2016-10-08 13:34:37 +00:00
|
|
|
/*
|
2016-11-15 19:45:20 +00:00
|
|
|
Package client is a Go client for the Docker Engine API.
|
2016-10-08 13:34:37 +00:00
|
|
|
|
|
|
|
The "docker" command uses this package to communicate with the daemon. It can also
|
|
|
|
be used by your own Go applications to do anything the command-line interface does
|
2016-11-11 19:51:26 +00:00
|
|
|
- running containers, pulling images, managing swarms, etc.
|
2016-10-08 13:34:37 +00:00
|
|
|
|
2016-11-15 19:45:20 +00:00
|
|
|
For more information about the Engine API, see the documentation:
|
|
|
|
https://docs.docker.com/engine/reference/api/
|
2016-10-08 13:34:37 +00:00
|
|
|
|
|
|
|
Usage
|
|
|
|
|
|
|
|
You use the library by creating a client object and calling methods on it. The
|
|
|
|
client can be created either from environment variables with NewEnvClient, or
|
|
|
|
configured manually with NewClient.
|
|
|
|
|
|
|
|
For example, to list running containers (the equivalent of "docker ps"):
|
|
|
|
|
|
|
|
package main
|
|
|
|
|
|
|
|
import (
|
|
|
|
"context"
|
|
|
|
"fmt"
|
|
|
|
|
|
|
|
"github.com/docker/docker/api/types"
|
|
|
|
"github.com/docker/docker/client"
|
|
|
|
)
|
|
|
|
|
|
|
|
func main() {
|
|
|
|
cli, err := client.NewEnvClient()
|
|
|
|
if err != nil {
|
|
|
|
panic(err)
|
|
|
|
}
|
|
|
|
|
|
|
|
containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
|
|
|
|
if err != nil {
|
|
|
|
panic(err)
|
|
|
|
}
|
|
|
|
|
|
|
|
for _, container := range containers {
|
|
|
|
fmt.Printf("%s %s\n", container.ID[:10], container.Image)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
*/
|
2016-09-06 18:46:37 +00:00
|
|
|
package client
|
|
|
|
|
|
|
|
import (
|
|
|
|
"fmt"
|
|
|
|
"net/http"
|
|
|
|
"net/url"
|
|
|
|
"os"
|
|
|
|
"path/filepath"
|
|
|
|
"strings"
|
|
|
|
|
2016-09-09 03:44:25 +00:00
|
|
|
"github.com/docker/go-connections/sockets"
|
2016-09-06 18:46:37 +00:00
|
|
|
"github.com/docker/go-connections/tlsconfig"
|
|
|
|
)
|
|
|
|
|
|
|
|
// DefaultVersion is the version of the current stable API
|
2016-11-11 19:51:26 +00:00
|
|
|
const DefaultVersion string = "1.26"
|
2016-09-06 18:46:37 +00:00
|
|
|
|
|
|
|
// Client is the API client that performs all operations
|
|
|
|
// against a docker server.
|
|
|
|
type Client struct {
|
2016-10-11 22:53:14 +00:00
|
|
|
// scheme sets the scheme for the client
|
|
|
|
scheme string
|
2016-09-06 18:46:37 +00:00
|
|
|
// host holds the server address to connect to
|
|
|
|
host string
|
|
|
|
// proto holds the client protocol i.e. unix.
|
|
|
|
proto string
|
|
|
|
// addr holds the client address.
|
|
|
|
addr string
|
|
|
|
// basePath holds the path to prepend to the requests.
|
|
|
|
basePath string
|
2016-09-09 03:44:25 +00:00
|
|
|
// client used to send and receive http requests.
|
|
|
|
client *http.Client
|
2016-09-06 18:46:37 +00:00
|
|
|
// version of the server to talk to.
|
|
|
|
version string
|
|
|
|
// custom http headers configured by users.
|
|
|
|
customHTTPHeaders map[string]string
|
2016-11-03 00:43:32 +00:00
|
|
|
// manualOverride is set to true when the version was set by users.
|
|
|
|
manualOverride bool
|
2016-09-06 18:46:37 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// NewEnvClient initializes a new API client based on environment variables.
|
|
|
|
// Use DOCKER_HOST to set the url to the docker server.
|
|
|
|
// Use DOCKER_API_VERSION to set the version of the API to reach, leave empty for latest.
|
|
|
|
// Use DOCKER_CERT_PATH to load the tls certificates from.
|
|
|
|
// Use DOCKER_TLS_VERIFY to enable or disable TLS verification, off by default.
|
|
|
|
func NewEnvClient() (*Client, error) {
|
|
|
|
var client *http.Client
|
|
|
|
if dockerCertPath := os.Getenv("DOCKER_CERT_PATH"); dockerCertPath != "" {
|
|
|
|
options := tlsconfig.Options{
|
|
|
|
CAFile: filepath.Join(dockerCertPath, "ca.pem"),
|
|
|
|
CertFile: filepath.Join(dockerCertPath, "cert.pem"),
|
|
|
|
KeyFile: filepath.Join(dockerCertPath, "key.pem"),
|
|
|
|
InsecureSkipVerify: os.Getenv("DOCKER_TLS_VERIFY") == "",
|
|
|
|
}
|
|
|
|
tlsc, err := tlsconfig.Client(options)
|
|
|
|
if err != nil {
|
|
|
|
return nil, err
|
|
|
|
}
|
|
|
|
|
|
|
|
client = &http.Client{
|
|
|
|
Transport: &http.Transport{
|
|
|
|
TLSClientConfig: tlsc,
|
|
|
|
},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
host := os.Getenv("DOCKER_HOST")
|
|
|
|
if host == "" {
|
|
|
|
host = DefaultDockerHost
|
|
|
|
}
|
|
|
|
version := os.Getenv("DOCKER_API_VERSION")
|
|
|
|
if version == "" {
|
|
|
|
version = DefaultVersion
|
|
|
|
}
|
|
|
|
|
2016-11-03 00:43:32 +00:00
|
|
|
cli, err := NewClient(host, version, client, nil)
|
|
|
|
if err != nil {
|
|
|
|
return cli, err
|
|
|
|
}
|
2016-11-21 09:31:46 +00:00
|
|
|
if os.Getenv("DOCKER_API_VERSION") != "" {
|
2016-11-03 00:43:32 +00:00
|
|
|
cli.manualOverride = true
|
|
|
|
}
|
|
|
|
return cli, nil
|
2016-09-06 18:46:37 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// NewClient initializes a new API client for the given host and API version.
|
|
|
|
// It uses the given http client as transport.
|
|
|
|
// It also initializes the custom http headers to add to each request.
|
|
|
|
//
|
|
|
|
// It won't send any version information if the version number is empty. It is
|
|
|
|
// highly recommended that you set a version or your client may break if the
|
|
|
|
// server is upgraded.
|
|
|
|
func NewClient(host string, version string, client *http.Client, httpHeaders map[string]string) (*Client, error) {
|
|
|
|
proto, addr, basePath, err := ParseHost(host)
|
|
|
|
if err != nil {
|
|
|
|
return nil, err
|
|
|
|
}
|
|
|
|
|
2016-09-22 02:16:44 +00:00
|
|
|
if client != nil {
|
|
|
|
if _, ok := client.Transport.(*http.Transport); !ok {
|
|
|
|
return nil, fmt.Errorf("unable to verify TLS configuration, invalid transport %v", client.Transport)
|
|
|
|
}
|
|
|
|
} else {
|
2016-09-09 03:44:25 +00:00
|
|
|
transport := new(http.Transport)
|
|
|
|
sockets.ConfigureTransport(transport, proto, addr)
|
2016-09-22 02:16:44 +00:00
|
|
|
client = &http.Client{
|
|
|
|
Transport: transport,
|
|
|
|
}
|
2016-09-06 18:46:37 +00:00
|
|
|
}
|
|
|
|
|
2016-10-11 22:53:14 +00:00
|
|
|
scheme := "http"
|
|
|
|
tlsConfig := resolveTLSConfig(client.Transport)
|
|
|
|
if tlsConfig != nil {
|
|
|
|
// TODO(stevvooe): This isn't really the right way to write clients in Go.
|
|
|
|
// `NewClient` should probably only take an `*http.Client` and work from there.
|
|
|
|
// Unfortunately, the model of having a host-ish/url-thingy as the connection
|
|
|
|
// string has us confusing protocol and transport layers. We continue doing
|
|
|
|
// this to avoid breaking existing clients but this should be addressed.
|
|
|
|
scheme = "https"
|
|
|
|
}
|
|
|
|
|
2016-09-06 18:46:37 +00:00
|
|
|
return &Client{
|
2016-10-11 22:53:14 +00:00
|
|
|
scheme: scheme,
|
2016-09-06 18:46:37 +00:00
|
|
|
host: host,
|
|
|
|
proto: proto,
|
|
|
|
addr: addr,
|
|
|
|
basePath: basePath,
|
2016-09-09 03:44:25 +00:00
|
|
|
client: client,
|
2016-09-06 18:46:37 +00:00
|
|
|
version: version,
|
|
|
|
customHTTPHeaders: httpHeaders,
|
|
|
|
}, nil
|
|
|
|
}
|
|
|
|
|
2016-09-08 01:57:54 +00:00
|
|
|
// Close ensures that transport.Client is closed
|
|
|
|
// especially needed while using NewClient with *http.Client = nil
|
|
|
|
// for example
|
|
|
|
// client.NewClient("unix:///var/run/docker.sock", nil, "v1.18", map[string]string{"User-Agent": "engine-api-cli-1.0"})
|
|
|
|
func (cli *Client) Close() error {
|
|
|
|
|
|
|
|
if t, ok := cli.client.Transport.(*http.Transport); ok {
|
|
|
|
t.CloseIdleConnections()
|
|
|
|
}
|
|
|
|
|
|
|
|
return nil
|
|
|
|
}
|
|
|
|
|
2016-09-06 18:46:37 +00:00
|
|
|
// getAPIPath returns the versioned request path to call the api.
|
|
|
|
// It appends the query parameters to the path if they are not empty.
|
|
|
|
func (cli *Client) getAPIPath(p string, query url.Values) string {
|
|
|
|
var apiPath string
|
|
|
|
if cli.version != "" {
|
|
|
|
v := strings.TrimPrefix(cli.version, "v")
|
|
|
|
apiPath = fmt.Sprintf("%s/v%s%s", cli.basePath, v, p)
|
|
|
|
} else {
|
|
|
|
apiPath = fmt.Sprintf("%s%s", cli.basePath, p)
|
|
|
|
}
|
|
|
|
|
|
|
|
u := &url.URL{
|
|
|
|
Path: apiPath,
|
|
|
|
}
|
|
|
|
if len(query) > 0 {
|
|
|
|
u.RawQuery = query.Encode()
|
|
|
|
}
|
|
|
|
return u.String()
|
|
|
|
}
|
|
|
|
|
|
|
|
// ClientVersion returns the version string associated with this
|
|
|
|
// instance of the Client. Note that this value can be changed
|
|
|
|
// via the DOCKER_API_VERSION env var.
|
2016-10-21 05:41:54 +00:00
|
|
|
// This operation doesn't acquire a mutex.
|
2016-09-06 18:46:37 +00:00
|
|
|
func (cli *Client) ClientVersion() string {
|
|
|
|
return cli.version
|
|
|
|
}
|
|
|
|
|
|
|
|
// UpdateClientVersion updates the version string associated with this
|
2016-10-21 05:41:54 +00:00
|
|
|
// instance of the Client. This operation doesn't acquire a mutex.
|
2016-09-06 18:46:37 +00:00
|
|
|
func (cli *Client) UpdateClientVersion(v string) {
|
2016-11-03 00:43:32 +00:00
|
|
|
if !cli.manualOverride {
|
|
|
|
cli.version = v
|
|
|
|
}
|
|
|
|
|
2016-09-06 18:46:37 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// ParseHost verifies that the given host strings is valid.
|
|
|
|
func ParseHost(host string) (string, string, string, error) {
|
|
|
|
protoAddrParts := strings.SplitN(host, "://", 2)
|
|
|
|
if len(protoAddrParts) == 1 {
|
|
|
|
return "", "", "", fmt.Errorf("unable to parse docker host `%s`", host)
|
|
|
|
}
|
|
|
|
|
|
|
|
var basePath string
|
|
|
|
proto, addr := protoAddrParts[0], protoAddrParts[1]
|
|
|
|
if proto == "tcp" {
|
|
|
|
parsed, err := url.Parse("tcp://" + addr)
|
|
|
|
if err != nil {
|
|
|
|
return "", "", "", err
|
|
|
|
}
|
|
|
|
addr = parsed.Host
|
|
|
|
basePath = parsed.Path
|
|
|
|
}
|
|
|
|
return proto, addr, basePath, nil
|
|
|
|
}
|
2016-10-21 05:41:54 +00:00
|
|
|
|
|
|
|
// CustomHTTPHeaders returns the custom http headers associated with this
|
|
|
|
// instance of the Client. This operation doesn't acquire a mutex.
|
|
|
|
func (cli *Client) CustomHTTPHeaders() map[string]string {
|
|
|
|
m := make(map[string]string)
|
|
|
|
for k, v := range cli.customHTTPHeaders {
|
|
|
|
m[k] = v
|
|
|
|
}
|
|
|
|
return m
|
|
|
|
}
|
|
|
|
|
|
|
|
// SetCustomHTTPHeaders updates the custom http headers associated with this
|
|
|
|
// instance of the Client. This operation doesn't acquire a mutex.
|
|
|
|
func (cli *Client) SetCustomHTTPHeaders(headers map[string]string) {
|
|
|
|
cli.customHTTPHeaders = headers
|
|
|
|
}
|