Infrastructure as Code and Platform Engineering

Executive summary

Most infrastructure trouble starts with a change made by hand: a console edit or an ad hoc script, applied under deadline and never written down. From that moment environments diverge, and every new environment becomes a negotiation with a central team through a ticket queue. Three shifts address the problem. Infrastructure as code (IaC) makes the desired state declarative, versioned and reviewable. GitOps keeps running systems continuously reconciled to that declared state. An internal platform packages both into golden paths that teams use to provision and change infrastructure themselves, within guardrails, instead of filing tickets.

• Infrastructure as code differs from scripting through four principles: declarative desired state, idempotent apply, modules and composition, and immutable infrastructure.
• Every change follows one workflow: write and plan, review, test in an ephemeral stack, apply through automation, and verify against the desired state.
• One artifact is built once and promoted through environments of rising fidelity; a preview environment for each change is among the earliest wins.
• GitOps, as defined by the OpenGitOps principles, is declarative, versioned and immutable, pulled automatically and continuously reconciled.
• Platform engineering treats the platform as a product with internal customers, grown from the thinnest viable platform toward paved paths that are easier to use than to bypass.
• Guardrails such as landing zones, policy as code, mandatory tagging and cost budgets let teams move quickly without moving dangerously, and leave an audit trail as a by-product.

The implementation differs with scale. A small organization lets its application team write infrastructure code; a large one runs a dedicated platform organization with a governed module catalog, enforced GitOps and a FinOps practice. The closing sections describe the operating model, the pitfalls that recur, a five-stage maturity path and a first 90 days aimed at working evidence rather than a strategy document.

Why hand-built environments fail

Manual change is the root of most infrastructure trouble. A console edit or a one-off script solves the problem in front of someone, but nothing records it, so the next environment is built without it. Repeated across months and people, these unrecorded changes produce drift (an environment that no longer matches any definition) and snowflakes (environments that are each slightly different, so a release that works in one fails in another). Recovery becomes archaeology, because rebuilding a system means rediscovering every change ever made to it.

Manual environments also queue. When only a central team can create or change infrastructure, every request becomes a ticket, the team becomes a bottleneck and a single point of knowledge, and delivery teams build shadow workarounds around the queue. The cost is paid twice: in slower delivery, and in risk that no one can see.

Hand-built environments drift, differ and queue behind tickets; code, GitOps and a platform turn infrastructure into a product.

Three shifts answer this, and each builds on the one before. Infrastructure as code turns a change into a reviewed commit rather than a quiet edit. GitOps keeps running systems reconciled to the committed state and corrects drift when it appears. An internal platform packages both into paved paths that teams use without waiting. Guardrails, policy and cost controls run underneath all three.

Infrastructure as code foundations

Infrastructure as code is the practice of defining servers, networks, databases, permissions and the rest of an environment in machine-readable files that are versioned, reviewed and applied by tools rather than by hand. Keeping files in a repository is not enough on its own: a folder of scripts that someone runs from a laptop is still manual change. Four principles separate genuine infrastructure as code from scripting that happens to live in version control; Kief Morris's Infrastructure as Code explores the ideas behind them in depth.

Four principles

The principles reinforce one another. Declarative definitions make idempotence possible, because the tool always works toward a target rather than replaying a sequence of steps. Modules keep definitions maintainable as the estate grows, and immutability closes the last loophole: if no one edits a running system, the running system can only be what the definition says. Together they turn infrastructure from something that is administered into something that is built and released.

Imperative scripts and declarative desired state

The distinction between imperative and declarative approaches is the heart of the practice. An imperative script lists commands to run in order. Re-running it may fail halfway or apply a change twice, drift is hard to see because nothing states what the result should be, and the intended outcome is scattered across the logic. A declarative definition states the outcome and leaves the tool to reach it: a plan shows the gap between desired and actual before anything changes, and a reviewer reads the intended state directly in the diff.

Declarative and imperative are not rival camps. Most estates combine a declarative provisioning tool with some procedural glue, and general-purpose programming languages can express declarative intent. What matters is that the definition, not the procedure, is the source of truth.

A safe change workflow

A safe workflow turns every infrastructure change into a reviewed, testable event. The author writes the desired state and generates a plan that shows exactly what will be created, changed or destroyed, so surprises surface before they reach a system. Peers review the code and the plan together while static analysis and policy checks run automatically. The change is then applied to a temporary, ephemeral stack where integration tests confirm that it behaves, after which the stack is destroyed so that no one keeps paying for it. Only then is it applied to the real environment, by automation using least-privilege credentials rather than by a person with standing access. Finally the result is verified against the desired state, and any drift is detected and corrected.

The same workflow carries routine change, disaster recovery and experiments, and it runs in the delivery pipeline like any other code. Its value compounds: once every change passes through it, the repository history becomes a complete, reviewable record of how each environment came to be, and rebuilding an environment becomes a routine operation rather than a crisis.

