README
¶
Docker Client
This package provides a client for the Docker API.
Installation
go get github.com/docker/go-sdk/client
Usage
The library provides a default client that is initialised with the current docker context. It uses a default logger that is configured to print to the standard output using the slog package.
cli := client.DefaultClient
It's also possible to create a new client, with optional configuration:
cli, err := client.New(context.Background())
if err != nil {
log.Fatalf("failed to create docker client: %v", err)
}
// Close the docker client when done
defer cli.Close()
Customizing the client
The client created with the New function can be customized using functional options. The following options are available:
WithHealthCheck(healthCheck func(ctx context.Context) func(c *Client) error) ClientOption: A healthcheck function that is called to check the health of the client. By default, the client usesPingto check the health of the client.WithDockerHost(dockerHost string) ClientOption: The docker host to use. By default, the client uses the current docker host.WithDockerContext(dockerContext string) ClientOption: The docker context to use. By default, the client uses the current docker context.
In the case that both the docker host and the docker context are provided, the docker context takes precedence.
Documentation
¶
Index ¶
- Constants
- func AddSDKLabels(target map[string]string)
- func IsPermanentClientError(err error) bool
- func SDKLabels() map[string]string
- func Version() string
- type ClientOption
- func FromDockerOpt(opt client.Opt) ClientOption
- func WithDockerAPI(api client.APIClient) ClientOption
- func WithDockerContext(dockerContext string) ClientOption
- func WithDockerHost(dockerHost string) ClientOption
- func WithExtraHeaders(headers map[string]string) ClientOption
- func WithHealthCheck(healthCheck func(ctx context.Context) func(c SDKClient) error) ClientOption
- func WithLogger(log *slog.Logger) ClientOption
- type SDKClient
Examples ¶
Constants ¶
const ( // LabelBase is the base label for all Docker SDK labels. LabelBase = "com.docker.sdk" // LabelLang specifies the language. LabelLang = LabelBase + ".lang" // LabelVersion specifies the version of go-sdk's client. LabelVersion = LabelBase + ".client" )
Variables ¶
This section is empty.
Functions ¶
func AddSDKLabels ¶
AddSDKLabels adds the SDK labels to target.
func IsPermanentClientError ¶
IsPermanentClientError returns true if the error is a permanent client error.
Types ¶
type ClientOption ¶
type ClientOption interface {
// Apply applies the option to the client.
// This method is used to make ClientOption compatible with docker's Opt type.
Apply(*sdkClient) error
}
ClientOption is a type that represents an option for configuring a client. It is compatible with docker's Opt type.
func FromDockerOpt ¶
func FromDockerOpt(opt client.Opt) ClientOption
FromDockerOpt converts a docker Opt to our ClientOption
func WithDockerAPI ¶
func WithDockerAPI(api client.APIClient) ClientOption
WithDockerAPI returns a client option that sets the docker client used to access Docker API.
func WithDockerContext ¶
func WithDockerContext(dockerContext string) ClientOption
WithDockerContext returns a client option that sets the docker context for the client. If set, the client will use the docker context to determine the docker host. If used in combination with WithDockerHost, the host in the context will take precedence.
func WithDockerHost ¶
func WithDockerHost(dockerHost string) ClientOption
WithDockerHost returns a client option that sets the docker host for the client.
func WithExtraHeaders ¶
func WithExtraHeaders(headers map[string]string) ClientOption
WithExtraHeaders returns a client option that sets the extra headers for the client.
func WithHealthCheck ¶
func WithHealthCheck(healthCheck func(ctx context.Context) func(c SDKClient) error) ClientOption
WithHealthCheck returns a client option that sets the health check for the client. If not set, the default health check will be used, which retries the ping to the docker daemon until it is ready, three times, or the context is done.
func WithLogger ¶
func WithLogger(log *slog.Logger) ClientOption
WithLogger returns a client option that sets the logger for the client.
type SDKClient ¶
type SDKClient interface {
client.APIClient
// Logger returns the logger for the client.
Logger() *slog.Logger
// DaemonHostWithContext gets the host or ip of the Docker daemon where ports are exposed on
DaemonHostWithContext(ctx context.Context) (string, error)
// FindContainerByName finds a container by name.
FindContainerByName(ctx context.Context, name string) (*container.Summary, error)
}
SDKClient extends SDKClient with higher-level functions
func New ¶
func New(ctx context.Context, options ...ClientOption) (SDKClient, error)
New returns a new client for interacting with containers. The client is configured using the provided options, that must be compatible with docker's client.Opt type.
The Docker host is automatically resolved reading it from the current docker context; in case you need to pass client.Opt options that override the docker host, you can do so by providing the FromDockerOpt options adapter. E.g.
cli, err := client.New(context.Background(), client.FromDockerOpt(client.WithHost("tcp://foobar:2375")))
The client uses a logger that is initialized to io.Discard; you can change it by providing the WithLogger option. E.g.
cli, err := client.New(context.Background(), client.WithLogger(slog.Default()))
The client is safe for concurrent use by multiple goroutines.
Example ¶
package main
import (
"context"
"fmt"
"log"
dockerclient "github.com/moby/moby/client"
"github.com/docker/go-sdk/client"
)
func main() {
cli, err := client.New(context.Background())
if err != nil {
log.Printf("error creating client: %s", err)
return
}
info, err := cli.Info(context.Background(), dockerclient.InfoOptions{})
if err != nil {
log.Printf("error getting info: %s", err)
return
}
fmt.Println(info.Info.OperatingSystem != "")
}
Output: true
Source Files