client

package module
v0.1.0-alpha005 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2025 License: Apache-2.0 Imports: 21 Imported by: 5

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 uses Ping to 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

Examples

Constants

View Source 
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

View Source 
var DefaultClient = &Client{
	log:         defaultLogger,
	healthCheck: defaultHealthCheck,
}

DefaultClient is the default client for interacting with containers.

View Source 
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 

func AddSDKLabels(target map[string]string)

AddSDKLabels adds the SDK labels to target.

func IsPermanentClientError 

func IsPermanentClientError(err error) bool

IsPermanentClientError returns true if the error is a permanent client error.

func Version 

func Version() string

Version returns the version of the client package.

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 

func (c *Client) Client() (*client.Client, error)

Client returns the underlying docker client. It verifies that the client is initialized. It is safe to call this method concurrently.

func (*Client) Close 

func (c *Client) Close() error

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) DaemonHost 

func (c *Client) DaemonHost(ctx context.Context) (string, error)

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 

func (c *Client) Info(ctx context.Context) (system.Info, error)

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) Logger 

func (c *Client) Logger() *slog.Logger

Logger returns the logger for the client.

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) NetworkList 

func (c *Client) NetworkList(ctx context.Context, options network.ListOptions) ([]network.Summary, error)

NetworkList lists networks

func (*Client) NetworkRemove 

func (c *Client) NetworkRemove(ctx context.Context, name string) error

NetworkRemove removes a network

func (*Client) VolumeRemove 

func (c *Client) VolumeRemove(ctx context.Context, volumeID string, force bool) error

VolumeRemove removes a volume.

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.