Environments and promotion

Environments are where infrastructure as code pays off first, because the discipline that builds one environment from code can build any number of them. How an organization treats its environments, and how it moves changes between them, decides whether its path to production can be trusted.

Long-lived and ephemeral environments

Environments fall into two kinds. Long-lived environments such as staging and production persist, accumulate state and history, and are shared across teams, so changes need coordination, and drift creeps in unless every change goes through code. They also cost money whether or not anyone is using them. Ephemeral environments are created on demand from the same code and destroyed after use, typically one per change or pull request. Because each is built fresh, it cannot drift, and it costs money only while it exists.

The two kinds are complementary rather than competing. Defining everything as code is what makes ephemeral environments possible, and the same discipline keeps long-lived environments from drifting. A preview environment for every pull request, where reviewers can see and exercise the change running, is one of the clearest early wins of infrastructure as code: it shortens review, catches integration problems before merge and demonstrates the value of the approach to people who will never read a module.

Environment types on the path to production

A typical path to production runs through several environment types, each with a purpose, a lifetime and a data policy. Parity with production matters most where a result must be trusted; lower environments trade fidelity for speed and cost.

Three rules hold across the path. First, the same artifact is promoted from one environment to the next rather than rebuilt for each. Only building binaries once is one of the deployment pipeline practices that Jez Humble and David Farley set out in Continuous Delivery, and it ensures that what was tested is what ships. Second, configuration is separated from code and injected per environment, and secrets come from a managed secrets store at run time rather than from images or repositories. Third, production-like data reaches lower environments only through masking or synthetic generation under the organization's data classification policy, so that realistic testing never becomes an uncontrolled copy of production data.

GitOps and continuous reconciliation

Infrastructure as code describes what an environment should be; GitOps keeps it that way. Rather than relying on a pipeline to push each change and hoping nothing changes afterward, GitOps places agents in each environment that continuously compare the running system with its declared state and correct any difference.

The four GitOps principles

GitOps has a precise, vendor-neutral definition rather than being a loose style. OpenGitOps, a Cloud Native Computing Foundation (CNCF) Sandbox project overseen by the GitOps Working Group, publishes the GitOps Principles (version 1.0.0), which name four properties. The term itself was coined at Weaveworks, the company that created the Flux project.

The principles do not mandate Git. They require a store that is versioned, immutable and keeps a complete history; Git is the most common choice, which is where the name comes from, but the definition is deliberately tool-agnostic. Together the four principles shape how repositories are laid out and how promotion and rollback work.

How reconciliation works

Reconciliation is the mechanism that makes GitOps more than version-controlled deployment scripts. The desired state lives in a repository as declarative manifests that are versioned and reviewed. A reconciliation controller running inside the environment, with Argo CD and Flux as widely used examples, pulls that state on a loop, compares it with what is running and applies the difference until the two converge. When someone changes the environment out of band, directly against a cluster or through a cloud console, the controller detects the divergence and reverts it, so drift cannot accumulate. Sync status and divergence are reported to teams and dashboards, which makes the health of every environment visible at a glance.

Repository layout supports the loop. Application source code and deployment configuration usually live in separate repositories, so a configuration change does not trigger an application build and access to each can be controlled separately. Promotion between environments is a pull request that changes the configuration for the next environment, and rollback is a revert of that commit. Secrets are referenced rather than stored: the repository holds encrypted values or references to an external secrets manager, never secrets in clear text.

Pull and push deployment

Deployment can push or pull, and GitOps is the pull model. In a push model, a pipeline holds credentials for each environment and pushes changes in from outside. The pipeline must be able to reach every target, standing credentials for every environment accumulate in one place, and drift is corrected only when the pipeline next runs. In a pull model, a controller inside the environment pulls the desired state and reconciles continuously, so no external system needs standing access to the cluster and drift is corrected between deployments as well as during them.

Pull is not always available or appropriate. Some targets, such as managed services configured through a provider's API or legacy platforms that cannot host an agent, are easier to drive from a pipeline, and many estates use both models. Where it fits, the pull model removes a class of credential exposure and keeps environments converged continuously rather than correct only at the moment of deployment.

Platform engineering and golden paths

Infrastructure as code and GitOps make environments repeatable; platform engineering makes them available. Without a platform, every delivery team must learn the same tools, write the same modules and solve the same problems, or wait for a central team to do it for them. A platform packages that shared work once and offers it as a product.

The internal platform as a product

The CNCF Platforms White Paper defines a platform as an integrated collection of capabilities defined and presented according to the needs of the platform's users. Platform engineering is the practice of planning, building and running such platforms for the teams that build products. In practice an internal platform gathers the capabilities that teams would otherwise each build or request: provisioning templates, environments on demand, pipelines and deployment, secrets and configuration, an observability baseline, policy and guardrails, a service catalog and cost visibility.

