docker

Documentation

Overview

Package docker provides the Docker container management provider using the Docker Engine API.

Package docker provides the Docker container management provider.

Index

• type APIClient
• type ActionResult
• type Client
  • func New() (*Client, error)
  • func NewWithClient(client APIClient) *Client
  • func (d *Client) Create(ctx context.Context, params CreateParams) (*Container, error)
  • func (d *Client) Exec(ctx context.Context, id string, params ExecParams) (*ExecResult, error)
  • func (d *Client) ImageRemove(ctx context.Context, imageName string, force bool) (*ActionResult, error)
  • func (d *Client) Inspect(ctx context.Context, id string) (*ContainerDetail, error)
  • func (d *Client) List(ctx context.Context, params ListParams) ([]Container, error)
  • func (d *Client) Ping(ctx context.Context) error
  • func (d *Client) Pull(ctx context.Context, imageName string) (*PullResult, error)
  • func (d *Client) Remove(ctx context.Context, id string, force bool) (*ActionResult, error)
  • func (d *Client) Start(ctx context.Context, id string) (*ActionResult, error)
  • func (d *Client) Stop(ctx context.Context, id string, timeout *time.Duration) (*ActionResult, error)
• type Container
• type ContainerDetail
• type CreateParams
• type ExecParams
• type ExecResult
• type ListParams
• type NetworkSettings
• type PortMapping
• type Provider
• type PullResult
• type VolumeMapping

Types

type APIClient

type APIClient interface {
	ContainerCreate(
		ctx context.Context,
		config *container.Config,
		hostConfig *container.HostConfig,
		networkingConfig *network.NetworkingConfig,
		platform *ocispec.Platform,
		containerName string,
	) (container.CreateResponse, error)
	ContainerStart(
		ctx context.Context,
		containerID string,
		options container.StartOptions,
	) error
	ContainerStop(
		ctx context.Context,
		containerID string,
		options container.StopOptions,
	) error
	ContainerRemove(
		ctx context.Context,
		containerID string,
		options container.RemoveOptions,
	) error
	ContainerList(
		ctx context.Context,
		options container.ListOptions,
	) ([]container.Summary, error)
	ContainerInspect(
		ctx context.Context,
		containerID string,
	) (container.InspectResponse, error)
	ContainerExecCreate(
		ctx context.Context,
		container string,
		options container.ExecOptions,
	) (common.IDResponse, error)
	ContainerExecAttach(
		ctx context.Context,
		execID string,
		options container.ExecStartOptions,
	) (types.HijackedResponse, error)
	ContainerExecInspect(
		ctx context.Context,
		execID string,
	) (container.ExecInspect, error)
	ImagePull(
		ctx context.Context,
		ref string,
		options image.PullOptions,
	) (io.ReadCloser, error)
	ImageInspect(
		ctx context.Context,
		imageID string,
		options ...dockerclient.ImageInspectOption,
	) (image.InspectResponse, error)
	ImageRemove(
		ctx context.Context,
		imageID string,
		options image.RemoveOptions,
	) ([]image.DeleteResponse, error)
	Ping(
		ctx context.Context,
	) (types.Ping, error)
}

APIClient defines the subset of the Docker Engine API used by this provider.

type ActionResult

type ActionResult struct {
	Message string `json:"message"`
	Changed bool   `json:"changed"`
}

ActionResult holds the result of a lifecycle action (start, stop, remove).

type Client

type Client struct {
	provider.FactsAware
	// contains filtered or unexported fields
}

Client implements Driver using the Docker Engine API.

func New

func New() (*Client, error)

New creates a new Docker provider using default client options.

func NewWithClient

func NewWithClient(
	client APIClient,
) *Client

NewWithClient creates a Docker provider with an injected client (for testing).

func (*Client) Create

func (d *Client) Create(
	ctx context.Context,
	params CreateParams,
) (*Container, error)

Create creates a new container from the given parameters.

func (*Client) Exec

func (d *Client) Exec(
	ctx context.Context,
	id string,
	params ExecParams,
) (*ExecResult, error)

Exec executes a command in a running container.

func (*Client) ImageRemove

func (d *Client) ImageRemove(
	ctx context.Context,
	imageName string,
	force bool,
) (*ActionResult, error)

ImageRemove removes a container image from the local Docker daemon.

func (*Client) Inspect

func (d *Client) Inspect(
	ctx context.Context,
	id string,
) (*ContainerDetail, error)

Inspect returns detailed information about a container.

func (*Client) List

func (d *Client) List(
	ctx context.Context,
	params ListParams,
) ([]Container, error)

List returns a list of containers matching the given parameters.

func (*Client) Ping

func (d *Client) Ping(
	ctx context.Context,
) error

Ping verifies connectivity to the Docker daemon.

func (*Client) Pull

