docker

package
v0.0.0-...-a541f19 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2023 License: Apache-2.0, BSD-2-Clause Imports: 21 Imported by: 0

README

#go-dockerclient

Build Status Build Status

GoDoc

This package presents a client for the Docker remote API.

For more details, check the remote API documentation.

##Versioning

  • Version 0.1 is compatible with Docker v0.7.1
  • The master is compatible with Docker's master

Example

package main

import (
        "fmt"
        "github.com/fsouza/go-dockerclient"
)

func main() {
        endpoint := "unix:///var/run/docker.sock"
        client, _ := docker.NewClient(endpoint)
        imgs, _ := client.ListImages(true)
        for _, img := range imgs {
                fmt.Println("ID: ", img.ID)
                fmt.Println("RepoTags: ", img.RepoTags)
                fmt.Println("Created: ", img.Created)
                fmt.Println("Size: ", img.Size)
                fmt.Println("VirtualSize: ", img.VirtualSize)
                fmt.Println("ParentId: ", img.ParentId)
                fmt.Println("Repository: ", img.Repository)
        }
}

Developing

You can run the tests with:

go get -d ./...
go test ./...

Documentation

Overview

Package docker provides a client for the Docker remote API.

See http://goo.gl/mxyql for more details on the remote API.

Index

Examples

Constants

View Source 
const (
	SIGABRT   = Signal(0x6)
	SIGALRM   = Signal(0xe)
	SIGBUS    = Signal(0x7)
	SIGCHLD   = Signal(0x11)
	SIGCLD    = Signal(0x11)
	SIGCONT   = Signal(0x12)
	SIGFPE    = Signal(0x8)
	SIGHUP    = Signal(0x1)
	SIGILL    = Signal(0x4)
	SIGINT    = Signal(0x2)
	SIGIO     = Signal(0x1d)
	SIGIOT    = Signal(0x6)
	SIGKILL   = Signal(0x9)
	SIGPIPE   = Signal(0xd)
	SIGPOLL   = Signal(0x1d)
	SIGPROF   = Signal(0x1b)
	SIGPWR    = Signal(0x1e)
	SIGQUIT   = Signal(0x3)
	SIGSEGV   = Signal(0xb)
	SIGSTKFLT = Signal(0x10)
	SIGSTOP   = Signal(0x13)
	SIGSYS    = Signal(0x1f)
	SIGTERM   = Signal(0xf)
	SIGTRAP   = Signal(0x5)
	SIGTSTP   = Signal(0x14)
	SIGTTIN   = Signal(0x15)
	SIGTTOU   = Signal(0x16)
	SIGUNUSED = Signal(0x1f)
	SIGURG    = Signal(0x17)
	SIGUSR1   = Signal(0xa)
	SIGUSR2   = Signal(0xc)
	SIGVTALRM = Signal(0x1a)
	SIGWINCH  = Signal(0x1c)
	SIGXCPU   = Signal(0x18)
	SIGXFSZ   = Signal(0x19)
)

These values represent all signals available on Linux, where containers will be running.

Variables

View Source 
var (
	// ErrInvalidEndpoint is returned when the endpoint is not a valid HTTP URL.
	ErrInvalidEndpoint = errors.New("invalid endpoint")

	// ErrConnectionRefused is returned when the client cannot connect to the given endpoint.
	ErrConnectionRefused = errors.New("cannot connect to Docker endpoint")
)
View Source 
var (
	// ErrNoListeners is the error returned when no listeners are available
	// to receive an event.
	ErrNoListeners = errors.New("no listeners present to receive event")

	// ErrListenerAlreadyExists is the error returned when the listerner already
	// exists.
	ErrListenerAlreadyExists = errors.New("listener already exists for docker events")
)
View Source 
var (
	// ErrNoSuchImage is the error returned when the image does not exist.
	ErrNoSuchImage = errors.New("no such image")

	// ErrMissingRepo is the error returned when the remote repository is
	// missing.
	ErrMissingRepo = errors.New("missing remote repository e.g. 'github.com/user/repo'")

	// ErrMissingOutputStream is the error returned when no output stream
	// is provided to some calls, like BuildImage.
	ErrMissingOutputStream = errors.New("missing output stream")
)

Functions

This section is empty.

Types

type APIContainers 

type APIContainers struct {
	ID         string `json:"Id"`
	Image      string
	Command    string
	Created    int64
	Status     string
	Ports      []APIPort
	SizeRw     int64
	SizeRootFs int64
	Names      []string
}