The point is not to centralize these capabilities behind a queue but to offer them as self-service, through a portal, an application programming interface (API) or a command-line tool, so a team takes what it needs without waiting. Team Topologies, by Matthew Skelton and Manuel Pais, describes the platform team as one that provides a compelling internal product to accelerate delivery by stream-aligned teams, and it recommends the thinnest viable platform: the smallest platform that removes real obstacles, grown from what teams actually need rather than from what the platform team can imagine. For some organizations the thinnest viable platform is a page of documentation and a handful of templates over a cloud provider's managed services, and that is a legitimate place to start.

From ticket queues to self-service

The contrast between ticket-driven operations and a self-service platform is the case for platform engineering. In ticket-driven operations, teams file a request and wait, each environment is built by hand so no two are alike, the central team becomes a bottleneck and a single point of knowledge, and change is slow enough that shadow workarounds grow around the queue. A self-service platform lets teams provision and change infrastructure through paved paths, templates produce consistent environments on demand, and guardrails enforce policy without a human gate on every change, so the platform team spends its time building capability rather than closing tickets.

Self-service does not mean uncontrolled. What changes is where control is exercised: in the paths, templates and policies that every change passes through, rather than in a person reviewing each request. The paved path also stays optional, with escape hatches for teams whose genuine needs it does not yet meet, provided those teams meet the same guardrails by other means.

What a golden path provides

Spotify, which popularized the term in platform engineering, defines a golden path as the opinionated and supported path to build something, such as a backend service, a website or a data pipeline; others call the same idea a paved road. Its defining property is that teams choose it because it is the easiest route, not because it is mandated. What a golden path provides is concrete:

• A new service or environment created from a template, ready to run.
• Pipelines, deployment and rollback wired in from the first commit.
• Observability, logging and alerting present by default.
• Secrets and configuration drawn from managed stores, not baked into images.
• Policy and security guardrails applied automatically.
• An owner, a catalog entry and cost attribution from the first day.
• Documentation and sensible defaults, with escape hatches when a team needs to leave the path.

The CNCF Platforms White Paper lists the attributes that make such paths succeed: the platform is run as a product for its users, offers a consistent user experience, is self-service, reduces the cognitive load on product teams, is optional and composable rather than an impediment, is secure by default, and comes with documentation and onboarding. Camille Fournier and Ian Nowland's Platform Engineering develops the product approach behind these capabilities from the perspective of the leaders who fund, staff and run platforms.

Guardrails, policy and cost

Guardrails let teams move quickly without moving dangerously. Each guardrail prevents a specific failure and is enforced at a specific point, and expressing guardrails as code means that they are reviewed, versioned and tested like everything else.

Landing zones and policy as code

A landing zone is a baseline account or project structure with networking, identity, logging and guardrail policies in place before any workload arrives, so every environment starts from a governed foundation rather than an empty account. The major cloud providers each publish landing-zone guidance, and mature platforms vend new accounts or projects through the platform itself, already configured.

Policy as code expresses rules such as no public storage buckets, encryption at rest, approved regions only and images only from the trusted registry as code that is evaluated automatically. The checks run twice: at plan time, before a change is applied, so the author gets fast feedback in the pull request; and at admission, inside the cluster or the cloud control plane, so that nothing bypasses the rule. Open Policy Agent (OPA) is one widely used policy engine. Pipelines themselves run under least-privilege identities, and the supply chain behind infrastructure, from pinned modules to signed artifacts, should follow the practices of the NIST Secure Software Development Framework (SP 800-218).

Ownership, cost and audit evidence

Every resource should carry tags for its owner, environment and cost center, and plan and admission checks should reject resources that lack them, so that nothing runs without a traceable owner. Those tags make cost visible: spending is attributed to teams and services and reviewed regularly, with budgets and alerts catching overruns before the invoice does. The FinOps Foundation describes this shared practice as FinOps, an operational framework and cultural practice that creates financial accountability through collaboration between engineering, finance and business teams, rather than leaving cloud cost to a central budget that no engineer sees.

A further benefit arrives without extra effort. Because every infrastructure change is a reviewed commit applied by automation, the history of the repositories and pipelines is audit evidence: who changed what, when and under which review. Auditors can be given a query rather than a binder of screenshots.

Scale, operating model and maturity

What good looks like depends on size. This paper uses three size bands as a convention rather than as fixed categories. A small organization has one or two teams, a handful of deployable units and one production environment, with no dedicated platform function. A medium organization has several teams and tens of services, shared environments, and a platform or enablement team beginning to form. A large organization has many teams, hundreds of services, multiple platforms or regions, a dedicated platform organization, and formal change and audit obligations.

What changes with scale

