command

package
v29.0.2+incompatible Latest Latest
Warning

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

 Go to latest Published: Nov 17, 2025 License: Apache-2.0 Imports: 54 Imported by: 3,882

Documentation

Index

Constants

View Source 
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"
)

Variables

This section is empty.

Functions

func BaseCommandAttributes 

func BaseCommandAttributes(cmd *cobra.Command, streams Streams) []attribute.KeyValue

BaseCommandAttributes returns an attribute.Set containing attributes to attach to metrics/traces

func DefaultContextStoreConfig 

func DefaultContextStoreConfig() store.Config

DefaultContextStoreConfig returns a new store.Config with the default set of endpoints configured.

func GetDefaultAuthConfig 

func GetDefaultAuthConfig(cfg *configfile.ConfigFile, checkCredStore bool, serverAddress string, isDefaultRegistry bool) (registrytypes.AuthConfig, error)

GetDefaultAuthConfig gets the default auth config given a serverAddress If credentials for given serverAddress exists in the credential store, the configuration will be populated with values in it

func NewAPIClientFromFlags 

func NewAPIClientFromFlags(opts *cliflags.ClientOptions, configFile *configfile.ConfigFile) (client.APIClient, error)

NewAPIClientFromFlags creates a new APIClient from command line flags

func PromptUserForCredentials 

func PromptUserForCredentials(ctx context.Context, cli Cli, argUser, argPassword, defaultUsername, serverAddress string) (registrytypes.AuthConfig, error)

PromptUserForCredentials handles the CLI prompt for the user to input credentials. If argUser is not empty, then the user is only prompted for their password. If argPassword is not empty, then the user is only prompted for their username If neither argUser nor argPassword are empty, then the user is not prompted and an AuthConfig is returned with those values. If defaultUsername is not empty, the username prompt includes that username and the user can hit enter without inputting a username to use that default username.

func PruneFilters 

func PruneFilters(dockerCLI config.Provider, filters client.Filters) client.Filters

PruneFilters merges prune filters specified in config.json with those specified as command-line flags. It returns a deep copy of filters to prevent mutating the original.

CLI label filters have precedence over those specified in config.json. If a label filter specified as flag conflicts with a label defined in config.json (i.e., "label=some-value" conflicts with "label!=some-value", and vice versa), then the filter defined in config.json is omitted.

func RegisterDefaultStoreEndpoints 

func RegisterDefaultStoreEndpoints(ep ...store.NamedTypeGetter)

RegisterDefaultStoreEndpoints registers a new named endpoint metadata type with the default context store config, so that endpoint will be supported by stores using the config returned by DefaultContextStoreConfig.

func ResolveAuthConfig deprecated 

func ResolveAuthConfig(cfg *configfile.ConfigFile, index *registrytypes.IndexInfo) registrytypes.AuthConfig

ResolveAuthConfig returns auth-config for the given registry from the credential-store. It returns an empty AuthConfig if no credentials were found.

Deprecated: this function is no longer used, and will be removed in the next release.

func RetrieveAuthTokenFromImage 

func RetrieveAuthTokenFromImage(cfg *configfile.ConfigFile, image string) (string, error)

RetrieveAuthTokenFromImage retrieves an encoded auth token given a complete image reference. The auth configuration is serialized as a base64url encoded (RFC 4648, Section 5) JSON string for sending through the "X-Registry-Auth" header.

func ShowHelp 

func ShowHelp(err io.Writer) func(*cobra.Command, []string) error

ShowHelp shows the command help.

func UserAgent 

func UserAgent() string

UserAgent returns the default user agent string used for making API requests.

func ValidateOutputPath 

func ValidateOutputPath(path string) error

ValidateOutputPath validates the output paths of the "docker cp" command.

func ValidateOutputPathFileMode 

func ValidateOutputPathFileMode(fileMode os.FileMode) error

ValidateOutputPathFileMode validates the output paths of the "docker cp" command and serves as a helper to ValidateOutputPath

Types

type CLIOption 

type CLIOption func(cli *DockerCli) error

CLIOption is a functional argument to apply options to a DockerCli. These options can be passed to NewDockerCli to initialize a new CLI, or applied with DockerCli.Initialize or [DockerCli.Apply].

func WithAPIClient 

func WithAPIClient(c client.APIClient) CLIOption

WithAPIClient configures the cli to use the given API client.

func WithBaseContext 

func WithBaseContext(ctx context.Context) CLIOption

