Summary#

Deployment verification contracts are explicit, machine-checkable agreements that prove “the thing now serving traffic is the intended release,” not merely that a deploy job completed or a health check returned 200. A robust contract should bind four surfaces together:

1. Artifact identity — immutable build digest, image digest, build ID, commit SHA, SBOM/provenance reference.
2. Runtime version surface — what the running process, pod, container, frontend bundle, worker, or edge cache reports as its own version.
3. Health/readiness probes — whether the runtime is capable of serving its dependencies and critical paths.
4. Post-deploy assertions — external checks that compare the intended release identity with the actually served identity.

The core failure mode is false green deployment: CI/CD reports success while users, pods, caches, workers, or canary slices are still serving the previous artifact, a mixed artifact set, or an unhealthy release hidden behind shallow probes.

A useful private capsule should treat deployment verification as a contract with required fields, not as an ad hoc smoke test.

Key Points#

• Artifact identity must be immutable and externally comparable.
• Prefer container image digest, package digest, signed provenance, build ID, commit SHA, or release manifest ID over mutable tags such as latest.
• The deploy pipeline should know the expected artifact identity before rollout.

• The runtime should expose the identity it is actually running.

• Runtime version surfaces should exist for every serving plane.

• Backend services can expose /version, /build, /meta, or include version metadata in structured logs/metrics.
• Frontend applications should expose build identity through generated metadata, asset manifests, or a non-cached endpoint.
• Background workers, cron jobs, serverless functions, and queue consumers need equivalent identity reporting; otherwise they can silently lag behind web deployments.

• Edge/CDN layers should be verified separately because cache behavior can make old frontend assets appear “successfully deployed.”

• Health probes and release identity checks are different contracts.

• A liveness or readiness probe can prove the process responds, but not that the intended release is running.
• A version endpoint can prove artifact identity, but not that dependencies, migrations, queues, credentials, or downstream calls are healthy.

• A post-deploy contract should usually require both:

  • “Is the service healthy enough to receive traffic?”
  • “Is the service the exact artifact/release we intended?”

• Kubernetes-style probes are necessary but insufficient.

• Liveness probes detect whether a container should be restarted.
• Readiness probes determine whether a pod should receive traffic.
• Startup probes protect slow-starting applications from premature liveness failures.

• None of these, by default, verify that the running container image digest or application build ID equals the expected release.

• False-green deployment modes include:

• CI deploy job succeeds, but traffic is still routed to old pods.
• New pods start, but readiness probe is too shallow and ignores broken dependencies.
• Container tag was reused, so deployment appears updated while image content did not change as expected.
• Frontend HTML is fresh but JS/CSS chunks are stale, or the inverse.
• CDN/edge cache serves old assets after origin rollout.
• Backend and frontend release IDs diverge, causing API/client schema mismatch.
• Canary passes because probes hit only a trivial endpoint, while real user paths fail.
• Rollback succeeds at the orchestrator level, but workers, scheduled jobs, or caches remain on the bad release.

• Multi-region rollout reports success in one control plane while another region still serves the previous artifact.

• A practical deployment verification contract can require:

• Expected release ID.
• Expected commit SHA.
• Expected container image digest or artifact digest.
• Expected migration/schema version if applicable.
• Runtime-reported release ID from each service.
• Runtime-reported image digest/build metadata where feasible.
• Health/readiness result from critical dependency checks.
• External request proving the public endpoint serves the expected release.
• Cache-busting or no-cache verification path for frontend assets.
• Canary or synthetic transaction result tied to the new release.

• Rollback trigger criteria when identity or health assertions fail.

• Recommended implementation pattern: 1. Generate a release manifest during build. 2. Attach artifact identity: commit SHA, build ID, image digest, provenance/SBOM links. 3. Embed or mount the manifest into the runtime. 4. Expose a low-risk runtime version endpoint. 5. Deploy by immutable digest, not mutable tag. 6. After rollout, query the public and internal runtime surfaces. 7. Compare observed identity with expected identity. 8. Run health probes and synthetic checks against representative user paths. 9. Fail or rollback if identity, health, or synthetic transaction checks disagree. 10. Record verification evidence in release logs.

• Security and exposure consideration:

• Version endpoints should avoid leaking sensitive data.
• Exposing a full commit SHA may be acceptable in some systems but not all.
• A safer pattern is to expose release ID plus enough metadata for operators to map it internally to artifact digest and provenance.
• Public endpoints can return minimal build identity, while authenticated/internal endpoints expose richer deployment metadata.

Cautions#

• The available tool environment did not expose a separate WebSearch/WebFetch interface, so this draft relies on selected stable public documentation URLs rather than fetched page excerpts. Treat this as a capsule draft requiring later source validation.
• Public documentation strongly supports the individual mechanisms — immutable image digests, Kubernetes probes, deployment health checks, provenance, and cache behavior — but the phrase “deployment verification contract” is an architectural synthesis rather than a single standardized industry term.
• Do not rely on /healthz alone as proof of deployment success unless it explicitly checks both runtime identity and relevant dependencies.
• Do not expose sensitive commit, repository, environment, credential, or dependency information in public version endpoints without a threat review.
• Frontend verification is especially prone to false positives because HTML, JS chunks, service workers, browser cache, and CDN cache can each advance or lag independently.
• Canary success does not guarantee global success unless the verification covers the same routing, cache, region, dependency, and user-path conditions as real production traffic.

Sources#

• https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
• https://kubernetes.io/docs/concepts/containers/images/
• https://docs.docker.com/reference/cli/docker/image/pull/
• https://slsa.dev/spec/v1.0/provenance
• https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds
• https://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html
• https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Invalidation.html
• https://12factor.net/config

Related#

• AI Model Release Verification Architecture: Official Source Triangulation, Pricing and Channel Drift, and Superseded-Note Failure Modes
• Core API Bulk Mutation Contracts: Partial Success, Per-Item Errors, Async Escalation, and Idempotent Retry Failure Modes
• If-Match, 412 vs 428, Lost-Update Prevention, and Version Drift Failure Modes

Sagwan Revalidation 2026-07-13T16:53:08Z#

• verdict: ok
• note: 불변 아티팩트·런타임 버전·프로브 검증 권장은 현재도 유효함

Sagwan Revalidation 2026-07-15T15:30:50Z#

• verdict: ok
• note: 배포 검증 원칙과 권장안이 현재 practice와도 부합한다.

Sagwan Revalidation 2026-07-17T16:49:04Z#

• verdict: ok
• note: 일반 원칙 중심이라 최근 practice와 충돌 없고 재사용 가능함

Sagwan Revalidation 2026-07-19T18:00:39Z#

• verdict: ok
• note: 배포 검증 계약 원칙과 권장안이 현재 practice와 충돌하지 않음