Skip to content

fix(docker): make Tentacle images OCI-compliant (FD-492) #1259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
todthomson wants to merge 6 commits into
base: main
Choose a base branch
from
+100 −40
Open

fix(docker): make Tentacle images OCI-compliant (FD-492) #1259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c43f87e
fix(docker): make Tentacle images OCI-compliant (FD-492)
todthomson Jun 18, 2026
db2914c
chore(docker): align attestation switch on BUILDX_NO_DEFAULT_ATTESTAT…
todthomson Jun 23, 2026
fafe56b
feat(docker): stamp OCI image-spec annotations on the k8s agent index…
todthomson Jun 23, 2026
95ca0c2
docs(docker): add keep-in-sync pointers for OCI image metadata (FD-492)
Jun 24, 2026
06aa414
refactor(docker): single build timestamp for k8s label + annotation (…
Jun 24, 2026
9cae415
fix(docker): guard against commas in k8s OCI annotation values (FD-492)
Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 58 additions & 4 deletions build/Build.Pack.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -727,14 +727,68 @@ void BuildAndPushOrLoadKubernetesTentacleContainerImage(bool push, bool load, st
if (includeDebugger)
tag += "-debug";

// Capture one timestamp and reuse it for both the BUILD_DATE build arg (which feeds
// the Dockerfile's org.opencontainers.image.created LABEL) and the created annotation
// below, so the image config and the manifest annotation report the same instant.
var buildDate = DateTime.UtcNow.ToString("O");

settings = settings
.AddBuildArg($"BUILD_NUMBER={FullSemVer}", $"BUILD_DATE={DateTime.UtcNow:O}", $"RuntimeDepsTag={runtimeDepsImageTag}")
.AddBuildArg($"BUILD_NUMBER={FullSemVer}", $"BUILD_DATE={buildDate}", $"RuntimeDepsTag={runtimeDepsImageTag}")
.SetPlatform(DockerPlatform)
.SetTag(tag)
.SetFile(dockerfile)
.SetPath(RootDirectory)
.SetPush(push)
.SetLoad(load);
.SetPath(RootDirectory);

if (push)
{
// FD-492: Force a single, consistent OCI media type across the whole image
// manifest and disable default attestations. Without this, buildx can emit
// a manifest that mixes Docker and OCI layer media types (and an attestation
// index), which strict OCI clients such as Podman reject - in particular when
// the image is used as a base image (FROM ...). BUILDX_NO_DEFAULT_ATTESTATIONS
// is used (rather than --provenance=false) so the same switch applies to both
// `docker buildx build` here and `docker buildx bake` in the TeamCity Linux
// image build (see OctopusDeploy/TeamCity-Configuration).
//
// We also stamp the OCI image-spec annotations (org.opencontainers.image.*)
// onto both the image index and each platform manifest. The Dockerfile LABELs
// set the same metadata on the image *config*; annotations are the spec-preferred
// location that registries and OCI tooling read from the manifest/index.
// Keep these values in sync with the org.opencontainers.image.* LABELs in
// docker/kubernetes-agent-tentacle/Dockerfile.

@matt-richardson matt-richardson Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude is over commenting - can we trim it down to things that future people will need when looking at the code.

Reasoning for "why are we making the changes" are much better as comments on a PR IMHO.

var annotations = new Dictionary<string, string>
{
["org.opencontainers.image.title"] = "Octopus Deploy Kubernetes Agent Tentacle",
["org.opencontainers.image.vendor"] = "Octopus Deploy",
["org.opencontainers.image.url"] = "https://octopus.com",
["org.opencontainers.image.source"] = "https://github.com/OctopusDeploy/OctopusTentacle",
["org.opencontainers.image.licenses"] = "Apache-2.0",
["org.opencontainers.image.description"] = "Octopus Kubernetes Agent Tentacle instance with auto-registration to Octopus Server",
["org.opencontainers.image.version"] = FullSemVer,
["org.opencontainers.image.created"] = buildDate,
};

// annotation-index.* lands on the image index, annotation.* on each platform manifest.
// Guard: annotation values are folded into the comma-separated buildx --output option
// list, so a comma in a value would corrupt it (the keys are fixed and comma-free).
var output = "type=image,oci-mediatypes=true,push=true";
foreach (var (key, value) in annotations)
{
if (value.Contains(','))
throw new InvalidOperationException(
$"OCI annotation '{key}' value must not contain a comma; it would break the buildx --output option list: '{value}'");

output += $",annotation-index.{key}={value},annotation.{key}={value}";
}
Comment on lines +771 to +782

@APErebus APErebus Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are controlling the annotations above and FullSemVer and buildDate will never have comma's, so this is a completely unnecessary guard + comment


settings = settings
.SetOutput(output)
.AddProcessEnvironmentVariable("BUILDX_NO_DEFAULT_ATTESTATIONS", "1");
}
else
{
settings = settings.SetLoad(load);
}

if (includeDebugger)
{
Expand Down
19 changes: 10 additions & 9 deletions docker/kubernetes-agent-tentacle/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,13 +115,14 @@ ENV TentaclePollingProxyPassword=""

ENTRYPOINT ["/scripts/configure-and-run.sh"]

# org.opencontainers.image.* metadata for the kubernetes-agent-tentacle image.
# Keep in sync with the OCI annotations set in build/Build.Pack.cs.
LABEL \
org.label-schema.schema-version="1.0" \
org.label-schema.name="Octopus Deploy Kubernetes Agent Tentacle" \
org.label-schema.vendor="Octopus Deploy" \
org.label-schema.url="https://octopus.com" \
org.label-schema.vcs-url="https://github.com/OctopusDeploy/OctopusTentacle" \
org.label-schema.license="Apache" \
org.label-schema.description="Octopus Kubernetes Agent Tentacle instance with auto-registration to Octopus Server" \
org.label-schema.version=${BUILD_NUMBER} \
org.label-schema.build-date=${BUILD_DATE}
org.opencontainers.image.title="Octopus Deploy Kubernetes Agent Tentacle" \
org.opencontainers.image.vendor="Octopus Deploy" \
org.opencontainers.image.url="https://octopus.com" \
org.opencontainers.image.source="https://github.com/OctopusDeploy/OctopusTentacle" \
org.opencontainers.image.licenses="Apache-2.0" \
org.opencontainers.image.description="Octopus Kubernetes Agent Tentacle instance with auto-registration to Octopus Server" \
org.opencontainers.image.version=${BUILD_NUMBER} \
org.opencontainers.image.created=${BUILD_DATE}
19 changes: 10 additions & 9 deletions docker/kubernetes-agent-tentacle/dev/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,16 +99,17 @@ ENV TentaclePollingProxyPassword=""

ENTRYPOINT [ "/dev-scripts/bootstrap.sh" ]

# org.opencontainers.image.* metadata for the dev/debug kubernetes tentacle image.
# Keep in sync with docker/kubernetes-agent-tentacle/Dockerfile.
LABEL \
org.label-schema.schema-version="1.0" \
org.label-schema.name="Octopus Deploy Kubernetes Tentacle" \
org.label-schema.vendor="Octopus Deploy" \
org.label-schema.url="https://octopus.com" \
org.label-schema.vcs-url="https://github.com/OctopusDeploy/OctopusTentacle" \
org.label-schema.license="Apache" \
org.label-schema.description="Octopus Kubernetes Tentacle instance with auto-registration to Octopus Server" \
org.label-schema.version=${BUILD_NUMBER} \
org.label-schema.build-date=${BUILD_DATE}
org.opencontainers.image.title="Octopus Deploy Kubernetes Tentacle" \
org.opencontainers.image.vendor="Octopus Deploy" \
org.opencontainers.image.url="https://octopus.com" \
org.opencontainers.image.source="https://github.com/OctopusDeploy/OctopusTentacle" \
org.opencontainers.image.licenses="Apache-2.0" \
org.opencontainers.image.description="Octopus Kubernetes Tentacle instance with auto-registration to Octopus Server" \
org.opencontainers.image.version=${BUILD_NUMBER} \
org.opencontainers.image.created=${BUILD_DATE}

# This installs the required tools, but there are versioning issues and it isn't working as expected

Expand Down
20 changes: 11 additions & 9 deletions docker/linux/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,13 +82,15 @@ VOLUME /var/lib/docker

ENTRYPOINT [ "/scripts/configure-and-run.sh" ]

# org.opencontainers.image.* metadata for the published octopusdeploy/tentacle image.
# Keep in sync with docker/windows/Dockerfile and the index annotations in the TeamCity
# "Build: Docker manifest" step (OctopusDeploy/TeamCity-Configuration).
LABEL \
org.label-schema.schema-version="1.0" \
org.label-schema.name="Octopus Deploy Tentacle" \
org.label-schema.vendor="Octopus Deploy" \
org.label-schema.url="https://octopus.com" \
org.label-schema.vcs-url="https://github.com/OctopusDeploy/OctopusTentacle" \
org.label-schema.license="Apache" \
org.label-schema.description="Octopus Tentacle instance with auto-registration to Octopus Server" \
org.label-schema.version=${BUILD_NUMBER} \
org.label-schema.build-date=${BUILD_DATE}
org.opencontainers.image.title="Octopus Deploy Tentacle" \
org.opencontainers.image.vendor="Octopus Deploy" \
org.opencontainers.image.url="https://octopus.com" \
org.opencontainers.image.source="https://github.com/OctopusDeploy/OctopusTentacle" \
org.opencontainers.image.licenses="Apache-2.0" \
org.opencontainers.image.description="Octopus Tentacle instance with auto-registration to Octopus Server" \
org.opencontainers.image.version=${BUILD_NUMBER} \
org.opencontainers.image.created=${BUILD_DATE}
20 changes: 11 additions & 9 deletions docker/windows/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,18 @@ ARG INSTALLATION_FOLDER="C:/Program Files/Octopus Deploy/Tentacle"
ENV TentacleVersion ${BUILD_NUMBER}
ENV OCTOPUS_RUNNING_IN_CONTAINER Y

# org.opencontainers.image.* metadata for the published octopusdeploy/tentacle image.
# Keep in sync with docker/linux/Dockerfile and the index annotations in the TeamCity
# "Build: Docker manifest" step (OctopusDeploy/TeamCity-Configuration).
LABEL \
org.label-schema.schema-version="1.0" \
org.label-schema.name="Octopus Deploy Tentacle" \
org.label-schema.vendor="Octopus Deploy" \
org.label-schema.url="https://octopus.com" \
org.label-schema.vcs-url="https://github.com/OctopusDeploy/OctopusTentacle" \
org.label-schema.license="Apache" \
org.label-schema.description="Octopus Tentacle instance with auto-registration to Octopus Server" \
org.label-schema.version=${BUILD_NUMBER} \
org.label-schema.build-date=${BUILD_DATE}
org.opencontainers.image.title="Octopus Deploy Tentacle" \
org.opencontainers.image.vendor="Octopus Deploy" \
org.opencontainers.image.url="https://octopus.com" \
org.opencontainers.image.source="https://github.com/OctopusDeploy/OctopusTentacle" \
org.opencontainers.image.licenses="Apache-2.0" \
org.opencontainers.image.description="Octopus Tentacle instance with auto-registration to Octopus Server" \
org.opencontainers.image.version=${BUILD_NUMBER} \
org.opencontainers.image.created=${BUILD_DATE}

EXPOSE 10933

Expand Down