WithBaseContext sets the base context of a cli. It is used to propagate the context from the command line to the client.

func WithCombinedStreams 

func WithCombinedStreams(combined io.Writer) CLIOption

WithCombinedStreams uses the same stream for the output and error streams.

func WithDefaultContextStoreConfig 

func WithDefaultContextStoreConfig() CLIOption

WithDefaultContextStoreConfig configures the cli to use the default context store configuration.

func WithEnableGlobalMeterProvider 

func WithEnableGlobalMeterProvider() CLIOption

WithEnableGlobalMeterProvider configures the DockerCli to create a new MeterProvider from the initialized DockerCli struct, and set it as the global meter provider.

WARNING: For internal use, don't depend on this.

func WithEnableGlobalTracerProvider 

func WithEnableGlobalTracerProvider() CLIOption

WithEnableGlobalTracerProvider configures the DockerCli to create a new TracerProvider from the initialized DockerCli struct, and set it as the global tracer provider.

WARNING: For internal use, don't depend on this.

func WithErrorStream 

func WithErrorStream(err io.Writer) CLIOption

WithErrorStream sets a cli error stream.

func WithInitializeClient 

func WithInitializeClient(makeClient func(*DockerCli) (client.APIClient, error)) CLIOption

WithInitializeClient is passed to DockerCli.Initialize to initialize an API Client for use by the CLI.

func WithInputStream 

func WithInputStream(in io.ReadCloser) CLIOption

WithInputStream sets a cli input stream.

func WithOutputStream 

func WithOutputStream(out io.Writer) CLIOption

WithOutputStream sets a cli output stream.

func WithResource 

func WithResource(res *resource.Resource) CLIOption

WithResource overwrites the default resource and prevents its creation.

func WithResourceOptions 

func WithResourceOptions(opts ...resource.Option) CLIOption

WithResourceOptions configures additional options for the default resource. The default resource will continue to include its default options.

func WithStandardStreams 

func WithStandardStreams() CLIOption

WithStandardStreams sets a cli in, out and err streams with the standard streams.

func WithUserAgent 

func WithUserAgent(userAgent string) CLIOption

WithUserAgent configures the User-Agent string for cli HTTP requests.

type Cli 

type Cli interface {
	Client() client.APIClient
	Streams
	SetIn(in *streams.In)
	config.Provider
	ServerInfo() ServerInfo
	CurrentVersion() string
	BuildKitEnabled() (bool, error)
	ContextStore() store.Store
	CurrentContext() string
	DockerEndpoint() docker.Endpoint
	TelemetryClient
}

Cli represents the docker command line client.

type ContextStoreWithDefault 

type ContextStoreWithDefault struct {
	store.Store
	Resolver DefaultContextResolver
}

ContextStoreWithDefault implements the store.Store interface with a support for the default context

func (*ContextStoreWithDefault) CreateOrUpdate 

func (s *ContextStoreWithDefault) CreateOrUpdate(meta store.Metadata) error

CreateOrUpdate is not allowed for the default context and fails

func (*ContextStoreWithDefault) GetMetadata 

func (s *ContextStoreWithDefault) GetMetadata(name string) (store.Metadata, error)

GetMetadata implements store.Store's GetMetadata

func (*ContextStoreWithDefault) GetStorageInfo 

func (s *ContextStoreWithDefault) GetStorageInfo(contextName string) store.StorageInfo

GetStorageInfo implements store.Store's GetStorageInfo

func (*ContextStoreWithDefault) GetTLSData 

func (s *ContextStoreWithDefault) GetTLSData(contextName, endpointName, fileName string) ([]byte, error)

GetTLSData implements store.Store's GetTLSData

func (*ContextStoreWithDefault) List 

func (s *ContextStoreWithDefault) List() ([]store.Metadata, error)

List implements store.Store's List

func (*ContextStoreWithDefault) ListTLSFiles 

func (s *ContextStoreWithDefault) ListTLSFiles(name string) (map[string]store.EndpointFiles, error)

ListTLSFiles implements store.Store's ListTLSFiles

func (*ContextStoreWithDefault) Remove 

func (s *ContextStoreWithDefault) Remove(name string) error

Remove is not allowed for the default context and fails

func (*ContextStoreWithDefault) ResetEndpointTLSMaterial 

func (s *ContextStoreWithDefault) ResetEndpointTLSMaterial(contextName string, endpointName string, data *store.EndpointTLSData) error