APIContainers represents a container.

See http://goo.gl/QeFH7U for more details.

type APIEvents 

type APIEvents struct {
	Status string
	ID     string
	From   string
	Time   int64
}

APIEvents represents an event returned by the API.

type APIImages 

type APIImages struct {
	ID          string   `json:"Id"`
	RepoTags    []string `json:",omitempty"`
	Created     int64
	Size        int64
	VirtualSize int64
	ParentId    string `json:",omitempty"`
	Repository  string `json:",omitempty"`
	Tag         string `json:",omitempty"`
}

APIImages represent an image returned in the ListImages call.

type APIPort 

type APIPort struct {
	PrivatePort int64
	PublicPort  int64
	Type        string
	IP          string
}

type AttachToContainerOptions 

type AttachToContainerOptions struct {
	Container    string    `qs:"-"`
	InputStream  io.Reader `qs:"-"`
	OutputStream io.Writer `qs:"-"`
	ErrorStream  io.Writer `qs:"-"`

	// Get container logs, sending it to OutputStream.
	Logs bool

	// Stream the response?
	Stream bool

	// Attach to stdin, and use InputFile.
	Stdin bool

	// Attach to stdout, and use OutputStream.
	Stdout bool

	// Attach to stderr, and use ErrorStream.
	Stderr bool

	// If set, after a successful connect, a sentinel will be sent and then the
	// client will block on receive before continuing.
	//
	// It must be an unbuffered channel. Using a buffered channel can lead
	// to unexpected behavior.
	Success chan struct{}
}

AttachToContainerOptions is the set of options that can be used when attaching to a container.

See http://goo.gl/oPzcqH for more details.

type AuthConfiguration 

