compose/pkg/api/labels.go
Nicolas De Loof eaf172eab2 feat: reconciliation plan creates pre_start hook runners
pre_start hook containers become first-class resources of the
reconciliation plan. The reconciler plans one OpCreateHookContainer per
declared hook — gated on the same predicate the start phase uses to run
the hooks: a replica to start and no running replica SURVIVING the plan
(a recreated replica is not running at start time, so its runners are
planned too). Runner creation depends on every replica node (the
executor resolves the VolumesFrom target against a final live view),
on the infrastructure, and on the purge of previously observed runners:
names are deterministic (<project>-<service>-pre_start-<i>) so repeated
plans converge on the same container instead of accumulating anonymous
ones, and a new HookIndexLabel ties each runner to its hook.

runPreStart becomes pure execution: it looks up the created-state
runner for each hook by label and never creates one. A declared hook
without a prepared runner is an actionable error naming the
reconciliation command (docker compose up <service>) — the accepted
consequence is that stop-then-start of a hooked service errors, since
runners are consumed on success (locked by e2e). Success removal,
failure retention and cancellation cleanup are unchanged.

Runners stay invisible to the start/ps container listings — they carry
no ConfigHashLabel, which getDefaultFilters requires — and down keeps
removing them by hook label.

Rebased onto main, which diverged substantially since this branch was
opened (the unrelated container-spec-layering refactor, #14093,
restructured compose-go's ServiceConfig/PreStartHook types this PR also
touches). Reconciling pre_start.go/pre_start_test.go against that
refactor surfaced a real bug: createPreStartContainer builds the hook's
config via the shared getCreateConfigs, which unconditionally stamps a
ConfigHashLabel — silently contradicting this same commit's own
"invisible to ps/start" guarantee above, since that label is exactly
what getDefaultFilters requires. Fixed by deleting the label after
getCreateConfigs returns, with a test asserting its absence (an
independent local review, via the GitHub Copilot CLI, and a
fresh-context review agent both converged on catching this during
rebase verification). Also restored two security/label tests that only
existed on one side of the rebase (SecuritySensitiveFieldsHonored,
HookLabelsMerged), ported to call createPreStartContainer directly.

Also addresses glours' three review comments on this PR: hook-container
create operations for a service no longer chain serially (each depends
on the same shared containerNodes+infraDeps+purges set, letting the
executor create them in parallel), the corresponding plan-string test
assertion, and a clearer missing-runner error message hinting this
isn't necessarily a planning bug.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
2026-09-30 12:03:10 +02:00

92 lines
4.5 KiB
Go

/*
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.
*/
package api
import (
"github.com/hashicorp/go-version"
"github.com/docker/compose/v5/internal"
)
const (
// ProjectLabel allow to track resource related to a compose project
ProjectLabel = "com.docker.compose.project"
// ServiceLabel allow to track resource related to a compose service
ServiceLabel = "com.docker.compose.service"
// ConfigHashLabel stores configuration hash for a compose service
ConfigHashLabel = "com.docker.compose.config-hash"
// ContainerNumberLabel stores the container index of a replicated service
ContainerNumberLabel = "com.docker.compose.container-number"
// VolumeLabel allow to track resource related to a compose volume
VolumeLabel = "com.docker.compose.volume"
// NetworkLabel allow to track resource related to a compose network
NetworkLabel = "com.docker.compose.network"
// WorkingDirLabel stores absolute path to compose project working directory
WorkingDirLabel = "com.docker.compose.project.working_dir"
// ConfigFilesLabel stores absolute path to compose project configuration files
ConfigFilesLabel = "com.docker.compose.project.config_files"
// EnvironmentFileLabel stores absolute path to compose project env file set by `--env-file`
EnvironmentFileLabel = "com.docker.compose.project.environment_file"
// OneoffLabel stores value 'True' for one-off containers created by `compose run`
OneoffLabel = "com.docker.compose.oneoff"
// RelayLabel marks the network relay container compose deploys in place
// of a provider-managed service (see the publish-endpoint provider
// message). Its value is a hash of the relay's routes, used to decide
// whether an existing relay can be kept on the next up. Commands that
// act on a service's process (exec, ...) refuse relay containers.
RelayLabel = "com.docker.compose.relay"
// SlugLabel stores unique slug used for one-off container identity
SlugLabel = "com.docker.compose.slug"
// ImageDigestLabel stores digest of the container image used to run service
ImageDigestLabel = "com.docker.compose.image"
// ImageVolumeDigestLabel stores the content digest of each `type: image`
// volume's source image, as "target=digest" pairs joined by ",", so
// mustRecreate can detect a rebuilt/updated source image independently of
// the mount Source (which must stay a resolvable name, not a digest).
ImageVolumeDigestLabel = "com.docker.compose.image-volume-digest"
// DependenciesLabel stores service dependencies
DependenciesLabel = "com.docker.compose.depends_on"
// VersionLabel stores the compose tool version used to build/run application
VersionLabel = "com.docker.compose.version"
// ImageBuilderLabel stores the builder (classic or BuildKit) used to produce the image.
ImageBuilderLabel = "com.docker.compose.image.builder"
// ContainerReplaceLabel is set when container is created to replace another container (recreated)
ContainerReplaceLabel = "com.docker.compose.replace"
// ContainerEngineLabel stores the name of the engine that runs the container
ContainerEngineLabel = "com.docker.compose.engine"
// HookLabel identifies an ephemeral lifecycle-hook container and stores the
// hook type, e.g. "pre_start". It is applied to every runner container
// created by createPreStartContainer so stale runners from a previous
// failed run can be found and removed by project+service+hook label
// filters, and down can sweep them all by project+hook label.
HookLabel = "com.docker.compose.hook"
// HookIndexLabel stores the position of the hook in its service's hook
// list (e.g. pre_start[2] → "2"), so the start phase can match each
// declared hook with the runner container the reconciliation plan
// prepared for it.
HookIndexLabel = "com.docker.compose.hook-index"
)
// ComposeVersion is the compose tool version as declared by label VersionLabel
var ComposeVersion string
func init() {
v, err := version.NewVersion(internal.Version)
if err == nil {
ComposeVersion = v.Core().String()
}
}