Documentation ¶
Index ¶
- Constants
- Variables
- func AddPlatformFlag(flags *pflag.FlagSet, target *string)
- func AddTrustSigningFlags(fs *pflag.FlagSet, v *bool, trusted bool)
- func AddTrustVerificationFlags(fs *pflag.FlagSet, v *bool, trusted bool)
- func BaseCommandAttributes(cmd *cobra.Command, streams Streams) []attribute.KeyValue
- func ConfigureAuth(ctx context.Context, cli Cli, flUser, flPassword string, ...) error
- func CopyToFile(outfile string, r io.Reader) error
- func DefaultContextStoreConfig() store.Config
- func DisableInputEcho(ins *streams.In) (restore func() error, err error)
- func GetDefaultAuthConfig(cfg *configfile.ConfigFile, checkCredStore bool, serverAddress string, ...) (registrytypes.AuthConfig, error)
- func NewAPIClientFromFlags(opts *cliflags.ClientOptions, configFile *configfile.ConfigFile) (client.APIClient, error)
- func PrettyPrint(i any) string
- func PromptForConfirmation(ctx context.Context, ins io.Reader, outs io.Writer, message string) (bool, error)
- func PromptForInput(ctx context.Context, in io.Reader, out io.Writer, message string) (string, error)
- func PromptUserForCredentials(ctx context.Context, cli Cli, ...) (authConfig registrytypes.AuthConfig, err error)
- func PruneFilters(dockerCli Cli, pruneFilters filters.Args) filters.Args
- func RegisterDefaultStoreEndpoints(ep ...store.NamedTypeGetter)
- func RegistryAuthenticationPrivilegedFunc(cli Cli, index *registrytypes.IndexInfo, cmdName string) registrytypes.RequestAuthConfig
- func ResolveAuthConfig(cfg *configfile.ConfigFile, index *registrytypes.IndexInfo) registrytypes.AuthConfig
- func RetrieveAuthTokenFromImage(cfg *configfile.ConfigFile, image string) (string, error)
- func ShowHelp(err io.Writer) func(*cobra.Command, []string) error
- func StringSliceReplaceAt(s, find, replace []string, requireIndex int) ([]string, bool)
- func UserAgent() string
- func ValidateMountWithAPIVersion(m mounttypes.Mount, serverAPIVersion string) error
- func ValidateOutputPath(path string) error
- func ValidateOutputPathFileMode(fileMode os.FileMode) error
- type CLIOption
- func WithAPIClient(c client.APIClient) CLIOption
- func WithBaseContext(ctx context.Context) CLIOption
- func WithCombinedStreams(combined io.Writer) CLIOption
- func WithContentTrust(enabled bool) CLIOption
- func WithContentTrustFromEnv() CLIOption
- func WithDefaultContextStoreConfig() CLIOption
- func WithEnableGlobalMeterProvider() CLIOption
- func WithEnableGlobalTracerProvider() CLIOption
- func WithErrorStream(err io.Writer) CLIOption
- func WithInitializeClient(makeClient func(dockerCli *DockerCli) (client.APIClient, error)) CLIOption
- func WithInputStream(in io.ReadCloser) CLIOption
- func WithOutputStream(out io.Writer) CLIOption
- func WithResource(res *resource.Resource) CLIOption
- func WithResourceOptions(opts ...resource.Option) CLIOption
- func WithStandardStreams() CLIOption
- type Cli
- type ContextStoreWithDefault
- func (s *ContextStoreWithDefault) CreateOrUpdate(meta store.Metadata) error
- func (s *ContextStoreWithDefault) GetMetadata(name string) (store.Metadata, error)
- func (s *ContextStoreWithDefault) GetStorageInfo(contextName string) store.StorageInfo
- func (s *ContextStoreWithDefault) GetTLSData(contextName, endpointName, fileName string) ([]byte, error)
- func (s *ContextStoreWithDefault) List() ([]store.Metadata, error)
- func (s *ContextStoreWithDefault) ListTLSFiles(name string) (map[string]store.EndpointFiles, error)
- func (s *ContextStoreWithDefault) Remove(name string) error
- func (s *ContextStoreWithDefault) ResetEndpointTLSMaterial(contextName string, endpointName string, data *store.EndpointTLSData) error
- func (s *ContextStoreWithDefault) ResetTLSMaterial(name string, data *store.ContextTLSData) error
- type DefaultContext
- type DefaultContextResolver
- type DockerCli
- func (cli *DockerCli) Apply(ops ...CLIOption) error
- func (cli *DockerCli) BuildKitEnabled() (bool, error)
- func (cli *DockerCli) Client() client.APIClient
- func (cli *DockerCli) ConfigFile() *configfile.ConfigFile
- func (cli *DockerCli) ContentTrustEnabled() bool
- func (cli *DockerCli) ContextStore() store.Store
- func (cli *DockerCli) CurrentContext() string
- func (cli *DockerCli) CurrentVersion() string
- func (cli *DockerCli) DefaultVersion() string
- func (cli *DockerCli) DockerEndpoint() docker.Endpoint
- func (cli *DockerCli) Err() *streams.Out
- func (cli *DockerCli) HooksEnabled() bool
- func (cli *DockerCli) In() *streams.In
- func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...CLIOption) error
- func (cli *DockerCli) InstrumentCobraCommands(ctx context.Context, cmd *cobra.Command)
- func (cli *DockerCli) ManifestStore() manifeststore.Store
- func (cli *DockerCli) MeterProvider() metric.MeterProvider
- func (cli *DockerCli) NotaryClient(imgRefAndAuth trust.ImageRefAndAuth, actions []string) (notaryclient.Repository, error)
- func (cli *DockerCli) Out() *streams.Out
- func (cli *DockerCli) RegistryClient(allowInsecure bool) registryclient.RegistryClient
- func (cli *DockerCli) Resource() *resource.Resource
- func (cli *DockerCli) ServerInfo() ServerInfo
- func (cli *DockerCli) SetIn(in *streams.In)
- func (cli *DockerCli) StartInstrumentation(cmd *cobra.Command) (stopInstrumentation func(error))
- func (cli *DockerCli) TracerProvider() trace.TracerProvider
- type DockerContext
- type EndpointDefaultResolver
- type MeterProvider
- type ServerInfo
- type Streams
- type TelemetryClient
- type TracerProvider
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" )
Variables ¶
var ErrPromptTerminated = errdefs.Cancelled(errors.New("prompt terminated"))
Functions ¶
func AddPlatformFlag ¶
AddPlatformFlag adds `platform` to a set of flags for API version 1.32 and later.
func AddTrustSigningFlags ¶
AddTrustSigningFlags adds "signing" flags to the provided flagset
func AddTrustVerificationFlags ¶
AddTrustVerificationFlags adds content trust flags to the provided flagset
func BaseCommandAttributes ¶
BaseCommandAttributes returns an attribute.Set containing attributes to attach to metrics/traces
func ConfigureAuth ¶
func ConfigureAuth(ctx context.Context, cli Cli, flUser, flPassword string, authConfig *registrytypes.AuthConfig, _ bool) error
ConfigureAuth handles prompting of user's username and password if needed. Deprecated: use PromptUserForCredentials instead.
func CopyToFile ¶
CopyToFile writes the content of the reader to the specified file
func DefaultContextStoreConfig ¶
DefaultContextStoreConfig returns a new store.Config with the default set of endpoints configured.
func DisableInputEcho ¶
DisableInputEcho disables input echo on the provided streams.In. This is useful when the user provides sensitive information like passwords. The function returns a restore function that should be called to restore the terminal state.
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 PrettyPrint ¶
PrettyPrint outputs arbitrary data for human formatted output by uppercasing the first letter.
func PromptForConfirmation ¶
func PromptForConfirmation(ctx context.Context, ins io.Reader, outs io.Writer, message string) (bool, error)
PromptForConfirmation requests and checks confirmation from the user. This will display the provided message followed by ' y/N '. If the user input 'y' or 'Y' it returns true otherwise false. If no message is provided, "Are you sure you want to proceed? y/N " will be used instead.
If the user terminates the CLI with SIGINT or SIGTERM while the prompt is active, the prompt will return false with an ErrPromptTerminated error. When the prompt returns an error, the caller should propagate the error up the stack and close the io.Reader used for the prompt which will prevent the background goroutine from blocking indefinitely.
func PromptForInput ¶
func PromptForInput(ctx context.Context, in io.Reader, out io.Writer, message string) (string, error)
PromptForInput requests input from the user.
If the user terminates the CLI with SIGINT or SIGTERM while the prompt is active, the prompt will return an empty string ("") with an ErrPromptTerminated error. When the prompt returns an error, the caller should propagate the error up the stack and close the io.Reader used for the prompt which will prevent the background goroutine from blocking indefinitely.
func PromptUserForCredentials ¶
func PromptUserForCredentials(ctx context.Context, cli Cli, argUser, argPassword, defaultUsername, serverAddress string) (authConfig registrytypes.AuthConfig, err 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 ¶
PruneFilters returns consolidated prune filters obtained from config.json and cli
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 RegistryAuthenticationPrivilegedFunc ¶
func RegistryAuthenticationPrivilegedFunc(cli Cli, index *registrytypes.IndexInfo, cmdName string) registrytypes.RequestAuthConfig
RegistryAuthenticationPrivilegedFunc returns a RequestPrivilegeFunc from the specified registry index info for the given command.
func ResolveAuthConfig ¶
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.
It is similar to [registry.ResolveAuthConfig], but uses the credentials- store, instead of looking up credentials from a map.
func RetrieveAuthTokenFromImage ¶
func RetrieveAuthTokenFromImage(cfg *configfile.ConfigFile, image string) (string, error)
RetrieveAuthTokenFromImage retrieves an encoded auth token given a complete image. The auth configuration is serialized as a base64url encoded RFC4648, section 5) JSON string for sending through the X-Registry-Auth header.
For details on base64url encoding, see: - RFC4648, section 5: https://tools.ietf.org/html/rfc4648#section-5
func StringSliceReplaceAt ¶
StringSliceReplaceAt replaces the sub-slice find, with the sub-slice replace, in the string slice s, returning a new slice and a boolean indicating if the replacement happened. requireIdx is the index at which old needs to be found at (or -1 to disregard that).
func UserAgent ¶
func UserAgent() string
UserAgent returns the user agent string used for making API requests
func ValidateMountWithAPIVersion ¶
func ValidateMountWithAPIVersion(m mounttypes.Mount, serverAPIVersion string) error
ValidateMountWithAPIVersion validates a mount with the server API version.
func ValidateOutputPath ¶
ValidateOutputPath validates the output paths of the `export` and `save` commands.
func ValidateOutputPathFileMode ¶
ValidateOutputPathFileMode validates the output paths of the `cp` command and serves as a helper to `ValidateOutputPath`
Types ¶
type CLIOption ¶
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 ¶
WithAPIClient configures the cli to use the given API client.
func WithBaseContext ¶
WithBaseContext sets the base context of a cli. It is used to propagate the context from the command line to the client.
func WithCombinedStreams ¶
WithCombinedStreams uses the same stream for the output and error streams.
func WithContentTrust ¶
WithContentTrust enables content trust on a cli.
func WithContentTrustFromEnv ¶
func WithContentTrustFromEnv() CLIOption
WithContentTrustFromEnv enables content trust on a cli from environment variable DOCKER_CONTENT_TRUST value.
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 ¶
WithErrorStream sets a cli error stream.
func WithInitializeClient ¶
func WithInitializeClient(makeClient func(dockerCli *DockerCli) (client.APIClient, error)) CLIOption
WithInitializeClient is passed to DockerCli.Initialize by callers who wish to set a particular API Client for use by the CLI.
func WithInputStream ¶
func WithInputStream(in io.ReadCloser) CLIOption
WithInputStream sets a cli input stream.
func WithOutputStream ¶
WithOutputStream sets a cli output stream.
func WithResource ¶
WithResource overwrites the default resource and prevents its creation.
func WithResourceOptions ¶
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.
type Cli ¶
type Cli interface { Client() client.APIClient Streams SetIn(in *streams.In) Apply(ops ...CLIOption) error ConfigFile() *configfile.ConfigFile ServerInfo() ServerInfo NotaryClient(imgRefAndAuth trust.ImageRefAndAuth, actions []string) (notaryclient.Repository, error) DefaultVersion() string CurrentVersion() string ManifestStore() manifeststore.Store RegistryClient(bool) registryclient.RegistryClient ContentTrustEnabled() bool 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
func ResolveDefaultContext ¶
func ResolveDefaultContext(opts *cliflags.ClientOptions, config store.Config) (*DefaultContext, error)
ResolveDefaultContext creates a Metadata for the current CLI invocation parameters
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 can be returned from NewDockerCli.
func NewDockerCli ¶
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 ¶
BuildKitEnabled returns buildkit is enabled or not.
func (*DockerCli) ConfigFile ¶
func (cli *DockerCli) ConfigFile() *configfile.ConfigFile
ConfigFile returns the ConfigFile
func (*DockerCli) ContentTrustEnabled ¶
ContentTrustEnabled returns whether content trust has been enabled by an environment variable.
func (*DockerCli) ContextStore ¶
ContextStore returns the ContextStore
func (*DockerCli) CurrentContext ¶
CurrentContext returns the current context name, based on flags, environment variables and the cli configuration file, in the following order of preference:
- The "--context" command-line option.
- The "DOCKER_CONTEXT" environment variable (EnvOverrideContext).
- The current context as configured through the in "currentContext" field in the CLI configuration file ("~/.docker/config.json").
- 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 ¶
CurrentVersion returns the API version currently negotiated, or the default version otherwise.
func (*DockerCli) DefaultVersion ¶
DefaultVersion returns api.defaultVersion.
func (*DockerCli) DockerEndpoint ¶
DockerEndpoint returns the current docker endpoint
func (*DockerCli) HooksEnabled ¶
HooksEnabled returns whether plugin hooks are enabled.
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 ¶
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) ManifestStore ¶
func (cli *DockerCli) ManifestStore() manifeststore.Store
ManifestStore returns a store for local manifests
func (*DockerCli) MeterProvider ¶
func (cli *DockerCli) MeterProvider() metric.MeterProvider
func (*DockerCli) NotaryClient ¶
func (cli *DockerCli) NotaryClient(imgRefAndAuth trust.ImageRefAndAuth, actions []string) (notaryclient.Repository, error)
NotaryClient provides a Notary Repository to interact with signed metadata for an image
func (*DockerCli) RegistryClient ¶
func (cli *DockerCli) RegistryClient(allowInsecure bool) registryclient.RegistryClient
RegistryClient returns a client for communicating with a Docker distribution registry
func (*DockerCli) ServerInfo ¶
func (cli *DockerCli) ServerInfo() ServerInfo
ServerInfo returns the server version details for the host this client is connected to
func (*DockerCli) StartInstrumentation ¶
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 (cli *DockerCli) TracerProvider() trace.TracerProvider
type DockerContext ¶
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 types.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 *swarm.Status }
ServerInfo stores details about the supported features and platform of the server
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.