Documentation
¶
Overview ¶
Copyright 2020 Docker Compose CLI authors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Index ¶
- Constants
- func ImageDigestResolver(ctx context.Context, file *configfile.ConfigFile, apiClient client.APIClient) func(named reference.Named) (digest.Digest, error)
- func InDependencyOrder(ctx context.Context, project *types.Project, ...) error
- func InReverseDependencyOrder(ctx context.Context, project *types.Project, ...) error
- func NetworkHash(o *types.NetworkConfig) (string, error)
- func NewComposeService(dockerCli command.Cli, options ...Option) (api.Compose, error)
- func Run(ctx context.Context, pf progressFunc, operation string, bus api.EventProcessor) error
- func ServiceHash(o types.ServiceConfig) (string, error)
- func ToMobyEnv(environment compose.MappingWithEquals) []string
- func ToSeconds(d *compose.Duration) *int
- func VolumeHash(o types.VolumeConfig) (string, error)
- func WithDryRun(s *composeService) error
- func WithRootNodesAndDown(nodes []string) func(*graphTraversal)
- type CommandMetadata
- type ContainerStdin
- type ContainerStdout
- type Containers
- type Graph
- func (g *Graph) AddEdge(source string, destination string) error
- func (g *Graph) AddVertex(key string, service string, initialStatus ServiceStatus)
- func (g *Graph) FilterChildren(key string, status ServiceStatus) []*Vertex
- func (g *Graph) FilterParents(key string, status ServiceStatus) []*Vertex
- func (g *Graph) HasCycles() (bool, error)
- func (g *Graph) Leaves() []*Vertex
- func (g *Graph) Roots() []*Vertex
- func (g *Graph) UpdateStatus(key string, status ServiceStatus)
- type ImagePruneMode
- type ImagePruneOptions
- type ImagePruner
- type JsonMessage
- type Model
- type ObservedContainer
- type ObservedNetwork
- type ObservedState
- type ObservedVolume
- type Operation
- type OperationType
- type Option
- func WithContextInfo(info api.ContextInfo) Option
- func WithErrorStream(err io.Writer) Option
- func WithEventProcessor(bus api.EventProcessor) Option
- func WithInputStream(in io.Reader) Option
- func WithMaxConcurrency(maxConcurrency int) Option
- func WithOutputStream(out io.Writer) Option
- func WithPrompt(prompt Prompt) Option
- func WithProxyConfig(config map[string]string) Option
- func WithStreams(out, err io.Writer, in io.Reader) Option
- type ParameterMetadata
- type Plan
- type PlanNode
- type Prompt
- type ProviderMetadata
- type ReconcileOptions
- type ServiceStatus
- type Vertex
- type WatchFunc
- type Watcher
Constants ¶
const ( ErrorType = "error" InfoType = "info" SetEnvType = "setenv" RawSetEnvType = "rawsetenv" DebugType = "debug" )
const ( PreparingPhase = "Preparing" WaitingPhase = "waiting" PullingFsPhase = "Pulling fs layer" DownloadingPhase = "Downloading" DownloadCompletePhase = "Download complete" ExtractingPhase = "Extracting" VerifyingChecksumPhase = "Verifying Checksum" AlreadyExistsPhase = "Already exists" PullCompletePhase = "Pull complete" )
const (
// DockerEngineV28_1 is the specific version string for Docker Engine 28.1
DockerEngineV28_1 = "v28.1"
)
Docker Engine version strings for user-facing error messages. These should be used in error messages to provide clear version requirements.
const ServiceConditionRunningOrHealthy = "running_or_healthy"
ServiceConditionRunningOrHealthy is a service condition on status running or healthy
Variables ¶
This section is empty.
Functions ¶
func ImageDigestResolver ¶
func ImageDigestResolver(ctx context.Context, file *configfile.ConfigFile, apiClient client.APIClient) func(named reference.Named) (digest.Digest, error)
ImageDigestResolver creates a func able to resolve image digest from a docker ref,
func InDependencyOrder ¶
func InDependencyOrder(ctx context.Context, project *types.Project, fn func(context.Context, string) error, options ...func(*graphTraversal)) error
InDependencyOrder applies the function to the services of the project taking in account the dependency order
func InReverseDependencyOrder ¶
func InReverseDependencyOrder(ctx context.Context, project *types.Project, fn func(context.Context, string) error, options ...func(*graphTraversal)) error
InReverseDependencyOrder applies the function to the services of the project in reverse order of dependencies
func NetworkHash ¶
func NetworkHash(o *types.NetworkConfig) (string, error)
NetworkHash computes the configuration hash for a network.
func NewComposeService ¶
NewComposeService creates a Compose service using Docker CLI. This is the standard constructor that requires command.Cli for full functionality.
Example usage:
dockerCli, _ := command.NewDockerCli() service := NewComposeService(dockerCli)
For advanced configuration with custom overrides, use ServiceOption functions:
service := NewComposeService(dockerCli,
WithPrompt(prompt.NewPrompt(cli.In(), cli.Out()).Confirm),
WithOutputStream(customOut),
WithErrorStream(customErr),
WithInputStream(customIn))
Or set all streams at once:
service := NewComposeService(dockerCli,
WithStreams(customOut, customErr, customIn))
func ServiceHash ¶
func ServiceHash(o types.ServiceConfig) (string, error)
ServiceHash computes the configuration hash for a service.
func ToMobyEnv ¶
func ToMobyEnv(environment compose.MappingWithEquals) []string
ToMobyEnv convert into []string
func VolumeHash ¶
func VolumeHash(o types.VolumeConfig) (string, error)
VolumeHash computes the configuration hash for a volume.
func WithDryRun ¶
func WithDryRun(s *composeService) error
WithDryRun configure Compose to run without actually applying changes
func WithRootNodesAndDown ¶
func WithRootNodesAndDown(nodes []string) func(*graphTraversal)
Types ¶
type CommandMetadata ¶
type CommandMetadata struct {
Parameters []ParameterMetadata `json:"parameters"`
}
func (CommandMetadata) CheckRequiredParameters ¶
func (c CommandMetadata) CheckRequiredParameters(provider types.ServiceProviderConfig) error
func (CommandMetadata) GetParameter ¶
func (c CommandMetadata) GetParameter(paramName string) (ParameterMetadata, bool)
type ContainerStdin ¶
type ContainerStdin struct {
client.HijackedResponse
}
ContainerStdin implement WriteCloser for moby.HijackedResponse
type ContainerStdout ¶
type ContainerStdout struct {
client.HijackedResponse
}
ContainerStdout implement ReadCloser for moby.HijackedResponse
type Graph ¶
Graph represents project as service dependencies
func NewGraph ¶
func NewGraph(project *types.Project, initialStatus ServiceStatus) (*Graph, error)
NewGraph returns the dependency graph of the services
func (*Graph) AddEdge ¶
AddEdge adds a relationship of dependency between vertices `source` and `destination`
func (*Graph) AddVertex ¶
func (g *Graph) AddVertex(key string, service string, initialStatus ServiceStatus)
AddVertex adds a vertex to the Graph
func (*Graph) FilterChildren ¶
func (g *Graph) FilterChildren(key string, status ServiceStatus) []*Vertex
FilterChildren returns children of a certain vertex that are in a certain status
func (*Graph) FilterParents ¶
func (g *Graph) FilterParents(key string, status ServiceStatus) []*Vertex
FilterParents returns the parents of a certain vertex that are in a certain status
func (*Graph) UpdateStatus ¶
func (g *Graph) UpdateStatus(key string, status ServiceStatus)
UpdateStatus updates the status of a certain vertex
type ImagePruneMode ¶
type ImagePruneMode string
ImagePruneMode controls how aggressively images associated with the project are removed from the engine.
const ( // ImagePruneNone indicates that no project images should be removed. ImagePruneNone ImagePruneMode = "" // ImagePruneLocal indicates that only images built locally by Compose // should be removed. ImagePruneLocal ImagePruneMode = "local" // ImagePruneAll indicates that all project-associated images, including // remote images should be removed. ImagePruneAll ImagePruneMode = "all" )
type ImagePruneOptions ¶
type ImagePruneOptions struct {
Mode ImagePruneMode
// RemoveOrphans will result in the removal of images that were built for
// the project regardless of whether they are for a known service if true.
RemoveOrphans bool
}
ImagePruneOptions controls the behavior of image pruning.
type ImagePruner ¶
type ImagePruner struct {
// contains filtered or unexported fields
}
ImagePruner handles image removal during Compose `down` operations.
func NewImagePruner ¶
func NewImagePruner(imageClient client.ImageAPIClient, project *types.Project) *ImagePruner
NewImagePruner creates an ImagePruner object for a project.
func (*ImagePruner) ImagesToPrune ¶
func (p *ImagePruner) ImagesToPrune(ctx context.Context, opts ImagePruneOptions) ([]string, error)
ImagesToPrune returns the set of images that should be removed.
type JsonMessage ¶
type Model ¶
type Model struct {
Id string `json:"id"`
Tags []string `json:"tags"`
Created int `json:"created"`
Config struct {
Format string `json:"format"`
Quantization string `json:"quantization"`
Parameters string `json:"parameters"`
Architecture string `json:"architecture"`
Size string `json:"size"`
} `json:"config"`
}
type ObservedContainer ¶ added in v5.2.0
type ObservedContainer struct {
ID string
Name string
State container.ContainerState // "running", "exited", "created", "restarting", etc.
ConfigHash string // label com.docker.compose.config-hash
ImageDigest string // label com.docker.compose.image
Number int // label com.docker.compose.container-number
// ConnectedNetworks maps network IDs found in the container's network
// settings. Key is the network name as seen by Docker, value is the
// network ID.
ConnectedNetworks map[string]string
// Raw summary kept for the executor which needs it to call Moby APIs.
Summary container.Summary
}
ObservedContainer holds the relevant state extracted from a running or stopped container, with label values pre-parsed for efficient comparison.
type ObservedNetwork ¶ added in v5.2.0
type ObservedNetwork struct {
ID string
Name string
ConfigHash string // label com.docker.compose.config-hash
ProjectName string // label com.docker.compose.project
}
ObservedNetwork holds the state of a Docker network that belongs to the project, identified by the com.docker.compose.network label.
type ObservedState ¶ added in v5.2.0
type ObservedState struct {
ProjectName string
Containers map[string][]ObservedContainer // service name → containers
Orphans []ObservedContainer // containers with no matching service
Networks map[string]ObservedNetwork // compose network key → observed
Volumes map[string]ObservedVolume // compose volume key → observed
}
ObservedState captures the current state of all Docker resources belonging to a Compose project. It is a snapshot taken before reconciliation so that the reconciler can compare desired state (types.Project) with reality without making any further API calls.
type ObservedVolume ¶ added in v5.2.0
type ObservedVolume struct {
Name string
ConfigHash string // label com.docker.compose.config-hash
ProjectName string // label com.docker.compose.project
Driver string
}
ObservedVolume holds the state of a Docker volume that belongs to the project, identified by the com.docker.compose.volume label.
type Operation ¶ added in v5.2.0
type Operation struct {
Type OperationType
ResourceID string // e.g. "service:web:1", "network:backend", "volume:data"
Cause string // why this operation is needed
// Resource-specific data (only the relevant fields are set per operation type)
Service *types.ServiceConfig // for container operations
Container *container.Summary // existing container (for stop/remove)
Inherited *container.Summary // container to inherit anonymous volumes from (for create-as-replacement)
Number int // container replica number (for create)
Name string // target container/resource name
Network *types.NetworkConfig // for network operations
Volume *types.VolumeConfig // for volume operations
Timeout *time.Duration // for stop operations
CreateNodeID int // for OpRenameContainer: ID of the CreateContainer node whose result to rename
}
Operation describes a single atomic action to be performed by the executor.
type OperationType ¶ added in v5.2.0
type OperationType int
OperationType identifies the kind of atomic operation in a reconciliation plan. Each operation maps to exactly one Docker API call.
const ( // Network operations OpCreateNetwork OperationType = 1 OpRemoveNetwork OperationType = 2 OpDisconnectNetwork OperationType = 3 OpConnectNetwork OperationType = 4 // Volume operations OpCreateVolume OperationType = 10 OpRemoveVolume OperationType = 11 // Container operations OpCreateContainer OperationType = 20 OpStartContainer OperationType = 21 OpStopContainer OperationType = 22 OpRemoveContainer OperationType = 23 OpRenameContainer OperationType = 24 // Provider operations OpRunProvider OperationType = 30 )
OperationType values are explicit so that adding a new op in the middle of the list does not silently shift other values.
func (OperationType) String ¶ added in v5.2.0
func (o OperationType) String() string
String returns the human-readable name of an OperationType.
type Option ¶
type Option func(service *composeService) error
func WithContextInfo ¶
func WithContextInfo(info api.ContextInfo) Option
WithContextInfo sets custom Docker context information
func WithErrorStream ¶
WithErrorStream sets a custom error stream
func WithEventProcessor ¶
func WithEventProcessor(bus api.EventProcessor) Option
WithEventProcessor configure component to get notified on Compose operation and progress events. Typically used to configure a progress UI
func WithInputStream ¶
WithInputStream sets a custom input stream
func WithMaxConcurrency ¶
WithMaxConcurrency defines upper limit for concurrent operations against engine API
func WithOutputStream ¶
WithOutputStream sets a custom output stream
func WithPrompt ¶
WithPrompt configure a UI component for Compose service to interact with user and confirm actions
func WithProxyConfig ¶
WithProxyConfig sets custom HTTP proxy configuration for builds
type ParameterMetadata ¶
type Plan ¶ added in v5.2.0
type Plan struct {
Nodes []*PlanNode
// contains filtered or unexported fields
}
Plan is a directed acyclic graph of operations produced by the reconciler. Nodes are stored in topological order (dependencies before dependents).
func (*Plan) String ¶ added in v5.2.0
String renders the plan as a human-readable graph for testing and debugging.
Format per line: [dep1,dep2] -> #id resource, operation, cause [group]
Examples:
[] -> #1 network:default, CreateNetwork, not found [1] -> #2 service:web:1, CreateContainer, no existing container [2] -> #3 service:web:1, StopContainer, replaced by #2 [recreate:web:1]
type PlanNode ¶ added in v5.2.0
type PlanNode struct {
ID int // numeric identifier (#1, #2, ...)
Operation Operation
DependsOn []*PlanNode // prerequisite operations
Group string // event grouping key (e.g. "recreate:web:1"); empty for ungrouped nodes
}
PlanNode is a single node in the reconciliation DAG. It represents one atomic operation and its dependencies on other nodes.
type Prompt ¶
func AlwaysOkPrompt ¶
func AlwaysOkPrompt() Prompt
AlwaysOkPrompt returns a Prompt implementation that always returns true without user interaction.
type ProviderMetadata ¶
type ProviderMetadata struct {
Description string `json:"description"`
Up CommandMetadata `json:"up"`
Down CommandMetadata `json:"down"`
Stop *CommandMetadata `json:"stop,omitempty"`
}
func (ProviderMetadata) IsEmpty ¶
func (p ProviderMetadata) IsEmpty() bool
type ReconcileOptions ¶ added in v5.2.0
type ReconcileOptions struct {
Services []string // targeted services (empty = all)
Recreate string // "diverged", "force", "never" for targeted services
RecreateDependencies string // same for non-targeted services
Inherit bool // inherit anonymous volumes on recreate
Timeout *time.Duration // for stop operations
RemoveOrphans bool
SkipProviders bool
}
ReconcileOptions controls how the reconciler compares desired and observed state.
type ServiceStatus ¶
type ServiceStatus int
ServiceStatus indicates the status of a service
const ( ServiceStopped ServiceStatus = iota ServiceStarted )
Services status flags
type Vertex ¶
type Vertex struct {
Key string
Service string
Status ServiceStatus
Children map[string]*Vertex
Parents map[string]*Vertex
}
Vertex represents a service in the dependencies structure
func NewVertex ¶
func NewVertex(key string, service string, initialStatus ServiceStatus) *Vertex
NewVertex is the constructor function for the Vertex
func (*Vertex) GetChildren ¶
GetChildren returns a slice with the child vertices of the Vertex
func (*Vertex) GetParents ¶
GetParents returns a slice with the parent vertices of the Vertex
Source Files
¶
- apiSocket.go
- api_versions.go
- attach.go
- attach_service.go
- build.go
- build_bake.go
- build_classic.go
- commit.go
- compose.go
- container.go
- containers.go
- convergence.go
- convert.go
- cp.go
- create.go
- dependencies.go
- desktop.go
- docker_cli_providers.go
- down.go
- envresolver.go
- events.go
- exec.go
- executor.go
- executor_events.go
- executor_ops.go
- export.go
- filters.go
- generate.go
- hash.go
- hook.go
- image_pruner.go
- images.go
- kill.go
- loader.go
- logs.go
- ls.go
- model.go
- monitor.go
- observed_state.go
- pause.go
- plan.go
- plugins.go
- port.go
- printer.go
- progress.go
- ps.go
- publish.go
- pull.go
- push.go
- reconcile.go
- remove.go
- restart.go
- run.go
- scale.go
- secrets.go
- shellout.go
- start.go
- stop.go
- suffix_unix.go
- top.go
- up.go
- viz.go
- volumes.go
- wait.go
- watch.go