Documentation
¶
Overview ¶
Package docker executes commands and transfers files inside a running container. It implements invoke.Environment, verified against the invoketest contract suite.
The daemon is found the way the docker command finds it: an endpoint passed to WithHost, then a context named by WithContext or DOCKER_CONTEXT, then DOCKER_HOST, then the endpoint recorded by the current context — which is where installations that do not use the conventional socket, such as Colima and Rancher Desktop, put theirs.
The daemon must serve Engine API version 1.40 or newer, which Docker 19.03 was the first to do. That is the oldest version Docker's client library speaks, and an older daemon is refused when the Environment is created — as is a DOCKER_API_VERSION naming an older version.
Commands are delivered to the daemon as a real argument vector, so nothing is reinterpreted by a shell, and environment variables travel over the API rather than on a command line. Signal delivery needs a shell in the container to record the in-container process id; a container without one reports the capability as unavailable rather than accepting signals and dropping them. Without a shell, Close and cancellation cannot stop a command either: they end its input and let it go, returning at once with an outcome that says it was abandoned, while the command runs on in the container until it ends. Path lookup and uploads need the shell too; downloads do not.
Index ¶
- type Config
- type Environment
- func (e *Environment) Capabilities() invoke.Capabilities
- func (e *Environment) Close() error
- func (e *Environment) Download(ctx context.Context, remotePath, localPath string, ...) error
- func (e *Environment) LookPath(ctx context.Context, name string) (string, error)
- func (e *Environment) OS() invoke.TargetOS
- func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
- func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, ...) error
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Container is the container name or ID to execute in. Required.
Container string
// User is the user commands run as, in the same form docker accepts
// ("root", "1000", "1000:1000"). Empty means the container's own
// default.
User string
// Privileged runs commands with elevated privileges.
Privileged bool
// Host is the daemon endpoint. Empty means the endpoint the local
// docker installation is configured to use: DOCKER_HOST when set,
// otherwise the current context's.
Host string
// Context names a docker context to take the endpoint from,
// overriding whichever one is current — and DOCKER_HOST, as the
// docker command's own --context flag does.
Context string
// Timeout bounds daemon calls that must not block indefinitely;
// zero means 30s.
Timeout time.Duration
}
Config holds the settings for executing in a container. Callers normally build it with New and the With options rather than by hand; NewFromConfig accepts one directly.
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment is a connection to a running container.
func New ¶
New connects to the daemon and returns an Environment for the named container, which must already be running.
ctx bounds establishing the connection only — which is several round trips to the daemon, not one. It does not govern the Environment afterwards, which lives until Close.
func NewFromConfig ¶
func NewFromConfig(ctx context.Context, cfg *Config) (*Environment, error)
NewFromConfig connects using a Config assembled directly. ctx bounds establishing the connection, as in New.
func (*Environment) Capabilities ¶
func (e *Environment) Capabilities() invoke.Capabilities
Capabilities reports the container's optional features.
Signal delivery requires a shell to record the in-container process id; without one the capability is not declared, so signal requests fail rather than being silently dropped.
Terminal allocation is available: the daemon's exec API takes a terminal flag and an initial size.
func (*Environment) Close ¶
func (e *Environment) Close() error
Close releases the daemon connection, terminating commands still running.
func (*Environment) Download ¶
func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.TransferOption) error
Download copies a path out of the container. See download; Close stops it as it does an Upload.
func (*Environment) OS ¶
func (e *Environment) OS() invoke.TargetOS
OS reports the container's operating system, detected once at connect time.
func (*Environment) Start ¶
func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
Start runs cmd in the container and returns a handle to it.
func (*Environment) Upload ¶
func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.TransferOption) error
Upload copies a local file or directory tree into the container. See upload; Close stops it, and it then fails wrapping invoke.ErrClosed.
type Option ¶
type Option func(*Config)
Option configures a Config.
func WithContext ¶ added in v0.3.0
WithContext takes the daemon endpoint from the named docker context, rather than from whichever one the installation currently selects — overriding an ambient DOCKER_HOST too, as the docker command's own --context flag does.
Naming a context that cannot be read fails, rather than falling back to the default endpoint: the fallback is a different daemon, and commands would run somewhere the caller did not choose.
func WithPrivileged ¶
func WithPrivileged() Option
WithPrivileged runs commands with elevated privileges.
func WithTimeout ¶
WithTimeout bounds daemon calls that must not block indefinitely.