ResetEndpointTLSMaterial is not implemented for default context and fails

func (*ContextStoreWithDefault) ResetTLSMaterial 

func (s *ContextStoreWithDefault) ResetTLSMaterial(name string, data *store.ContextTLSData) error

ResetTLSMaterial is not implemented for default context and fails

type DefaultContext 

type DefaultContext struct {
	Meta store.Metadata
	TLS  store.ContextTLSData
}

DefaultContext contains the default context data for all endpoints

type DefaultContextResolver 

type DefaultContextResolver func() (*DefaultContext, error)

DefaultContextResolver is a function which resolves the default context base on the configuration and the env variables

type DockerCli 

type DockerCli struct {
	// contains filtered or unexported fields
}

DockerCli is an instance the docker command line client. Instances of the client should be created using the NewDockerCli constructor to make sure they are properly initialized with defaults set.

func NewDockerCli 

func NewDockerCli(ops ...CLIOption) (*DockerCli, error)

NewDockerCli returns a DockerCli instance with all operators applied on it. It applies by default the standard streams, and the content trust from environment.

func (*DockerCli) BuildKitEnabled 

func (cli *DockerCli) BuildKitEnabled() (bool, error)

BuildKitEnabled returns buildkit is enabled or not.

func (*DockerCli) Client 

func (cli *DockerCli) Client() client.APIClient

Client returns the APIClient

func (*DockerCli) ConfigFile 

func (cli *DockerCli) ConfigFile() *configfile.ConfigFile

ConfigFile returns the ConfigFile

func (*DockerCli) ContextStore 

func (cli *DockerCli) ContextStore() store.Store

ContextStore returns the ContextStore

func (*DockerCli) CurrentContext 

func (cli *DockerCli) CurrentContext() string

CurrentContext returns the current context name, based on flags, environment variables and the cli configuration file, in the following order of preference:

  1. The "--context" command-line option.
  2. The "DOCKER_CONTEXT" environment variable (EnvOverrideContext).
  3. The current context as configured through the in "currentContext" field in the CLI configuration file ("~/.docker/config.json").
  4. If no context is configured, use the "default" context.

Fallbacks for backward-compatibility

To preserve backward-compatibility with the "pre-contexts" behavior, the "default" context is used if:

  • The "--host" option is set
  • The "DOCKER_HOST" (client.EnvOverrideHost) environment variable is set to a non-empty value.

In these cases, the default context is used, which uses the host as specified in "DOCKER_HOST", and TLS config from flags/env vars.

Setting both the "--context" and "--host" flags is ambiguous and results in an error when the cli is started.

CurrentContext does not validate if the given context exists or if it's valid; errors may occur when trying to use it.

func (*DockerCli) CurrentVersion 

func (cli *DockerCli) CurrentVersion() string

CurrentVersion returns the API version currently negotiated, or the default version otherwise.

func (*DockerCli) DockerEndpoint 

func (cli *DockerCli) DockerEndpoint() docker.Endpoint

DockerEndpoint returns the current docker endpoint

func (*DockerCli) Err 

func (cli *DockerCli) Err() *streams.Out

Err returns the writer used for stderr

func (*DockerCli) HooksEnabled 

func (cli *DockerCli) HooksEnabled() bool

HooksEnabled returns whether plugin hooks are enabled.

func (*DockerCli) In 

func (cli *DockerCli) In() *streams.In

In returns the reader used for stdin

func (*DockerCli) Initialize 

func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...CLIOption) error

Initialize the dockerCli runs initialization that must happen after command line flags are parsed.

func (*DockerCli) InstrumentCobraCommands 

func (cli *DockerCli) InstrumentCobraCommands(ctx context.Context, cmd *cobra.Command)

InstrumentCobraCommands wraps all cobra commands' RunE funcs to set a command duration metric using otel.

Note: this should be the last func to wrap/modify the PersistentRunE/RunE funcs before command execution.

can also be used for spans!

func (*DockerCli) MeterProvider 

func (*DockerCli) MeterProvider() metric.MeterProvider

func (*DockerCli) Out 

func (cli *DockerCli) Out() *streams.Out

Out returns the writer used for stdout

func (*DockerCli) Resource 

func (cli *DockerCli) Resource() *resource.Resource

func (*DockerCli) ServerInfo 

func (cli *DockerCli) ServerInfo() ServerInfo

ServerInfo returns the server version details for the host this client is connected to