func (d *Client) Pull(
	ctx context.Context,
	imageName string,
) (*PullResult, error)

Pull pulls a container image from a registry. Compares the image digest before and after the pull to determine if anything changed.

func (*Client) Remove

func (d *Client) Remove(
	ctx context.Context,
	id string,
	force bool,
) (*ActionResult, error)

Remove removes a container.

func (*Client) Start

func (d *Client) Start(
	ctx context.Context,
	id string,
) (*ActionResult, error)

Start starts a stopped container.

func (*Client) Stop

func (d *Client) Stop(
	ctx context.Context,
	id string,
	timeout *time.Duration,
) (*ActionResult, error)

Stop stops a running container with an optional timeout.

type Container

type Container struct {
	ID      string    `json:"id"`
	Name    string    `json:"name"`
	Image   string    `json:"image"`
	State   string    `json:"state"`
	Created time.Time `json:"created"`
	Changed bool      `json:"changed"`
}

Container holds summary info for a container.

type ContainerDetail

type ContainerDetail struct {
	Container
	NetworkSettings *NetworkSettings `json:"network_settings,omitempty"`
	Ports           []PortMapping    `json:"ports,omitempty"`
	Mounts          []VolumeMapping  `json:"mounts,omitempty"`
	Health          string           `json:"health,omitempty"`
}

ContainerDetail holds detailed info for a container.

type CreateParams

type CreateParams struct {
	// Image is the container image (required).
	Image string `json:"image"`
	// Name is an optional container name.
	Name string `json:"name,omitempty"`
	// Hostname sets the container hostname.
	Hostname string `json:"hostname,omitempty"`
	// DNS sets custom DNS servers for the container.
	DNS []string `json:"dns,omitempty"`
	// Command overrides the image's default command.
	Command []string `json:"command,omitempty"`
	// Env sets environment variables.
	Env map[string]string `json:"env,omitempty"`
	// Ports maps host ports to container ports.
	Ports []PortMapping `json:"ports,omitempty"`
	// Volumes maps host paths to container paths.
	Volumes []VolumeMapping `json:"volumes,omitempty"`
	// AutoStart starts the container after creation.
	AutoStart bool `json:"auto_start,omitempty"`
}

CreateParams contains parameters for container creation.

type ExecParams

type ExecParams struct {
	// Command is the command and arguments.
	Command []string `json:"command"`
	// Env sets environment variables.
	Env map[string]string `json:"env,omitempty"`
	// WorkingDir sets the working directory.
	WorkingDir string `json:"working_dir,omitempty"`
}

ExecParams contains parameters for executing a command in a container.

type ExecResult

type ExecResult struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exit_code"`
	Changed  bool   `json:"changed"`
}

ExecResult contains the output of a command execution in a container.

type ListParams

type ListParams struct {
	// State filters by container state: "running", "stopped", "all".
	State string `json:"state,omitempty"`
	// Limit caps the number of results.
	Limit int `json:"limit,omitempty"`
}

ListParams contains parameters for listing containers.

type NetworkSettings

type NetworkSettings struct {
	IPAddress string `json:"ip_address,omitempty"`
	Gateway   string `json:"gateway,omitempty"`
}

NetworkSettings holds container network configuration.

type PortMapping

type PortMapping struct {
	Host      int `json:"host"`
	Container int `json:"container"`
}

PortMapping maps a host port to a container port.

type Provider

type Provider interface {
	Ping(
		ctx context.Context,
	) error

	Create(
		ctx context.Context,
		params CreateParams,
	) (*Container, error)

	Start(
		ctx context.Context,
		id string,
	) (*ActionResult, error)

	Stop(
		ctx context.Context,
		id string,
		timeout *time.Duration,
	) (*ActionResult, error)

	Remove(
		ctx context.Context,
		id string,
		force bool,
	) (*ActionResult, error)

	List(
		ctx context.Context,
		params ListParams,
	) ([]Container, error)

	Inspect(
		ctx context.Context,
		id string,
	) (*ContainerDetail, error)

	Exec(
		ctx context.Context,
		id string,
		params ExecParams,
	) (*ExecResult, error)

	Pull(
		ctx context.Context,
		image string,
	) (*PullResult, error)

	ImageRemove(
		ctx context.Context,
		image string,
		force bool,
	) (*ActionResult, error)
}

Provider defines the Docker container management interface. All methods accept context.Context for cancellation and timeout propagation, which is important since the Docker daemon is a remote service.

type PullResult

type PullResult struct {
	ImageID string `json:"image_id"`
	Tag     string `json:"tag"`
	Size    int64  `json:"size"`
	Changed bool   `json:"changed"`
}

PullResult contains the result of an image pull.

type VolumeMapping

type VolumeMapping struct {
	Host      string `json:"host"`
	Container string `json:"container"`
}

VolumeMapping maps a host path to a container path.