A container image may pass every application test and still introduce a security risk if the image comes from an untrusted source or has been replaced after it was built. Kubernetes can pull and run container images from registries, but pulling an image successfully does not prove that the image was produced by an authorized build pipeline.
This is where container image signatures become useful.
Image signing allows a trusted build process to sign an image or its immutable digest. Before deployment, a verification process checks that the signature is valid and that it belongs to an identity the organization trusts.
For Kubernetes teams, this helps prevent unauthorized images from reaching production. It can also support software supply chain security by connecting deployed images to approved build identities and release processes.
However, verifying a signature is not the same as proving that an image is safe. A valid signature only establishes that the signed artifact is associated with the signing identity and signing process. If an attacker compromises an authorized build pipeline, the pipeline may sign a malicious image.
A reliable deployment process therefore combines image signature verification with access controls, trusted build workflows, vulnerability scanning, provenance checks, and Kubernetes admission policies.
This article explains how image signatures work, how to verify signed container images, and how to enforce verification before Kubernetes allows a workload to run.
Understand Container Image Signatures
A container image is composed of manifests, configuration data, and filesystem layers. Registries store and distribute these components so that container runtimes can download and run them.
A tag such as myapp:latest is a human-readable reference, but it is mutable. The tag may point to one image today and a different image tomorrow.
An image digest identifies content by its cryptographic hash. For example, a deployment can reference an image using a SHA-256 digest rather than relying only on a tag.
Image signing adds a cryptographic signature associated with the image or its digest. A verification system checks the signature against the relevant artifact and evaluates whether the signer is trusted.
The process generally involves four stages:
- Build the container image.
- Identify the exact image digest.
- Sign the image or its digest using an authorized signing identity.
- Verify the signature and enforce the result before deployment.
The verification policy determines which signers are acceptable. A valid signature from an unknown identity should not automatically authorize an image for production.
Why Image Digests Matter
Consider a deployment that uses a mutable tag:
apiVersion: apps/v1
kind: Deployment
metadata:
name: orders-api
spec:
replicas: 3
selector:
matchLabels:
app: orders-api
template:
metadata:
labels:
app: orders-api
spec:
containers:
- name: orders-api
image: registry.example.com/orders-api:release
The tag release can be moved to another image. A review of the YAML file alone does not guarantee that the same image will run on every deployment.
A digest-pinned reference is more precise:
apiVersion: apps/v1
kind: Deployment
metadata:
name: orders-api
spec:
replicas: 3
selector:
matchLabels:
app: orders-api
template:
metadata:
labels:
app: orders-api
spec:
containers:
- name: orders-api
image: registry.example.com/orders-api@sha256:REPLACE_WITH_REAL_DIGEST
The digest shown here is a placeholder, not a usable image reference. Replace it with the actual digest produced by the build and publishing process.
Digest pinning ensures that the reference identifies specific image content. It does not, by itself, establish who built the image or whether the build was authorized. Signature verification addresses that separate question.
Choose a Signing and Verification Tool
Several tools support container image signing and verification. The appropriate choice depends on the registry, build system, Kubernetes environment, and security requirements.
Common options include:
- Cosign, part of the Sigstore ecosystem, for signing and verifying container images.
- Notation, which supports artifact signing and verification through the Notary Project ecosystem.
- Registry or platform integrations that provide signature verification and policy enforcement.
This article uses Cosign for the command-line examples. The commands and policy configuration should be checked against the version installed in your environment because tooling and integration details can change.
Before selecting a tool, determine how signing identities are managed, where signatures are stored, how trust is configured, and how verification is enforced during deployment.
Sign an Image After Building It
A typical pipeline builds an image, pushes it to a registry, obtains the immutable digest, and signs the resulting artifact.
For example, a build pipeline might push an image with a release tag:
docker build -t registry.example.com/orders-api:1.4.0 .
docker push registry.example.com/orders-api:1.4.0
The next step is to identify the digest associated with the pushed image. Use the registry or build tooling to obtain the actual digest rather than assuming the tag uniquely identifies the artifact.
With Cosign configured to use an appropriate signing identity, a signing command can look like this:
cosign sign registry.example.com/orders-api@sha256:ACTUAL_IMAGE_DIGEST
Replace the placeholder with the real digest. The signing method depends on the organization's identity and key-management setup. Cosign supports key-based signing and identity-based workflows, including keyless signing with an appropriate identity provider and transparency-log configuration.
Do not place private signing keys directly in source control or embed them in container images. Prefer managed identity, protected signing services, or a secure key-management solution suitable for the environment.
Signing should occur in a trusted pipeline after the artifact has been built and any required checks have passed. Access to the signing identity should be restricted to authorized workflows.
Verify the Signature Before Deployment
After an image has been signed, verification checks whether a valid signature is associated with the expected artifact and signer.
For a key-based workflow, a basic Cosign verification command can use a trusted public key:
cosign verify \
--key cosign.pub \
registry.example.com/orders-api@sha256:ACTUAL_IMAGE_DIGEST
The public key must come from a trusted source. An attacker who can replace both the image and the public key used for verification could undermine the process.
A successful verification indicates that the image has a signature that validates under the supplied trust configuration. It does not establish that the image is free of vulnerabilities or that the build process was uncompromised.
Verify the expected signing identity
For an identity-based workflow, verification should restrict the expected certificate identity and the identity provider that issued it.
The exact flags depend on the signing method and Cosign version. The policy should identify the expected signer as precisely as possible, rather than trusting any valid signature.
For example, a production policy might accept images only when the signing identity belongs to a designated build workflow in the organization's repository and uses the expected identity provider.
This reduces the risk that an image signed by an unrelated project or workflow will be accepted.
Test the verification command with both a valid image and an image signed by an untrusted identity. The second test is essential: a verification system is useful only if it rejects artifacts that do not meet the policy.
Integrate Verification into CI/CD
Verifying an image manually is useful during development, but production deployment should enforce the same policy automatically.
A typical CI/CD pipeline contains the following stages:
- Build the application and container image.
- Run unit and integration tests.
- Scan the image for known vulnerabilities.
- Push the image to the registry.
- Obtain the immutable image digest.
- Sign the image using the authorized build identity.
- Verify the signature and required metadata.
- Deploy the digest-pinned image to Kubernetes.
Verification in the pipeline catches mistakes before the deployment request is sent to the cluster. However, pipeline checks alone are not enough if users or other automation systems can deploy directly to Kubernetes.
A production cluster should also enforce the policy at the admission layer.
Make deployment fail when verification fails
The pipeline should treat failed verification as a blocking error. It should not continue to deployment because the signature is missing, the signer is unknown, or the artifact digest does not match.
Do not implement verification as a warning-only step for production releases unless the exception is explicitly part of an approved migration plan.
Log the failed check and provide enough context for troubleshooting, but avoid exposing secrets or sensitive signing material.
Enforce Signature Policies in Kubernetes
Kubernetes does not automatically verify every container image signature simply because an image has been signed. Enforcement requires an admission controller or another platform mechanism that evaluates deployment requests against a verification policy.
Common approaches include policy controllers and admission integrations that can inspect the requested image, resolve its digest, and validate the associated signature and signer identity.
For example, an admission policy might require that every image in a production namespace:
- Uses an approved registry.
- Is referenced by an immutable digest.
- Has a valid signature from an approved build identity.
- Meets any required provenance or attestation rules.
- Passes additional organization-specific policy checks.
The specific policy syntax depends on the chosen admission solution. Do not assume that a generic Kubernetes manifest can enforce image signatures without an installed component that implements that behavior.
Test the admission policy
Before enforcing a new policy across an entire production cluster, validate it in a test namespace or staging cluster.
Create deployment requests for several cases:
Test case | Expected result |
|---|
Image signed by the approved identity | Accepted if all other policy requirements pass |
Image with no signature | Rejected |
Image signed by an untrusted identity | Rejected |
Image whose digest differs from the signed artifact | Rejected |
Image from a disallowed registry | Rejected |
Validly signed image that fails another required policy | Rejected |
Also test workloads that use init containers, sidecars, and ephemeral containers if the selected admission policy is intended to cover those cases.
A policy that checks only the main application container may leave other execution paths unprotected.
Verify More Than the Signature
A valid signature is an important control, but it should be part of a broader software supply chain security process.
Check provenance
Build provenance records information about how an artifact was produced. Depending on the tooling, it can include the source repository, revision, build process, and builder identity.
An image can be signed but still fail an organization's provenance requirements. For example, the signature may be valid while the artifact was built from an unapproved source revision.
Where the signing ecosystem supports attestations, verify the required provenance claims as well as the image signature.
Scan for vulnerabilities
Signature verification does not indicate that an image is free from known vulnerabilities.
Continue to scan container images and evaluate findings according to the organization's risk policy. Depending on the environment, this may include operating-system packages, application dependencies, secrets, and configuration issues.
A signed image with a critical vulnerability may still need to be blocked from production.
Restrict registry and signing access
Use least-privilege access for image publishing and signing. Developers who can publish images should not automatically receive unrestricted access to production signing identities.
Separate build permissions, signing permissions, and production deployment permissions where practical. This makes it harder for one compromised credential to replace an image, sign it as trusted, and deploy it without additional checks.
Common Mistakes to Avoid
Trusting a signature without checking the signer
A cryptographically valid signature does not mean the signer is authorized to publish production software. Restrict verification to expected keys or identities.
Using tags as the only deployment reference
Tags can move. Use image digests to identify the exact artifact that was verified and deployed.
Verifying only in the pipeline
If the cluster accepts unverified images from other deployment paths, the policy can be bypassed. Enforce verification at admission as well.
Storing private keys in source control
A leaked signing key can allow an attacker to produce artifacts that pass verification. Use protected key management or an appropriately configured identity-based signing workflow.
Assuming signed images are secure
Signatures help establish artifact authenticity and trust. They do not replace vulnerability scanning, provenance validation, access controls, or runtime security.
Best Practices for Production Kubernetes Deployments
Define the trust policy before enabling enforcement. Identify approved registries, signing identities, key-management requirements, and any provenance or vulnerability conditions.
Use immutable image digests throughout the release process. Ensure that the digest verified by the pipeline is the same digest deployed to Kubernetes.
Keep signing credentials restricted and rotate them according to your organization's key-management requirements. Monitor signing and verification failures, and investigate unexpected attempts to deploy unsigned or untrusted artifacts.
Roll out admission policies in a test environment before enforcing them in production. Validate legitimate workloads, including sidecars and init containers, and document how authorized emergency exceptions are handled.
Finally, ensure that verification remains fail-closed for production deployments when the policy requires a trusted signature. If the verification service or registry is unavailable, decide explicitly whether deployment should stop rather than silently bypassing the control.
Advantages and Disadvantages
Advantages
- Helps prevent unauthorized or substituted images from reaching production.
- Connects container artifacts to approved signing identities.
- Supports repeatable verification in CI/CD pipelines and Kubernetes admission controls.
- Complements digest pinning, provenance validation, and vulnerability scanning.
- Provides useful evidence for software supply chain security reviews.
Disadvantages
- Requires signing infrastructure, trust configuration, and ongoing maintenance.
- Admission enforcement needs additional Kubernetes components or platform support.
- Incorrect identity policies can block legitimate deployments.
- Key compromise or a compromised authorized build pipeline can undermine trust.
- A valid signature does not guarantee that the image is vulnerability-free or safe to run.
Summary
Container image signature verification helps Kubernetes teams confirm that deployed images are associated with authorized signing identities. Start by signing images in a trusted build pipeline, identifying them by immutable digest, and verifying their signatures against a carefully defined trust policy.
Then enforce the same requirements at Kubernetes admission so that unsigned or untrusted images cannot bypass pipeline checks. Test both accepted and rejected deployment cases before applying the policy broadly.
Finally, combine signature verification with provenance checks, vulnerability scanning, registry restrictions, and secure signing practices. The objective is to establish a verifiable chain of trust from the build process to the image that Kubernetes actually runs.
Join the conversation! Your thoughts help the community grow.