func (*DockerCli) SetIn 

func (cli *DockerCli) SetIn(in *streams.In)

SetIn sets the reader used for stdin

func (*DockerCli) StartInstrumentation 

func (cli *DockerCli) StartInstrumentation(cmd *cobra.Command) (stopInstrumentation func(error))

StartInstrumentation instruments CLI commands with the individual metrics and spans configured. It's the main command OTel utility, and new command-related metrics should be added to it. It should be called immediately before command execution, and returns a stopInstrumentation function that must be called with the error resulting from the command execution.

func (*DockerCli) TracerProvider 

func (*DockerCli) TracerProvider() trace.TracerProvider

type DockerContext 

type DockerContext struct {
	Description      string
	AdditionalFields map[string]any
}

DockerContext is a typed representation of what we put in Context metadata

func GetDockerContext 

func GetDockerContext(storeMetadata store.Metadata) (DockerContext, error)

GetDockerContext extracts metadata from stored context metadata

func (DockerContext) MarshalJSON 

func (dc DockerContext) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshalling

func (*DockerContext) UnmarshalJSON 

func (dc *DockerContext) UnmarshalJSON(payload []byte) error

UnmarshalJSON implements custom JSON marshalling

type EndpointDefaultResolver 

type EndpointDefaultResolver interface {
	// ResolveDefault returns values suitable for storing in store.Metadata.Endpoints
	// and store.ContextTLSData.Endpoints.
	//
	// An error is only returned for something fatal, not simply
	// the lack of a default (e.g. because the config file which
	// would contain it is missing). If there is no default then
	// returns nil, nil, nil.
	//
	//nolint:dupword // ignore "Duplicate words (nil,) found"
	ResolveDefault() (any, *store.EndpointTLSData, error)
}

EndpointDefaultResolver is implemented by any EndpointMeta object which wants to be able to populate the store with whatever their default is.

type MeterProvider 

type MeterProvider interface {
	metric.MeterProvider
	ForceFlush(ctx context.Context) error
	Shutdown(ctx context.Context) error
}

MeterProvider is an extension of the metric.MeterProvider interface for CLI programs.

type ServerInfo 

type ServerInfo struct {
	HasExperimental bool
	OSType          string
	BuildkitVersion build.BuilderVersion

	// SwarmStatus provides information about the current swarm status of the
	// engine, obtained from the "Swarm" header in the API response.
	//
	// It can be a nil struct if the API version does not provide this header
	// in the ping response, or if an error occurred, in which case the client
	// should use other ways to get the current swarm status, such as the /swarm
	// endpoint.
	SwarmStatus *client.SwarmStatus
}

ServerInfo stores details about the supported features and platform of the server

type Streams 

type Streams interface {
	In() *streams.In
	Out() *streams.Out
	Err() *streams.Out
}

Streams is an interface which exposes the standard input and output streams

type TelemetryClient 

type TelemetryClient interface {
	// Resource returns the OTEL Resource configured with this TelemetryClient.
	// This resource may be created lazily, but the resource should be the same
	// each time this function is invoked.
	Resource() *resource.Resource

	// TracerProvider returns the currently initialized TracerProvider. This TracerProvider will be configured
	// with the default tracing components for a CLI program
	TracerProvider() trace.TracerProvider

	// MeterProvider returns the currently initialized MeterProvider. This MeterProvider will be configured
	// with the default metric components for a CLI program
	MeterProvider() metric.MeterProvider
}

TelemetryClient provides the methods for using OTEL tracing or metrics.

type TracerProvider 

type TracerProvider interface {
	trace.TracerProvider
	ForceFlush(ctx context.Context) error
	Shutdown(ctx context.Context) error
}

TracerProvider is an extension of the trace.TracerProvider interface for CLI programs.

Source Files

View all Source files

Directories

Path Synopsis
tabwriter
build
build/internal/git
build/internal/urlutil
Package urlutil provides helper function to check if a given build-context location should be considered a URL or a remote Git repository.
 Package urlutil provides helper function to check if a given build-context location should be considered a URL or a remote Git repository.
internal/genericresource
Package genericresource is a local fork of SwarmKit's genericresource package, without protobuf dependencies.
 Package genericresource is a local fork of SwarmKit's genericresource package, without protobuf dependencies.
progress
progress
pruner
Package pruner registers "prune" functions to be included as part of "docker system prune".
 Package pruner registers "prune" functions to be included as part of "docker system prune".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.