README
¶
Docker Client
This package provides a client for the Docker API.
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
- Variables
- func AddSDKLabels(target map[string]string)
- func IsPermanentClientError(err error) bool
- func Version() string
- type Client
- func (c *Client) Client() (*client.Client, error)
- func (c *Client) Close() error
- func (c *Client) ContainerCreate(ctx context.Context, config *container.Config, ...) (container.CreateResponse, error)
- func (c *Client) ContainerExecAttach(ctx context.Context, execID string, config container.ExecAttachOptions) (types.HijackedResponse, error)
- func (c *Client) ContainerExecCreate(ctx context.Context, containerID string, options container.ExecOptions) (container.ExecCreateResponse, error)
- func (c *Client) ContainerExecInspect(ctx context.Context, execID string) (container.ExecInspect, error)
- func (c *Client) ContainerInspect(ctx context.Context, containerID string) (container.InspectResponse, error)
- func (c *Client) ContainerLogs(ctx context.Context, containerID string, options container.LogsOptions) (io.ReadCloser, error)
- func (c *Client) ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
- func (c *Client) ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
- func (c *Client) ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error
- func (c *Client) CopyFromContainer(ctx context.Context, containerID, srcPath string) (io.ReadCloser, container.PathStat, error)
- func (c *Client) CopyToContainer(ctx context.Context, containerID, dstPath string, content io.Reader, ...) error
- func (c *Client) DaemonHost(ctx context.Context) (string, error)
- func (c *Client) ImageInspect(ctx context.Context, imageID string, inspectOpts ...client.ImageInspectOption) (image.InspectResponse, error)
- func (c *Client) ImagePull(ctx context.Context, image string, options image.PullOptions) (io.ReadCloser, error)
- func (c *Client) Info(ctx context.Context) (system.Info, error)
- func (c *Client) Logger() *slog.Logger
- func (c *Client) NetworkConnect(ctx context.Context, networkID, containerID string, ...) error
- func (c *Client) NetworkCreate(ctx context.Context, name string, options network.CreateOptions) (network.CreateResponse, error)
- func (c *Client) NetworkInspect(ctx context.Context, name string, options network.InspectOptions) (network.Inspect, error)
- func (c *Client) NetworkRemove(ctx context.Context, name string) error
- func (c *Client) VolumeRemove(ctx context.Context, volumeID string, force bool) error
- type ClientOption
- func FromDockerOpt(opt client.Opt) ClientOption
- func NewClientOption(f func(*Client) error) 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 *Client) error) ClientOption
- func WithLogger(log *slog.Logger) ClientOption
Examples ¶
Constants ¶
const ( // LabelBase is the base label for all Docker labels. LabelBase = "com.docker.sdk" // LabelLang specifies the language which created the container. LabelLang = LabelBase + ".lang" // LabelVersion specifies the version of testcontainers which created the container. LabelVersion = LabelBase + ".version" )
Variables ¶
var DefaultClient = &Client{
log: defaultLogger,
healthCheck: defaultHealthCheck,
}
DefaultClient is the default client for interacting with containers.
var SDKLabels = map[string]string{ LabelBase: "true", LabelLang: "go", LabelVersion: Version(), }
SDKLabels returns a map of labels that can be used to identify resources created by this library.
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 Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a type that represents a client for interacting with containers.
func New ¶
func New(ctx context.Context, options ...ClientOption) (*Client, 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"
"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())
if err != nil {
log.Printf("error getting info: %s", err)
return
}
fmt.Println(info.OperatingSystem != "")
}
Output: true
func (*Client) Client ¶
Client returns the underlying docker client. It verifies that the client is initialized. It is safe to call this method concurrently.
func (*Client) Close ¶
Close closes the client. This method is safe for concurrent use by multiple goroutines.
func (*Client) ContainerCreate ¶
func (c *Client) ContainerCreate(ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *ocispec.Platform, name string) (container.CreateResponse, error)
ContainerCreate creates a new container.
func (*Client) ContainerExecAttach ¶
func (c *Client) ContainerExecAttach(ctx context.Context, execID string, config container.ExecAttachOptions) (types.HijackedResponse, error)
ContainerExecStart starts a new exec instance.
func (*Client) ContainerExecCreate ¶
func (c *Client) ContainerExecCreate(ctx context.Context, containerID string, options container.ExecOptions) (container.ExecCreateResponse, error)
ContainerExecCreate creates a new exec instance.
func (*Client) ContainerExecInspect ¶
func (c *Client) ContainerExecInspect(ctx context.Context, execID string) (container.ExecInspect, error)
ContainerExecInspect inspects a exec instance.
func (*Client) ContainerInspect ¶
func (c *Client) ContainerInspect(ctx context.Context, containerID string) (container.InspectResponse, error)
ContainerInspect inspects a container.
func (*Client) ContainerLogs ¶
func (c *Client) ContainerLogs(ctx context.Context, containerID string, options container.LogsOptions) (io.ReadCloser, error)
ContainerLogs returns the logs of a container.
func (*Client) ContainerRemove ¶
func (c *Client) ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
ContainerRemove removes a container.
func (*Client) ContainerStart ¶
func (c *Client) ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
ContainerStart starts a container.
func (*Client) ContainerStop ¶
func (c *Client) ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error
ContainerStop stops a container.
func (*Client) CopyFromContainer ¶
func (c *Client) CopyFromContainer(ctx context.Context, containerID, srcPath string) (io.ReadCloser, container.PathStat, error)
CopyFromContainer copies a file from a container.
func (*Client) CopyToContainer ¶
func (c *Client) CopyToContainer(ctx context.Context, containerID, dstPath string, content io.Reader, options container.CopyToContainerOptions) error
ContainerLogs returns the logs of a container.
func (*Client) ImageInspect ¶
func (c *Client) ImageInspect(ctx context.Context, imageID string, inspectOpts ...client.ImageInspectOption) (image.InspectResponse, error)
ImageInspect inspects an image.
func (*Client) ImagePull ¶
func (c *Client) ImagePull(ctx context.Context, image string, options image.PullOptions) (io.ReadCloser, error)
ImagePull pulls an image from a remote registry.
func (*Client) Info ¶
Info returns information about the docker server. The result of Info is cached and reused every time Info is called. It will also print out the docker server info, and the resolved Docker paths, to the default logger.
func (*Client) NetworkConnect ¶
func (c *Client) NetworkConnect(ctx context.Context, networkID, containerID string, config *network.EndpointSettings) error
NetworkConnect connects a container to a network
func (*Client) NetworkCreate ¶
func (c *Client) NetworkCreate(ctx context.Context, name string, options network.CreateOptions) (network.CreateResponse, error)
NetworkCreate creates a new network
func (*Client) NetworkInspect ¶
func (c *Client) NetworkInspect(ctx context.Context, name string, options network.InspectOptions) (network.Inspect, error)
NetworkInspect inspects a network
func (*Client) NetworkRemove ¶
NetworkRemove removes a network
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(*Client) 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 NewClientOption ¶
func NewClientOption(f func(*Client) error) ClientOption
NewClientOption creates a new ClientOption from a function
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 *Client) 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.
Source Files