README
¶
Docker Contexts
This package provides a simple API to interact with Docker contexts.
Installation
go get github.com/docker/go-sdk/context
Usage
Current Context
It returns the current Docker context name.
current, err := context.Current()
if err != nil {
log.Fatalf("failed to get current docker context: %v", err)
}
fmt.Printf("current docker context: %s", current)
Current Docker Host
It returns the Docker host that the current context is configured to use.
dockerHost, err := context.CurrentDockerHost()
if err != nil {
log.Fatalf("failed to get current docker host: %v", err)
}
fmt.Printf("current docker host: %s", dockerHost)
Docker Host From Context
It returns the Docker host that the given context is configured to use.
dockerHost, err := context.DockerHostFromContext("desktop-linux")
if err != nil {
log.Printf("error getting docker host from context: %s", err)
return
}
fmt.Printf("docker host from context: %s", dockerHost)
Inspect Context
It returns the description of the given context.
description, err := context.Inspect("context1")
if err != nil {
log.Printf("failed to inspect context: %v", err)
return
}
fmt.Printf("description: %s", description)
If the context is not found, it returns an ErrDockerContextNotFound error.
List Contexts
It returns the list of contexts available in the Docker configuration.
contexts, err := context.List()
if err != nil {
log.Printf("failed to list contexts: %v", err)
return
}
fmt.Printf("contexts: %v", contexts)
Documentation
¶
Index ¶
- Constants
- Variables
- func Current() (string, error)
- func CurrentDockerHost() (string, error)
- func DockerHostFromContext(ctxName string) (string, error)
- func List() ([]string, error)
- func SetupTestDockerContexts(tb testing.TB, currentContextIndex int, contextsCount int)
- func Version() string
- type Context
Examples ¶
Constants ¶
const ( // DefaultContextName is the name reserved for the default context (config & env based) DefaultContextName = "default" // EnvOverrideContext is the name of the environment variable that can be // used to override the context to use. If set, it overrides the context // that's set in the CLI's configuration file, but takes no effect if the // "DOCKER_HOST" env-var is set (which takes precedence. EnvOverrideContext = "DOCKER_CONTEXT" // EnvOverrideHost is the name of the environment variable that can be used // to override the default host to connect to (DefaultDockerHost). // // This env-var is read by FromEnv and WithHostFromEnv and when set to a // non-empty value, takes precedence over the default host (which is platform // specific), or any host already set. EnvOverrideHost = "DOCKER_HOST" )
Variables ¶
var ( // DefaultDockerHost is the default host to connect to the Docker socket. // The actual value is platform-specific and defined in host_linux.go and host_windows.go. DefaultDockerHost = "" // ErrDockerHostNotSet is the error returned when the Docker host is not set in the Docker context ErrDockerHostNotSet = internal.ErrDockerHostNotSet // ErrDockerContextNotFound is the error returned when the Docker context is not found. ErrDockerContextNotFound = internal.ErrDockerContextNotFound )
Functions ¶
func Current ¶
Current returns the current context name, based on environment variables and the cli configuration file. It does not validate if the given context exists or if it's valid.
If the current context is not found, it returns the default context name.
Example ¶
package main
import (
"fmt"
"github.com/docker/go-sdk/context"
)
func main() {
ctx, err := context.Current()
fmt.Println(err)
fmt.Println(ctx != "")
}
Output: <nil> true
func CurrentDockerHost ¶
CurrentDockerHost returns the Docker host from the current Docker context. For that, it traverses the directory structure of the Docker configuration directory, looking for the current context and its Docker endpoint.
If the current context is the default context, it returns the value of the DOCKER_HOST environment variable.
Example ¶
package main
import (
"fmt"
"github.com/docker/go-sdk/context"
)
func main() {
host, err := context.CurrentDockerHost()
fmt.Println(err)
fmt.Println(host != "")
}
Output: <nil> true
func DockerHostFromContext ¶
DockerHostFromContext returns the Docker host from the given context.
Example ¶
package main
import (
"fmt"
"log"
"github.com/docker/go-sdk/context"
)
func main() {
host, err := context.DockerHostFromContext("desktop-linux")
if err != nil {
log.Printf("error getting docker host from context: %s", err)
return
}
fmt.Println(host)
// Intentionally not printing the output, as the context could not exist in the CI environment
}
Output:
func List ¶
List returns the list of contexts available in the Docker configuration.
Example ¶
package main
import (
"fmt"
"log"
"github.com/docker/go-sdk/context"
)
func main() {
contexts, err := context.List()
if err != nil {
log.Printf("error listing contexts: %s", err)
return
}
fmt.Println(contexts)
// Intentionally not printing the output, as the contexts could not exist in the CI environment
}
Output:
func SetupTestDockerContexts ¶
SetupTestDockerContexts creates a temporary directory structure for testing the Docker context functions. It creates the following structure, where $i is the index of the context, starting from 1: - $HOME/.docker
- config.json
- contexts
- meta
- context$i
- meta.json
The config.json file contains the current context, and the meta.json files contain the metadata for each context. It generates the specified number of contexts, setting the current context to the one specified by currentContextIndex. The docker host for each context is "tcp://127.0.0.1:$i". Finally it always adds a context with an empty host, to validate the behavior when the host is not set, and a context with a custom endpoint, to validate the behavior when the endpoint is not the default "docker". This empty context can be used setting the currentContextIndex to a number greater than contextsCount.
Types ¶
type Context ¶
Context represents a Docker context
func Inspect ¶
Inspect returns the description of the given context.
Example ¶
package main
import (
"log"
"github.com/docker/go-sdk/context"
)
func main() {
_, err := context.Inspect("desktop-linux")
if err != nil {
log.Printf("error inspecting context: %s", err)
return
}
// Intentionally not printing the output, as the context could not exist in the CI environment
}
Output:
Source Files
Directories