From a2eb5a81895f65aba13923150fe776dc429f7c62 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 11 Mar 2026 16:22:17 +0100 Subject: [PATCH] engine: slight tweaks to client sdk examples I noticed that building the examples would produce a client with the default ("Go-http-client/1.1") User-Agent; this is something to look into (probably should have a saner default), but regardless, it's good practice to set your own; - Update examples to show setting the User-Agent - Use "log.Fatal" instead of "panic"; both exit the binary, but probably are slightly more readable. - Use the authconfig.Encode utility, which codifies the canonical format to encode the JSON, so that users don't have to replicate the same format. Signed-off-by: Sebastiaan van Stijn --- content/reference/api/engine/sdk/examples.md | 98 +++++++++++--------- 1 file changed, 52 insertions(+), 46 deletions(-) diff --git a/content/reference/api/engine/sdk/examples.md b/content/reference/api/engine/sdk/examples.md index 2f5f1e7151..ec334af59e 100644 --- a/content/reference/api/engine/sdk/examples.md +++ b/content/reference/api/engine/sdk/examples.md @@ -39,6 +39,7 @@ package main import ( "context" "io" + "log" "os" "github.com/moby/moby/api/pkg/stdcopy" @@ -48,15 +49,15 @@ import ( func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() reader, err := apiClient.ImagePull(ctx, "docker.io/library/alpine", client.ImagePullOptions{}) if err != nil { - panic(err) + log.Fatal(err) } defer reader.Close() @@ -73,25 +74,25 @@ func main() { Image: "alpine", }) if err != nil { - panic(err) + log.Fatal(err) } if _, err := apiClient.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil { - panic(err) + log.Fatal(err) } wait := apiClient.ContainerWait(ctx, resp.ID, client.ContainerWaitOptions{}) select { case err := <-wait.Error: if err != nil { - panic(err) + log.Fatal(err) } case <-wait.Result: } out, err := apiClient.ContainerLogs(ctx, resp.ID, client.ContainerLogsOptions{ShowStdout: true}) if err != nil { - panic(err) + log.Fatal(err) } stdcopy.StdCopy(os.Stdout, os.Stderr, out) @@ -155,6 +156,7 @@ import ( "context" "fmt" "io" + "log" "os" "github.com/moby/moby/client" @@ -162,9 +164,9 @@ import ( func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() @@ -172,20 +174,21 @@ func main() { out, err := apiClient.ImagePull(ctx, imageName, client.ImagePullOptions{}) if err != nil { - panic(err) + log.Fatal(err) } defer out.Close() + io.Copy(os.Stdout, out) resp, err := apiClient.ContainerCreate(ctx, client.ContainerCreateOptions{ Image: imageName, }) if err != nil { - panic(err) + log.Fatal(err) } if _, err := apiClient.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil { - panic(err) + log.Fatal(err) } fmt.Println(resp.ID) @@ -231,21 +234,22 @@ package main import ( "context" "fmt" + "log" "github.com/moby/moby/client" ) func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() containers, err := apiClient.ContainerList(ctx, client.ContainerListOptions{}) if err != nil { - panic(err) + log.Fatal(err) } for _, container := range containers.Items { @@ -300,28 +304,29 @@ package main import ( "context" "fmt" + "log" "github.com/moby/moby/client" ) func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() containers, err := apiClient.ContainerList(ctx, client.ContainerListOptions{}) if err != nil { - panic(err) + log.Fatal(err) } for _, container := range containers.Items { fmt.Print("Stopping container ", container.ID[:10], "... ") noWaitTimeout := 0 // to not wait for the container to exit gracefully if _, err := apiClient.ContainerStop(ctx, container.ID, client.ContainerStopOptions{Timeout: &noWaitTimeout}); err != nil { - panic(err) + log.Fatal(err) } fmt.Println("Success") } @@ -372,6 +377,7 @@ package main import ( "context" "io" + "log" "os" "github.com/moby/moby/client" @@ -379,9 +385,9 @@ import ( func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() @@ -389,7 +395,7 @@ func main() { // Replace this ID with a container that really exists out, err := apiClient.ContainerLogs(ctx, "f1064a8a4c82", options) if err != nil { - panic(err) + log.Fatal(err) } io.Copy(os.Stdout, out) @@ -434,21 +440,22 @@ package main import ( "context" "fmt" + "log" "github.com/moby/moby/client" ) func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() images, err := apiClient.ImageList(ctx, client.ImageListOptions{}) if err != nil { - panic(err) + log.Fatal(err) } for _, image := range images.Items { @@ -495,6 +502,7 @@ package main import ( "context" "io" + "log" "os" "github.com/moby/moby/client" @@ -502,17 +510,16 @@ import ( func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() out, err := apiClient.ImagePull(ctx, "alpine", client.ImagePullOptions{}) if err != nil { - panic(err) + log.Fatal(err) } - defer out.Close() io.Copy(os.Stdout, out) @@ -561,39 +568,37 @@ package main import ( "context" - "encoding/base64" - "encoding/json" "io" + "log" "os" + "github.com/moby/moby/api/pkg/authconfig" "github.com/moby/moby/api/types/registry" "github.com/moby/moby/client" ) func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() - authConfig := registry.AuthConfig{ + authStr, err := authconfig.Encode(registry.AuthConfig{ Username: "username", Password: "password", - } - encodedJSON, err := json.Marshal(authConfig) + }) if err != nil { - panic(err) + log.Fatal(err) } - authStr := base64.URLEncoding.EncodeToString(encodedJSON) out, err := apiClient.ImagePull(ctx, "alpine", client.ImagePullOptions{RegistryAuth: authStr}) if err != nil { - panic(err) + log.Fatal(err) } - defer out.Close() + io.Copy(os.Stdout, out) } ``` @@ -652,6 +657,7 @@ package main import ( "context" "fmt" + "log" "github.com/moby/moby/api/types/container" "github.com/moby/moby/client" @@ -659,9 +665,9 @@ import ( func main() { ctx := context.Background() - apiClient, err := client.New(client.FromEnv) + apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0")) if err != nil { - panic(err) + log.Fatal(err) } defer apiClient.Close() @@ -672,25 +678,25 @@ func main() { Image: "alpine", }) if err != nil { - panic(err) + log.Fatal(err) } if _, err := apiClient.ContainerStart(ctx, createResp.ID, client.ContainerStartOptions{}); err != nil { - panic(err) + log.Fatal(err) } wait := apiClient.ContainerWait(ctx, createResp.ID, client.ContainerWaitOptions{}) select { case err := <-wait.Error: if err != nil { - panic(err) + log.Fatal(err) } case <-wait.Result: } commitResp, err := apiClient.ContainerCommit(ctx, createResp.ID, client.ContainerCommitOptions{Reference: "helloworld"}) if err != nil { - panic(err) + log.Fatal(err) } fmt.Println(commitResp.ID)