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
- type Metadata
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 ( // ErrDockerHostNotSet is returned when the Docker host is not set in the Docker context. ErrDockerHostNotSet = errors.New("docker host not set in Docker context") // ErrDockerContextNotFound is returned when the Docker context is not found. ErrDockerContextNotFound = errors.New("docker context not found") )
var DefaultDockerHost = ""
DefaultDockerHost is the default host to connect to the Docker socket. The actual value is platform-specific and defined in host_unix.go and host_windows.go.
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 ¶
type Context struct {
// Name is the name of the context
Name string `json:"Name,omitempty"`
// Metadata is the metadata stored for a context
Metadata *Metadata `json:"Metadata,omitempty"`
// Endpoints is the list of endpoints for the context
Endpoints map[string]*endpoint `json:"Endpoints,omitempty"`
}
Context represents a Docker context
func Inspect ¶
Inspect returns the given context. It returns an error if the context is not found or if the docker endpoint is not set.
Example ¶
package main
import (
"fmt"
"log"
"github.com/docker/go-sdk/context"
)
func main() {
ctx, err := context.Inspect("docker-cloud")
if err != nil {
log.Printf("error inspecting context: %s", err)
return
}
fmt.Println(ctx.Metadata.Description)
fmt.Println(ctx.Metadata.Field("otel"))
fmt.Println(ctx.Metadata.Fields())
// Intentionally not printing the output, as the context could not exist in the CI environment
}
Output:
type Metadata ¶
type Metadata struct {
// Description is the description of the context
Description string `json:"Description,omitempty"`
// contains filtered or unexported fields
}
Metadata represents the metadata stored for a context
func (*Metadata) MarshalJSON ¶
MarshalJSON implements custom JSON marshaling for dockerContext
func (*Metadata) UnmarshalJSON ¶
UnmarshalJSON implements custom JSON unmarshaling for dockerContext
Source Files