docker

package module
v0.0.0-...-417fa16 Latest Latest
Warning

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

Go to latest
Published: Feb 4, 2014 License: BSD-2-Clause Imports: 19 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: http://docs.docker.io/en/latest/api/docker_remote_api.

##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)
        }
}

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

This section is empty.

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 (
	ErrNoSuchImage         = errors.New("No such image")
	ErrMissingRepo         = errors.New("Missing remote repository e.g. 'github.com/user/repo'")
	ErrMissingOutputStream = errors.New("Missing output-stream")
)

Error returned when the image does not exist.

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 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"`
}

This work with api verion < v1.7 and > v1.9

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:"-"`
	RawTerminal  bool      `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
}

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"`
	Remote         string    `qs:"remote"`
	SuppressOutput bool      `qs:"q"`
	OutputStream   io.Writer `qs:"-"`
}

BuildImageOptions present the set of informations available for building an image from a tarball's url.

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

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

func (c *Client) GetImageTarball(imageName string, w io.Writer) error

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(id string) 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) PostImageTarball

func (c *Client) PostImageTarball(r io.Reader) error

func (*Client) PullImage

func (c *Client) PullImage(opts PullImageOptions) 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) 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) 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
}

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
	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
}

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
}

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"`

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

80/tcp

func (Port) Port

func (p Port) Port() string

func (Port) Proto

func (p Port) Proto() string

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
	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"`
}

RemoveContainerOptions encapsulates options to remove a container.

type State

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

func (*State) String

func (s *State) String() string

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