type AuthConfiguration struct {
	Username string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`
	Email    string `json:"email,omitempty"`
}

AuthConfiguration represents authentication options to use in the PushImage method. It represents the authencation in the Docker index server.

type BuildImageOptions 

type BuildImageOptions struct {
	Name           string    `qs:"t"`
	NoCache        bool      `qs:"nocache"`
	SuppressOutput bool      `qs:"q"`
	RmTmpContainer bool      `qs:"rm"`
	InputStream    io.Reader `qs:"-"`
	OutputStream   io.Writer `qs:"-"`
	Remote         string    `qs:"remote"`
}

BuildImageOptions present the set of informations available for building an image from a tarfile with a Dockerfile in it,the details about Dockerfile see http://docs.docker.io/en/latest/reference/builder/

type Change 

type Change struct {
	Path string
	Kind ChangeType
}

Change represents a change in a container.

See http://goo.gl/DpGyzK for more details.

func (*Change) String 

func (change *Change) String() string

type ChangeType 

type ChangeType int
const (
	ChangeModify ChangeType = iota
	ChangeAdd
	ChangeDelete
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the basic type of this package. It provides methods for interaction with the API.

func NewClient 

func NewClient(endpoint string) (*Client, error)

NewClient returns a Client instance ready for communication with the given server endpoint.

func (*Client) AddEventListener 

func (c *Client) AddEventListener(listener chan<- *APIEvents) error

AddEventListener adds a new listener to container events in the Docker API.

The parameter is a channel through which events will be sent.

func (*Client) AttachToContainer 

func (c *Client) AttachToContainer(opts AttachToContainerOptions) error

AttachToContainer attaches to a container, using the given options.

See http://goo.gl/oPzcqH for more details.

Example 
client, err := docker.NewClient("http://localhost:4243")
if err != nil {
	log.Fatal(err)
}
// Reading logs from container a84849 and sending them to buf.
var buf bytes.Buffer
err = client.AttachToContainer(docker.AttachToContainerOptions{
	Container:    "a84849",
	OutputStream: &buf,
	Logs:         true,
	Stdout:       true,
	Stderr:       true,
})
if err != nil {
	log.Fatal(err)
}
log.Println(buf.String())
// Attaching to stdout and streaming.
buf.Reset()
err = client.AttachToContainer(docker.AttachToContainerOptions{
	Container:    "a84849",
	OutputStream: &buf,
	Stdout:       true,
	Stream:       true,
})
if err != nil {
	log.Fatal(err)
}
log.Println(buf.String())

Output:

func (*Client) BuildImage 

func (c *Client) BuildImage(opts BuildImageOptions) error

BuildImage builds an image from a tarball's url or a Dockerfile in the input stream.

Example 
client, err := docker.NewClient("http://localhost:4243")
if err != nil {
	log.Fatal(err)
}

t := time.Now()
inputbuf, outputbuf := bytes.NewBuffer(nil), bytes.NewBuffer(nil)
tr := tar.NewWriter(inputbuf)
tr.WriteHeader(&tar.Header{Name: "Dockerfile", Size: 10, ModTime: t, AccessTime: t, ChangeTime: t})
tr.Write([]byte("FROM base\n"))
tr.Close()
opts := docker.BuildImageOptions{
	Name:         "test",
	InputStream:  inputbuf,
	OutputStream: outputbuf,
}
if err := client.BuildImage(opts); err != nil {
	log.Fatal(err)
}

Output:

func (*Client) CommitContainer 

func (c *Client) CommitContainer(opts CommitContainerOptions) (*Image, error)

CommitContainer creates a new image from a container's changes.

See http://goo.gl/628gxm for more details.

func (*Client) ContainerChanges 

func (c *Client) ContainerChanges(id string) ([]Change, error)

ContainerChanges returns changes in the filesystem of the given container.

See http://goo.gl/DpGyzK for more details.

func (*Client) CopyFromContainer 

func (c *Client) CopyFromContainer(opts CopyFromContainerOptions) error

CopyFromContainer copy files or folders from a container, using a given resource.

See http://goo.gl/mnxRMl for more details.

Example 
client, err := docker.NewClient("http://localhost:4243")
if err != nil {
	log.Fatal(err)
}
cid := "a84849"
// Copy resulting file
var buf bytes.Buffer
filename := "/tmp/output.txt"
err = client.CopyFromContainer(docker.CopyFromContainerOptions{
	Container:    cid,
	Resource:     filename,
	OutputStream: &buf,
})
if err != nil {
	log.Fatalf("Error while copying from %s: %s\n", cid, err)
}
content := new(bytes.Buffer)
r := bytes.NewReader(buf.Bytes())
tr := tar.NewReader(r)
tr.Next()
if err != nil && err != io.EOF {
	log.Fatal(err)
}
if _, err := io.Copy(content, tr); err != nil {
	log.Fatal(err)
}
log.Println(buf.String())

Output:

func (*Client) CreateContainer 

func (c *Client) CreateContainer(opts CreateContainerOptions) (*Container, error)

CreateContainer creates a new container, returning the container instance, or an error in case of failure.

See http://goo.gl/tjihUc for more details.

func (*Client) ExportContainer 

func (c *Client) ExportContainer(opts ExportContainerOptions) error

ExportContainer export the contents of container id as tar archive and prints the exported contents to stdout.

See http://goo.gl/Lqk0FZ for more details.

func (*Client) ImportImage 

func (c *Client) ImportImage(opts ImportImageOptions) error

ImportImage imports an image from a url, a file or stdin

See http://goo.gl/PhBKnS for more details.

func (*Client) Info 

func (c *Client) Info() (*engine.Env, error)

Info returns system-wide information, like the number of running containers.

See http://goo.gl/LOmySw for more details.

func (*Client) InspectContainer 

func (c *Client) InspectContainer(id string) (*Container, error)

InspectContainer returns information about a container by its ID.

See http://goo.gl/2o52Sx for more details.

func (*Client) InspectImage 

func (c *Client) InspectImage(name string) (*Image, error)

InspectImage returns an image by its name or ID.

See http://goo.gl/pHEbma for more details.

func (*Client) KillContainer 

func (c *Client) KillContainer(opts KillContainerOptions) error

KillContainer kills a container, returning an error in case of failure.

See http://goo.gl/DPbbBy for more details.

func (*Client) ListContainers 

func (c *Client) ListContainers(opts ListContainersOptions) ([]APIContainers, error)

ListContainers returns a slice of containers matching the given criteria.

See http://goo.gl/QpCnDN for more details.

func (*Client) ListImages 

func (c *Client) ListImages(all bool) ([]APIImages, error)

ListImages returns the list of available images in the server.

See http://goo.gl/dkMrwP for more details.

func (*Client) PullImage 

func (c *Client) PullImage(opts PullImageOptions, auth AuthConfiguration) error

PullImage pulls an image from a remote registry, logging progress to w.

See http://goo.gl/PhBKnS for more details.

func (*Client) PushImage 

func (c *Client) PushImage(opts PushImageOptions, auth AuthConfiguration) error

PushImage pushes an image to a remote registry, logging progress to w.

An empty instance of AuthConfiguration may be used for unauthenticated pushes.

See http://goo.gl/GBmyhc for more details.

func (*Client) RemoveContainer 

func (c *Client) RemoveContainer(opts RemoveContainerOptions) error

RemoveContainer removes a container, returning an error in case of failure.

See http://goo.gl/PBvGdU for more details.

func (*Client) RemoveEventListener 

func (c *Client) RemoveEventListener(listener chan *APIEvents) error

RemoveEventListener removes a listener from the monitor.

func (*Client) RemoveImage 

func (c *Client) RemoveImage(name string) error

RemoveImage removes an image by its name or ID.

See http://goo.gl/7hjHHy for more details.

func (*Client) ResizeContainerTTY 

func (c *Client) ResizeContainerTTY(id string, height, width int) error

ResizeContainerTTY resizes the terminal to the given height and width.

func (*Client) RestartContainer 

func (c *Client) RestartContainer(id string, timeout uint) error

RestartContainer stops a container, killing it after the given timeout (in seconds), during the stop process.

See http://goo.gl/zms73Z for more details.

func (*Client) StartContainer 

func (c *Client) StartContainer(id string, hostConfig *HostConfig) error

StartContainer starts a container, returning an errror in case of failure.

See http://goo.gl/y5GZlE for more details.

func (*Client) StopContainer 

func (c *Client) StopContainer(id string, timeout uint) error

StopContainer stops a container, killing it after the given timeout (in seconds).

See http://goo.gl/X2mj8t for more details.

func (*Client) TagImage 

func (c *Client) TagImage(name string, opts TagImageOptions) error

TagImage adds a tag to the image 'name'

func (*Client) Version 

func (c *Client) Version() (*engine.Env, error)

Version returns version information about the docker server.

See http://goo.gl/IqKNRE for more details.

func (*Client) WaitContainer 

func (c *Client) WaitContainer(id string) (int, error)

WaitContainer blocks until the given container stops, return the exit code of the container status.

See http://goo.gl/gnHJL2 for more details.

type CommitContainerOptions 

type CommitContainerOptions struct {
	Container  string
	Repository string `qs:"repo"`
	Tag        string
	Message    string `qs:"m"`
	Author     string
	Run        *Config `qs:"-"`
}

CommitContainerOptions aggregates parameters to the CommitContainer method.

See http://goo.gl/628gxm for more details.

type Config 

type Config struct {
	Hostname        string
	Domainname      string
	User            string
	Memory          int64
	MemorySwap      int64
	CpuShares       int64
	AttachStdin     bool
	AttachStdout    bool
	AttachStderr    bool
	PortSpecs       []string
	ExposedPorts    map[Port]struct{}
	Tty             bool
	OpenStdin       bool
	StdinOnce       bool
	Env             []string
	Cmd             []string
	Dns             []string // For Docker API v1.9 and below only
	Image           string
	Volumes         map[string]struct{}
	VolumesFrom     string
	WorkingDir      string
	Entrypoint      []string
	NetworkDisabled bool
}

type Container 

type Container struct {
	ID string

	Created time.Time

	Path string
	Args []string

	Config *Config
	State  State
	Image  string

	NetworkSettings *NetworkSettings

	SysInitPath    string
	ResolvConfPath string
	HostnamePath   string
	HostsPath      string
	Name           string
	Driver         string

	Volumes    map[string]string
	VolumesRW  map[string]bool
	HostConfig *HostConfig
}

type CopyFromContainerOptions 

type CopyFromContainerOptions struct {
	OutputStream io.Writer `json:"-"`
	Container    string    `json:"-"`
	Resource     string
}

CopyFromContainerOptions is the set of options that can be used when copying files or folders from a container.

See http://goo.gl/mnxRMl for more details.

type CreateContainerOptions 

type CreateContainerOptions struct {
	Name   string
	Config *Config `qs:"-"`
}

CreateContainerOptions specify parameters to the CreateContainer function.

See http://goo.gl/WPPYtB for more details.

type Error 

type Error struct {
	Status  int
	Message string
}

Error represents failures in the API. It represents a failure from the API.

func (*Error) Error 

func (e *Error) Error() string

type ExportContainerOptions 

type ExportContainerOptions struct {
	ID           string
	OutputStream io.Writer
}

ExportContainerOptions is the set of parameters to the ExportContainer method.

See http://goo.gl/Lqk0FZ for more details.

type HostConfig 

type HostConfig struct {
	Binds           []string
	ContainerIDFile string
	LxcConf         []KeyValuePair
	Privileged      bool
	PortBindings    map[Port][]PortBinding
	Links           []string
	PublishAllPorts bool
	Dns             []string // For Docker API v1.10 and above only
}

type Image 

type Image struct {
	ID              string    `json:"id"`
	Parent          string    `json:"parent,omitempty"`
	Comment         string    `json:"comment,omitempty"`
	Created         time.Time `json:"created"`
	Container       string    `json:"container,omitempty"`
	ContainerConfig Config    `json:"container_config,omitempty"`
	DockerVersion   string    `json:"docker_version,omitempty"`
	Author          string    `json:"author,omitempty"`
	Config          *Config   `json:"config,omitempty"`
	Architecture    string    `json:"architecture,omitempty"`
	Size            int64
}

type ImportImageOptions 

type ImportImageOptions struct {
	Repository string `qs:"repo"`
	Source     string `qs:"fromSrc"`
	Tag        string `qs:"tag"`

	InputStream  io.Reader `qs:"-"`
	OutputStream io.Writer `qs:"-"`
}

ImportImageOptions present the set of informations available for importing an image from a source file or the stdin.

See http://goo.gl/PhBKnS for more details.

type KeyValuePair 

type KeyValuePair struct {
	Key   string
	Value string
}

type KillContainerOptions 

type KillContainerOptions struct {
	// The ID of the container.
	ID string `qs:"-"`

	// The signal to send to the container. When omitted, Docker server
	// will assume SIGKILL.
	Signal Signal
}

KillContainerOptions represents the set of options that can be used in a call to KillContainer.

type ListContainersOptions 

type ListContainersOptions struct {
	All    bool
	Size   bool
	Limit  int
	Since  string
	Before string
}

ListContainersOptions specify parameters to the ListContainers function.

See http://goo.gl/QpCnDN for more details.

type NetworkSettings 

type NetworkSettings struct {
	IPAddress   string
	IPPrefixLen int
	Gateway     string
	Bridge      string
	PortMapping map[string]PortMapping
	Ports       map[Port][]PortBinding
}

func (*NetworkSettings) PortMappingAPI 

func (settings *NetworkSettings) PortMappingAPI() []APIPort

type NoSuchContainer 

type NoSuchContainer struct {
	ID string
}

NoSuchContainer is the error returned when a given container does not exist.

func (NoSuchContainer) Error 

func (err NoSuchContainer) Error() string

type Port 

type Port string

Port represents the port number and the protocol, in the form <number>/<protocol>. For example: 80/tcp.

func (Port) Port 

func (p Port) Port() string

Port returns the number of the port.

func (Port) Proto 

func (p Port) Proto() string

Proto returns the name of the protocol.

type PortBinding 

type PortBinding struct {
	HostIp   string
	HostPort string
}

type PortMapping 

type PortMapping map[string]string

type PullImageOptions 

type PullImageOptions struct {
	Repository   string `qs:"fromImage"`
	Registry     string
	Tag          string
	OutputStream io.Writer `qs:"-"`
}

PullImageOptions present the set of options available for pulling an image from a registry.

See http://goo.gl/PhBKnS for more details.

type PushImageOptions 

type PushImageOptions struct {
	// Name of the image
	Name string

	// Registry server to push the image
	Registry string

	OutputStream io.Writer `qs:"-"`
}

PushImageOptions represents options to use in the PushImage method.

See http://goo.gl/GBmyhc for more details.

type RemoveContainerOptions 

type RemoveContainerOptions struct {
	// The ID of the container.
	ID string `qs:"-"`

	// A flag that indicates whether Docker should remove the volumes
	// associated to the container.
	RemoveVolumes bool `qs:"v"`

	// A flag that indicates whether Docker should remove the container
	// even if it is currently running.
	Force bool
}

RemoveContainerOptions encapsulates options to remove a container.

type Signal 

type Signal int

Signal represents a signal that can be send to the container on KillContainer call.

type State 

type State struct {
	sync.RWMutex
	Running    bool
	Pid        int
	ExitCode   int
	StartedAt  time.Time
	FinishedAt time.Time
	Ghost      bool
}

State represents the state of a container.

func (*State) String 

func (s *State) String() string

String returns the string representation of a state.

type TagImageOptions 

type TagImageOptions struct {
	Repo  string `qs:"repo"`
	Force bool   `qs:"force"`
}

TagImageOptions present the set of options to tag an image

Source Files

View all Source files

Directories

Path Synopsis
Package testing provides a fake implementation of the Docker API, useful for testing purpose.
 Package testing provides a fake implementation of the Docker API, useful for testing purpose.

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.