{"canonical_url":"https://engineer.company/glossary/deployment/","content_markdown":"# Deployment\n\n## What it is\n\nDeployment is the sequence of steps that takes a tested version of an\napplication out of the build system and puts it into service: placing the built\nfiles or container image on the machines or platform that will run it, handing\nit the configuration for that environment, starting it, and moving real requests\nover to it. The word names both the act and the result, so a team talks about a\ndeployment that stalled at the database step and about the deployments currently\nrunning in each environment. What gets deployed can be a website, an API, a\nscheduled job, a database change or the backend behind a mobile app.\n\nDeploying and releasing are often kept apart. Deploying puts the new code where\nit can run; releasing decides who sees it. A feature hidden behind a flag can be\ndeployed on Monday and released to customers on Thursday without touching the\nservers again. Keeping the two separate lets a team ship code in small, frequent\nsteps while product decisions about timing stay with the people who own them.\n\nMany deployments today ship a container image. The Open Container Initiative,\nset up under the Linux Foundation in June 2015, publishes three specifications\naround it: how an image is laid out, how a runtime runs one once it is unpacked,\nand how registries store and hand images out. An image is identified by its\ndigest, a hash of its content, so the same digest always means the same bytes. A\ntag such as `1.4.2` is a readable pointer to an image, and pushing again under\nthat tag points it at something new.\n\nThe [Twelve-Factor App](https://12factor.net/), a widely cited methodology for\nbuilding web services, splits the path from code to running service into three\nstages kept strictly apart. The build stage turns a commit into an executable\nbundle. The release stage combines that bundle with one environment's\nconfiguration. The run stage starts processes from a chosen release. Each\nrelease gets a unique identifier and is never changed after it exists; any\nchange makes a new release, which is what turns rolling back into a matter of\nchoosing an earlier one.\n\nHow the switch happens varies with what the service can tolerate. A recreate\ndeploy stops the old version, then starts the new one, and accepts a gap in\nbetween. A rolling deploy replaces instances a few at a time, so both versions\nserve traffic for a while; it is the default for a Kubernetes Deployment. A\nblue-green deploy runs the new version beside the old and moves all traffic at\nonce, keeping the old one ready to take it back. A canary sends a small share of\ntraffic to the new version first and widens it while error rates and latency\nstay healthy.\n\n## Why it matters\n\nDeployment is the point where a change starts to help anyone, and also the point\nwhere a mistake starts to reach users. Teams that deploy rarely tend to collect\nmany changes into each release, so every deploy carries more risk and, when it\nbreaks, more candidates for the cause. Small, frequent deploys keep each step\neasy to understand and easy to reverse.\n\nA deploy run by hand is only as consistent as the person running it. Steps get\nskipped, done in a different order or done slightly differently by a colleague\ncovering a holiday. A pipeline performs the same steps every time and leaves a\nrecord of which commit, which artefact and which environment, with a timestamp.\nThat record is where an incident review starts, and it is often the fastest way\nto answer what changed.\n\nThe strongest habit is to build once and promote the result. The artefact tested\nin staging should be byte for byte the one that reaches production, with only\nthe configuration differing, and the environment supplies that configuration\nwhen the artefact arrives. Recording the digest at build time and deploying by\ndigest makes the promise checkable:\n\n```sh\npodman build -t registry.example.com/web:1.4.2 .\npodman push --digestfile web.digest registry.example.com/web:1.4.2\nkubectl -n staging set image deployment/web \\\n  web=registry.example.com/web@$(cat web.digest)\n# after staging checks pass, the same digest goes to production\nkubectl -n production set image deployment/web \\\n  web=registry.example.com/web@$(cat web.digest)\n```\n\nRollback depends on the same discipline. When releases are immutable and\nidentified, going back means pointing at the previous one, which takes seconds.\nWhen each environment rebuilds from source, going back means rebuilding an old\ncommit and hoping its dependencies still resolve the same way.\n\n## What it looks like in practice\n\n[Deployments of one platform to Azure were owned end to end](/portfolio/owned-end-to-end-platform-deployments-to-azure/),\nwith every change travelling the same fixed route from development to staging to\nproduction, and no one pushing straight into a live environment. CI/CD\nbuilds the images and ships them, while Bicep templates keep the target\ninfrastructure the same in each environment, so each promotion lands on matching\ninfrastructure. Settings that differ per environment are kept apart from the\nsecrets, which lets a single build travel through every stage and collect each\nenvironment's settings on arrival, with no rebuild along the way. Changes reach\neach environment along that defined path with no ad-hoc manual deploys, and\nreleasing became a controlled step that runs the same way each time.\n\nAn earlier engagement shows what that consistency is worth in hours.\n[Automating build, test and deployment saved roughly 4,000 hours](/portfolio/streamlined-ci-cd-processes-saving-4000-hours/)\nby standardising the path from a change to production and removing manual steps\nthat varied with whoever performed them. Releases became both faster and more\nreliable.\n\nOn the company's own platform, deploying is kept apart from provisioning.\n[A container plane built on Podman and Quadlet](/portfolio/ran-containers-on-podman-and-quadlet/)\nhas root prepare the deployment path once. After that, an unprivileged user\nredeploys by running a single fixed script through a narrowly scoped rule that\nallows that one command with no arguments. The script builds the image and\nrestarts the service, so a routine release needs no root shell and no arbitrary\ncommands.\n\n## Where it goes wrong\n\nMost deployment trouble comes from a difference between what was checked and\nwhat actually changed.\n\n**Production runs something staging never saw.** When each environment builds\nits own copy, dependency ranges resolve to newer versions, a base image moves\nbetween builds, or a build flag differs, and the artefact that passed testing is\nnot the one serving customers. Build once, record the digest, promote that\ndigest, and keep anything environment-specific in configuration rather than in\nthe artefact.\n\n**A tag moves, and a rollback lands on the wrong version.** A deploy that names\n`latest`, or reuses a version tag after a rebuild, depends on what the tag\npoints at on the day it runs. The Kubernetes documentation advises against\n`:latest` in production because it becomes harder to tell which version is\nrunning and harder to roll back properly. Use a version tag that is never\nreused, and pin the digest where the platform allows.\n\n**The pipeline reports success before the new version works.** Many deploy\ncommands return as soon as the platform accepts the request, while the new\ninstances are still starting and may crash a minute later. A step that waits for\nthe new version to report ready, then sends a few real requests and checks the\nanswers, turns a quiet failure into a red build while the previous release is\nstill close at hand.\n\n**New code and the old schema meet in the middle of a rollout.** During a\nrolling or canary deploy, old and new versions serve traffic side by side\nagainst one database. A migration that renames or drops a column breaks the old\ninstances still running, and makes rolling back unsafe because the old code\nexpects what was removed. Split such changes across deploys: add the new\nstructure first, ship code that works with both, and remove the old structure\nonly once no running version needs it.\n\n## Further reading\n\n- [Build, release, run](https://12factor.net/build-release-run) — the\n  Twelve-Factor App's case for three separate stages and releases that are never\n  changed once made.\n- [Open Container Initiative](https://opencontainers.org/) — the Linux\n  Foundation project behind the image, runtime and distribution specifications\n  that most container deployments rely on.\n- [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)\n  — manifests, layers, configuration and the content digests that identify an\n  image.\n- [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)\n  — rolling updates, the recreate strategy, the progress deadline and rollbacks.\n- [Kubernetes images](https://kubernetes.io/docs/concepts/containers/images/) —\n  tags, digests, pull policies and why `:latest` makes rollbacks harder.\n\n\u003chttps://engineer.company/glossary/deployment/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What a deployment involves, why one built artefact should travel unchanged from staging to production, and where releases most often break.","formats":{"gemtext":"https://engineer.company/glossary/deployment/index.gmi","gopher":"https://engineer.company/glossary/deployment/gophermap","html":"https://engineer.company/glossary/deployment/","json":"https://engineer.company/glossary/deployment/index.json","markdown":"https://engineer.company/glossary/deployment/index.md","pdf":"https://engineer.company/glossary/deployment/index.pdf"},"kind":"page","language":"en","title":"What is deployment?","url":"https://engineer.company/glossary/deployment/","version":1}