The table reads left to right as a direction of travel, not as a ranking. A small organization should not import the machinery of a large one: a governed module catalog and an enforced GitOps estate would cost more than they return. Equally, a large organization that still relies on manual review and hand-built environments carries risk that grows with every team it adds. Different systems within one organization often sit in different bands, and the right moment to adopt the next column's practice is when the current one starts to strain.

Roles around the platform

An operating model names who owns what. On the platform side, a platform product owner sets the roadmap and runs the platform as a product with internal customers, and platform engineers build and run the paved paths and shared services. The platform is staffed as a long-lived team, not a time-boxed project, because a product needs continued investment and a project ends. Around it, stream-aligned teams build products on the golden paths, and an enabling team coaches adoption and closes capability gaps rather than doing the work for others.

Team Topologies names four team types (stream-aligned, enabling, complicated-subsystem and platform) and three interaction modes: collaboration for a defined period to discover something new, X-as-a-Service in which one team provides and another consumes, and facilitating in which one team helps and mentors another. A platform team that falls into permanent collaboration with every team, or insists on approving each change, has become a new gatekeeper. The measures of a platform are best read as signals rather than targets to game: teams onboarded, time to a team's first deployment, latency from request to fulfillment, tickets avoided, and the satisfaction of the developers who use it.

Pitfalls to avoid

Each pitfall below is the easy path under pressure, which is why naming them is the first defense.

If a platform is easier to use than to bypass, teams adopt it by choice; if it is harder, they route around it.

A maturity path

A maturity path gives teams a shared sense of where they stand and what comes next. It runs from manual change at the base, through codified and modular infrastructure and continuous reconciliation, to an optimizing organization that offers golden paths as self-service.

No stage can be skipped, because each supplies what the next depends on: there is no useful reconciliation without codified, modular infrastructure beneath it, and no golden path worth offering without reconciled environments to deliver it. Maturity should be assessed per team and per system rather than for the organization as a whole, since different teams will sit at different stages and the next step differs for each.

Where to start: the first 90 days

The first 90 days should produce working evidence rather than a strategy document. Choose one system and one painful, repeated request, and prove the approach end to end before widening it.

1. Days 1 to 30: codify and protect. Put all new infrastructure under code, establish remote, locked and encrypted state, and stop accepting new console changes to the target system.
2. Days 1 to 30: choose the first golden path. Pick one painful, repeated request, such as a new service or a test environment, and agree with the teams who make it what good would look like.
3. Days 31 to 60: build the path end to end. Let a team create a previewed, observable environment from a template, with pipeline, secrets and ownership wired in.
4. Days 31 to 60: reconcile one system. Run GitOps reconciliation for one system, promote between environments by pull request, and rehearse a rollback by revert.
5. Days 61 to 90: add guardrails and review adoption. Add policy as code and mandatory cost tags, run a real environment from the path, and review adoption and friction with the teams it serves.

After 90 days the organization should have one golden path in real use, one reconciled system, protected state and the first guardrails, together with evidence about what teams found easy and hard. That evidence, not a target architecture, should decide which path to build next. Make the paved path the easiest path, and teams will build on it by choice.

Glossary

Infrastructure as code (IaC)

The practice of defining infrastructure in machine-readable files that are versioned, reviewed and applied by tools rather than by hand.

Desired state

The declared description of what a system should be, from which a tool computes and applies the changes needed.

Idempotent apply

Applying the same definition repeatedly converges on the same state without additional side effects.

Drift

Divergence between a running system and its declared definition, usually caused by manual change.

Immutable infrastructure

An approach in which servers, images and containers are replaced with new versions rather than modified in place.

State file

A record that some declarative tools keep to map definitions to the real resources they manage.

Ephemeral environment

An environment created on demand from code for a specific purpose, such as a pull request, and destroyed after use.

Promotion

Moving the same built artifact through successive environments toward production, varying only configuration.

GitOps

An operating model in which the desired state is declarative, versioned and immutable, pulled automatically by software agents and continuously reconciled.

Reconciliation

The continuous loop in which an agent compares actual with desired state and applies the difference.

Platform engineering

The practice of planning, building and running internal platforms that offer shared capabilities to product teams as self-service.

Internal developer platform

The integrated set of capabilities, templates and APIs that product teams use to build, deploy and run software.

Internal developer portal

A user interface onto a platform, typically a service catalog with templates, documentation and scorecards.

Golden path

The opinionated and supported way to build and run something on a platform, chosen because it is the easiest route; also called a paved road.

Thinnest viable platform

The smallest platform that removes real obstacles for its users, grown from actual demand.

Landing zone

A baseline account or project structure with networking, identity, logging and guardrails in place before workloads arrive.

Policy as code

Rules expressed as code and evaluated automatically, for example at plan time and at admission.

FinOps

An operational framework and cultural practice that creates financial accountability for technology spending through collaboration between engineering, finance and business teams.