From 7a0b00a1889b5e44b8abeaa92583b00f1ac29647 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Thu, 22 Jun 2017 11:47:05 -0700 Subject: [PATCH] Add simple pull examples with auth (#3574) --- engine/api/get-started.md | 439 +++++++++++++++++++++++--------------- 1 file changed, 272 insertions(+), 167 deletions(-) diff --git a/engine/api/get-started.md b/engine/api/get-started.md index 519de27674..8b91b31228 100644 --- a/engine/api/get-started.md +++ b/engine/api/get-started.md @@ -104,49 +104,49 @@ print client.containers.run("alpine", ["echo", "hello", "world"]) package main import ( - "io" - "os" + "io" + "os" - "github.com/docker/docker/client" - "github.com/docker/docker/api/types" - "github.com/docker/docker/api/types/container" - "golang.org/x/net/context" + "github.com/docker/docker/client" + "github.com/docker/docker/api/types" + "github.com/docker/docker/api/types/container" + "golang.org/x/net/context" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - _, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) - if err != nil { - panic(err) - } + _, err = cli.ImagePull(ctx, "docker.io/library/alpine", types.ImagePullOptions{}) + if err != nil { + panic(err) + } - resp, err := cli.ContainerCreate(ctx, &container.Config{ - Image: "alpine", - Cmd: []string{"echo", "hello world"}, - }, nil, nil, "") - if err != nil { - panic(err) - } + resp, err := cli.ContainerCreate(ctx, &container.Config{ + Image: "alpine", + Cmd: []string{"echo", "hello world"}, + }, nil, nil, "") + if err != nil { + panic(err) + } - if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { - panic(err) - } + if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { + panic(err) + } - if _, err = cli.ContainerWait(ctx, resp.ID); err != nil { - panic(err) - } + if _, err = cli.ContainerWait(ctx, resp.ID); err != nil { + panic(err) + } - out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true}) - if err != nil { - panic(err) - } + out, err := cli.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true}) + if err != nil { + panic(err) + } - io.Copy(os.Stdout, out) + io.Copy(os.Stdout, out) } ``` @@ -201,43 +201,43 @@ print container.id package main import ( - "fmt" - "io" - "os" + "fmt" + "io" + "os" - "github.com/docker/docker/api/types" - "github.com/docker/docker/api/types/container" - "github.com/docker/docker/client" - "golang.org/x/net/context" + "github.com/docker/docker/api/types" + "github.com/docker/docker/api/types/container" + "github.com/docker/docker/client" + "golang.org/x/net/context" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - imageName := "bfirsh/reticulate-splines" + imageName := "bfirsh/reticulate-splines" - out, err := cli.ImagePull(ctx, imageName, types.ImagePullOptions{}) - if err != nil { - panic(err) - } - io.Copy(os.Stdout, out) + out, err := cli.ImagePull(ctx, imageName, types.ImagePullOptions{}) + if err != nil { + panic(err) + } + io.Copy(os.Stdout, out) - resp, err := cli.ContainerCreate(ctx, &container.Config{ - Image: imageName, - }, nil, nil, "") - if err != nil { - panic(err) - } + resp, err := cli.ContainerCreate(ctx, &container.Config{ + Image: imageName, + }, nil, nil, "") + if err != nil { + panic(err) + } - if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { - panic(err) - } + if err := cli.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{}); err != nil { + panic(err) + } - fmt.Println(resp.ID) + fmt.Println(resp.ID) } ``` @@ -286,27 +286,27 @@ for container in client.containers.list(): package main import ( - "context" - "fmt" + "context" + "fmt" - "github.com/docker/docker/api/types" - "github.com/docker/docker/client" + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" ) func main() { - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{}) - if err != nil { - panic(err) - } + containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{}) + if err != nil { + panic(err) + } - for _, container := range containers { - fmt.Println(container.ID) - } + for _, container := range containers { + fmt.Println(container.ID) + } } ``` @@ -356,29 +356,29 @@ for container in client.containers.list(): package main import ( - "context" + "context" - "github.com/docker/docker/api/types" - "github.com/docker/docker/client" + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - containers, err := cli.ContainerList(ctx, types.ContainerListOptions{}) - if err != nil { - panic(err) - } + containers, err := cli.ContainerList(ctx, types.ContainerListOptions{}) + if err != nil { + panic(err) + } - for _, container := range containers { - if err := cli.ContainerStop(ctx, container.ID, nil); err != nil { - panic(err) - } - } + for _, container := range containers { + if err := cli.ContainerStop(ctx, container.ID, nil); err != nil { + panic(err) + } + } } ``` @@ -430,28 +430,28 @@ print container.logs() package main import ( - "context" - "io" - "os" + "context" + "io" + "os" - "github.com/docker/docker/api/types" - "github.com/docker/docker/client" + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - options := types.ContainerLogsOptions{ShowStdout: true} - out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options) - if err != nil { - panic(err) - } + options := types.ContainerLogsOptions{ShowStdout: true} + out, err := cli.ContainerLogs(ctx, "f1064a8a4c82", options) + if err != nil { + panic(err) + } - io.Copy(os.Stdout, out) + io.Copy(os.Stdout, out) } ``` @@ -498,27 +498,27 @@ for image in client.images.list(): package main import ( - "context" - "fmt" + "context" + "fmt" - "github.com/docker/docker/api/types" - "github.com/docker/docker/client" + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" ) func main() { - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - images, err := cli.ImageList(context.Background(), types.ImageListOptions{}) - if err != nil { - panic(err) - } + images, err := cli.ImageList(context.Background(), types.ImageListOptions{}) + if err != nil { + panic(err) + } - for _, image := range images { - fmt.Println(image.ID) - } + for _, image := range images { + fmt.Println(image.ID) + } } ``` @@ -566,27 +566,29 @@ print image.id package main import ( - "io" - "os" + "io" + "os" - "github.com/docker/docker/api/types" - "github.com/docker/docker/client" - "golang.org/x/net/context" + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" + "golang.org/x/net/context" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{}) - if err != nil { - panic(err) - } + out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{}) + if err != nil { + panic(err) + } - io.Copy(os.Stdout, out) + defer out.Close() + + io.Copy(os.Stdout, out) } ``` @@ -606,6 +608,109 @@ $ curl --unix-socket /var/run/docker.sock \ + +### Pull images with authentication + +Pull images, like `docker pull`, with authentication: + +> **Note**: Credentials are sent in the clear. Docker's official registries use +> HTTPS. Private registries should also be configured to use HTTPS. + + + +
+
+ +The Python SDK retrieves authentication information from the [credentials +store](/engine/reference/commandline/login/#credentials-store) file and +integrates with [credential +helpers](https://github.com/docker/docker-credential-helpers){: target="_blank" +class="_" }. It is possible to override these credentials, but that is out of +scope for this Getting Started guide. After using `docker login`, the Python SDK +uses these credentials automatically. + +```python +import docker +client = docker.from_env() +image = client.images.pull("alpine") +print image.id +``` + +
+ +
+ +```go +package main + +import ( + "io" + "os" + "encoding/json" + "encoding/base64" + + "github.com/docker/docker/api/types" + "github.com/docker/docker/client" + "golang.org/x/net/context" +) + + +func main() { + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } + + authConfig := types.AuthConfig{ + Username: "username", + Password: "password", + } + encodedJSON, err := json.Marshal(authConfig) + if err != nil { + panic(err) + } + authStr := base64.URLEncoding.EncodeToString(encodedJSON) + + out, err := cli.ImagePull(ctx, "alpine", types.ImagePullOptions{RegistryAuth: + authStr}) + if err != nil { + panic(err) + } + + defer out.Close() + io.Copy(os.Stdout, out) +} +``` + +
+ +
+ +This example will leave the credentials in your shell's history, so consider +this a naive implementation. The credentials are passed as a Base-64-encoded +JSON structure. + +```bash +$ JSON=$(echo '{"username": "string", "password": "string", "serveraddress": "string"}' | base64) + +$ curl --unix-socket /var/run/docker.sock \ + -H "Content-Type: application/tar" + -X POST "http:/v1.24/images/create?fromImage=alpine" + -H "X-Registry-Auth" + -d "$JSON" +{"status":"Pulling from library/alpine","id":"3.1"} +{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"} +{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e ] 32.77 kB/2.244 MB","id":"8f13703509f7"} +... +``` + +
+
### Commit containers Commit containers to create images from their contents: @@ -636,43 +741,43 @@ print image.id package main import ( - "fmt" + "fmt" - "github.com/docker/docker/api/types" - "github.com/docker/docker/api/types/container" - "github.com/docker/docker/client" - "golang.org/x/net/context" + "github.com/docker/docker/api/types" + "github.com/docker/docker/api/types/container" + "github.com/docker/docker/client" + "golang.org/x/net/context" ) func main() { - ctx := context.Background() - cli, err := client.NewEnvClient() - if err != nil { - panic(err) - } + ctx := context.Background() + cli, err := client.NewEnvClient() + if err != nil { + panic(err) + } - createResp, err := cli.ContainerCreate(ctx, &container.Config{ - Image: "alpine", - Cmd: []string{"touch", "/helloworld"}, - }, nil, nil, "") - if err != nil { - panic(err) - } + createResp, err := cli.ContainerCreate(ctx, &container.Config{ + Image: "alpine", + Cmd: []string{"touch", "/helloworld"}, + }, nil, nil, "") + if err != nil { + panic(err) + } - if err := cli.ContainerStart(ctx, createResp.ID, types.ContainerStartOptions{}); err != nil { - panic(err) - } + if err := cli.ContainerStart(ctx, createResp.ID, types.ContainerStartOptions{}); err != nil { + panic(err) + } - if _, err = cli.ContainerWait(ctx, createResp.ID); err != nil { - panic(err) - } + if _, err = cli.ContainerWait(ctx, createResp.ID); err != nil { + panic(err) + } - commitResp, err := cli.ContainerCommit(ctx, createResp.ID, types.ContainerCommitOptions{Reference: "helloworld"}) - if err != nil { - panic(err) - } + commitResp, err := cli.ContainerCommit(ctx, createResp.ID, types.ContainerCommitOptions{Reference: "helloworld"}) + if err != nil { + panic(err) + } - fmt.Println(commitResp.ID) + fmt.Println(commitResp.ID) } ```