Infrastructure as Code

03

The platform described, not click-configured

Infrastructure-as-code means the entire platform — databases, networking, functions, security policies, monitoring, cron jobs — has one canonical, versioned, human-readable description. The cloud becomes a compiler for a declaration, and reality is meant to match the file. That sounds like an engineering preference; it is actually an organizational safety property.

• Reproducibility from nothing — a fresh environment springs from the same files that built production, so 'can I recreate it?' has a yes measured in hours, not a shrug.
• Change is reviewed like code — a change to the platform is a pull request with a diff, a review and a decision record, not an anonymous six-hour console session.
• Truth lives in one place — the file is the source of truth, and the console is a view of it, not a second, drifting reality that wins whenever it disagrees.
• Onboarding stops being archaeology — a new engineer reads the platform description instead of interrogating whoever clicked things into being, or worse, the production console itself.
• Auditability is natural — the git history is the full biography of the platform: who changed what, when, and what they reviewed, on the infrastructure that carries customer money.
• Whole environments are disposable — because they are described, not curated, an environment can be destroyed and rebuilt cleanly, which is a superpower on a platform that must drift-check and rehearse.

The console is where the platform lives; the code is where the platform is born. We make sure the birth certificate exists before anyone trusts the construction.

04

Why clicks defeat knowledge

Click-configured infrastructure has a specific failure mode: each click adds configuration that lives nowhere, answered to no one, and is forgotten by everyone but the person who clicked. The platform becomes a snowflake — unique, unrepeatable, and terrifying to touch. The problem is not that clicks are easy; it is that knowledge evaporates exactly as fast as the clicking finger forgets.

• Snowflake servers defeat change — configuration that exists only inside a running instance means the only honest test of 'will a change work?' is doing it live on the one and only instance.
• The blameless list of shame — 'who created this in the console?' is a question with a human answer that no one writes down; every such answer is eventually proved wrong by the next operator.
• Recovery is improvology — a snowflake that dies cannot be restored from a file; it is rebuilt by a human remembering their own clicks, which is a plan only until that human leaves.
• Scale multiplies the doom — ten servers clicked differently are ten different platforms wearing one nametag, each with its own private bugs and undocumented behaviour.
• Compliance cannot inspect the invisible — an auditor asks 'what is the platform?' and the honest answer is a shrug; the audit becomes an investigation, and confidence is the casualty.
• The cost is paid at the worst moment — the snowflake is always discovered at 2am during the incident, when the person who clicked it is asleep in another timezone.

We have inherited enough click-built platforms to know the pattern by smell. IaC exists so the platform's knowledge survives the people who happened to build it.

05

Declarative configuration: the desired state as the contract

The heart of IaC is the declaration: you express what you want to exist, and the tooling makes reality converge on it. You do not tell the machine 'create a database, then a table, then five indexes'; you describe the database, the table and the indexes, and the machine reconciles reality toward that description — creating what is missing, changing what differs, and leaving alone what already matches.

• Desired state beats imperative steps — a declaration is idempotent by nature; running it twice reaches the same end, where a script of steps run twice may create twice.
• Reconciliation is the mechanism — the tooling diffs current reality against the declaration and applies only the gap, so a partial deployment is repaired by the next run, not by a human.
• The declaration is machine-readable and human-readable — it is data a parser can act on and a reviewer can read, which is the whole point of review-as-code.
• Ordering is the tooling's problem — dependencies between resources (the table that sits in the database) are resolved from the declaration, not by a fragile script sequence.
• Rollback is a different declaration — if the new state is wrong, the previous state is the recovery plan, and it is a file, not a memory.
• On the payment platform the schema is declarative too — the ledger, RLS policies and SECURITY-DEFINER procedures are declared in versioned SQL, and the drift-check treats them like any other declared resource.

Declarative infrastructure turns the platform into a compiler target instead of a museum of hand-laid bricks. The declaration is the contract; the cloud is required to keep it.

06

Reproducibility: dev matching prod is not indulgence

Reproducibility means a developer's environment, a staging environment and production are built from the same descriptions, differing only in scale and credentials. This is not creature comfort; it is the difference between a bug that reproduces in a sandbox and a bug that only ever exists in production.

• Same code, same description, same behaviour — when dev and prod are built from the same files, 'works on my machine' is a statement the pipeline can actually audit.
• Scale is the honest variable — the topology matches; only the size of the compute, the data and the traffic differs, and those differences are named and understood rather than accidental.
• Disposable previews enable parallel work — an engineer can spin up a full environment per branch from the declaration, test, destroy, and never pollute the shared sandbox.
• The money system rehearses at full shape — the payment platform's staging runs the same functions, cron jobs, callback paths and procedures as production, pointed at test rails, so a release rehearses in a real arena.
• Reproducibility is the emergency exit — when production is broken, 'rebuild it from scratch in a sterile environment and test the recovery' is possible, which is the highest-value drill a platform can run.
• Reproducibility exposes the undocumented — anything the platform needs that is not in the declaration (a manual console tweak, a secret pasted by hand) is exposed the moment you reproduce it, and exposed is fixable.

A platform that cannot be reproduced is a platform that can only be hoped about. We build the ability to build it again into the platform itself.

07

The two-infra-engineers align discipline

Configuration as code brings with it a quiet law: two engineers who apply the same declaration to two valid states will keep them aligned — not because they are disciplined, but because the files do the disciplining. We call this the 'two engineers align' effect, and it is the social contract underneath IaC.

• The file is the referee — when a change goes through a pull request, the review makes sure both engineers' mental models match the file before anything is applied.
• Plan-then-apply separates thought from consequence — the tooling shows what a change will do (the plan) before any of it happens, and a human reads that plan, so applied changes are explicit choices.
• The review gate is where alignment happens — two engineers looking at one diff disagree loudly in review and agree silently in production, which is the correct order.
• The platform enforces the alignment — drift detection puts an actual automated guard on top of the human review, so 'we aligned once' becomes 'we stay aligned always'.
• On a money platform the schema is the referee too — the ledger file, the policy file and the function bodies are reviewed together so a change to the database and a change to the app cannot disagree.
• Alignment is the cheapest insurance — a five-minute plan read prevents a five-hour incident, and repeated a thousand times it is the entire business case for IaC.

IaC makes alignment a property of the system rather than a property of the mood. The discipline is not in the tool; it is in the two engineers — and the tool makes their alignment sticky.

08

Drift detection: when reality and code disagree

Infrastructure drifts. Someone clicks a firewall rule, a cron runs a one-off change, a failover modifies a resource, a console edit 'fixes' something temporary and stays forever. Drift is the slow divorce between the declaration and reality, and its first victim is trust: if the file lies, no one believes the file. Drift detection is how we keep the marriage honest.

• Drift checking is scheduled, not hoped — a recurring job compares the declared state to actual state and reports what no longer matches, before the mismatch becomes an incident.
• The payment ledger gets the same treatment — the schema, policies and procedure bodies are diffed against the declared SQL so an unauthorized or forgotten database change is visible immediately.
• Drift is triaged like a bug — every finding is either reconciled (reapply the declaration) or acknowledged (a legitimate operational change, documented and added back to the file).
• Reconciliation heals silently when safe — tooling re-applies the declared state for changes that are safe to correct automatically, and raises a flag when a human decision is needed.
• Unreconciled drift pages a human — a platform that quietly drifts and is never repaired is a platform being slowly edited by a ghost; detection with no follow-through is just a scary dashboard.
• Drift history is evidence — knowing what drifted, when, and whether it was ever reconciled gives an incident investigator the honest timeline that click-built platforms can never produce.

The fork between the file and reality will happen; the only question is whether it is discovered in a minute by a robot or at 3am by a customer. We choose the robot.

09

Secrets in the right place: declarative the platform, inject the secrets

IaC would be a catastrophe if it meant putting secrets in the code, and people do exactly that. The correct split is total: the code declares the shape of the platform, and the secrets arrive separately, at runtime, from a managed store — never in the files, never in the git history, never in the plan output.

• The declaration has no secrets — the IaC references a secret manager path, not the secret itself, so a repository leak exposes shapes, not credentials.
• The plan output redacts secrets — a plan that would print a password in CI logs is a plan that has already failed; redaction is enforced, not requested.
• On the money platform the gateway keys are the crown jewels — Daraja consumer keys, Stripe and PayPal secrets, signing secrets and callback HMACs live in a managed store with rotation and audit, never in the schema files, never in the repository.
• Rotation is a supported operation — because secrets are injected, rotating a key means updating the store and restarting consumers, not rewriting the repository and praying.
• Per-environment secrets are distinct — staging cannot authenticate as production; a leaked test key cannot move real money, and the identical topology cannot be trusted across key sets.
• Secret access is audited — who read which secret and when is logged, because the first question of a breach investigation is always 'what credentials were exposed?'.

IaC resolves the what, and the secret manager resolves the who-can-use-it. Keeping those two worlds separate is the boundary that keeps a repository leak from becoming a money leak.

10

Security by default in templates: the baseline is not optional

IaC's quiet gift to security is that defaults travel with the code. If every template is locked down, every environment is locked down — not because each person remembered, but because the default was safe and the exception had to be argued for in review. Security stops being a memory and becomes a property of the template.

• Private by default, opened by exception — the template starts sealed; every port, policy and public exposure is an explicit, reviewable line in a diff, not an unremarked default.
• Isolated by default — networks, database access and service-to-service trust are segmented in the declaration, so a compromise in one corner does not spread cross-platform by flat network.
• Encryption is declared, not remembered — storage and traffic encryption are properties of the resources in the templates, so a new database is born encrypted and no memory is required.
• Least-privilege roles are generated from templates — service identities get exactly the scopes their role needs from the same description that builds the platform, so their permissions are reproducibly safe.
• The money path templates are the strictest — the endpoints that touch the gateway, move wallets or handle callbacks declare the narrowest possible surface, and comprehensive security defaults are the template's baseline, not its ceiling.
• Security review happens in the diff — a malicious or careless change to security posture appears as a visible line in a code review rather than a silent console click nobody noticed.

The template is the contract every environment inherits. We make the contract say 'secure' in its first line, so nobody has to repeat it after it.

11

Rollback returns you to a known good state

When a change breaks the platform, the fastest rescue is returning to the state that worked. Click-built platforms make that archaeology; IaC makes it a revert. But a revert is only as good as the last known-good state, so the discipline of knowing good states is part of the system.

• Every environment has a known-good definition — the last committed, tested state of the declaration is a standing artifact, so 'good' is a specific, findable state, not a feeling.
• Rollback is a version of the file — reverting infrastructure is checking out the previous declaration and reapplying it; the platform converges back to it, and the tooling does not need to invent anything.
• The database gets the same honesty — the schema's forward migrations carry reverse paths, and the declaration's history records which code version matched which schema version, so a revert keeps the pair coherent.
• Rollback rehearsals are scheduled — on the payment platform, rolling back staging to a known-good state is a drill, not a theory, so the real emergency is the hundredth repetition, not the first.
• A revert does not destroy the evidence — the broken release remains in history, tagged and discussable, so the incident review has the exact change that caused it.
• Known-good is verified, not assumed — the state that the drills rebuild is the one the smoke tests pass against; 'good' means proven by the machine, not remembered by a human.

Recovery is a commodity when the known-good state is a file. We keep the exits open by keeping the good states real.

12

Destroy-and-rebuild testing: proving environments can be recreated

There is one test that proves reproducibility beyond argument: destroy an environment, then rebuild it from the declaration alone and watch whether anything breaks. We run that test deliberately, because 'should be reproducible' and 'is reproducible' are different claims separated by evidence.

• Full-stack destroy-and-rebuild on demand — the whole non-production platform is destroyed and rebuilt from the files, exposing everything the declaration forgot.
• The rebuild is the documentation test — if a new engineer cannot bring up a working environment from the files and the README, the platform is failing its own hiring process.
• The payment platform proves its own renewal — rebuilding the staged platform from the declaration—functions, ledger schema, policies, crons—proves that the money system is not a hand-built artifact.
• Unreproducible steps surface as blisters — a manual console tweak that was never added to the files becomes obvious when the rebuilt environment misbehaves exactly where the data or the policy is missing.
• The test is safe because environments are disposable — the value of IaC is that the destruction is routine; a platform too precious to rebuild is a platform too unmanaged to trust.
• Rebuild time is a metric that matters — a platform that rebuilds in four hours is dramatically easier to rescue and rehearse than one that takes four weeks of archaeology.

Nothing proves a recovery path like actually walking it. We destroy and rebuild, in public, on purpose, until the resurrection is boring.

13

Modules, composition and the platform as a portfolio

IaC at one scale is one file; at real scale it is a portfolio of modules — databases, application services, edge functions, networking, observability, policy — composed into environments. Composition is where IaC either stays coherent or collapses into a maze of copy-paste, and we treat it as its own discipline.

• Reusable modules with owned interfaces — the database module, the function module, the monitoring module are built once, reused everywhere, and improved in one place.
• Versioned module releases — a module is promoted like software: a specific version is consumed by an environment, and an upgrade is a reviewable change, not a silent refresh of everything.
• Naming and tagging as identity — resources carry consistent names and ownership tags from the declarations, which is how cost, responsibility and blast radius become queryable.
• Environment composition is thin — environments differ only in their small composition file (scale, region, credentials), so dev, staging and production stay aligned by construction.
• The money platform's modules are its money surfaces — wallet schema, ledger procedures, callback functions and their policies are composed as reviewed modules, so the discipline scales with the platform.
• Composition reviews are the real system design — the interesting decisions (what talks to what, where the boundary is) happen at the composition layer, which is exactly where review attention goes.

A platform is a portfolio of described parts with a wiring diagram. We keep both the parts and the wiring in files, reviewable and coherent.

14

The IaC we run for KodiiPay: declaring a ledger

The most opinionated infrastructure-as-code we operate is our own payment platform's schema and security model. Declaring a ledger in files is not a convenience; it is the difference between 'the books came from a ceremony' and 'the books came from a reviewed file'.

• The schema is one declarative source of truth — tables, constraints, enums, indexes, row-level security policies and the SECURITY-DEFINER procedures that move money are declared in versioned SQL, applied from the pipeline, never hand-diffed in a console.
• RLS policies are declared like infrastructure — who can read, write and own which rows is a reviewed, versioned policy file; a change to the policy is a pull request, not a privileges window.
• Cron jobs are declared in the platform — the money sweeps, expiry jobs, reconciliation runs and hold-releases are time-scheduled processes declared alongside the schema, each advisory-locked and idempotent, so the platform's automatic operations are reproducible too.
• The payment functions are defined, not remembered — the gateway-facing edge functions and their environment (secrets, timeouts, verifications) are declared, so the code that touches Daraja, Stripe or a bank-transfer corridor has an ancestry in the repo.
• Drift on the ledger is watched like fire — a drift-check compares the live schema and policies against the declaration, because an undocumented schema change on a ledger is a future reconciliation nightmare with a timestamp.
• The platform proves its own reproducibility — the whole declared stack can be rebuilt into a staging replica, which is how the money system rehearses a migration or a recovery without touching real customer funds.

Our ledger is not assembled; it is declared, reviewed and drifted-checked. That is what infrastructure-as-code means when the infrastructure is money.

15

The honest limits: when a script is the right answer

We are honest about IaC's opposite: some infrastructure does not need the full declarative machinery. A prototype, a static site, a single-purpose function or a short-lived experiment can be a well-written script, and calling that a failure is cargo-cult discipline. The judgement is about persistence, stakes and shared ownership.

• Ephemeral things justify scripting — a one-off analysis database or a deploy helper that runs once and dies does not need a module, a version and a review ceremony.
• Stakes decide the investment — the rule of thumb is direct: if breaking it costs money, reputation or customer trust, it earns the full discipline; if breaking it costs a coffee, a script is correct.
• Every script is still honest infrastructure — even the smallest automation keeps its secrets in the manager, runs from the repository, and has a README that explains its one job.
• The border moves as the thing lives longer — the moment the 'temporary' script becomes the platform's daily operation, it migrates into the declared platform, because persistence now deserves the discipline.
• Scripts die quietly; declarations are reviewed — an unattended cron of undocumented shell is the classic silent drift; we keep even the small things somewhere a human can see them.
• Small things are graded on whether they lie — the sin is not using a script; it is a script that lies about the state of the platform. A truth-telling script for a small job is engineering; a document lying about being IaC is not.

We will name the grading honestly: this deserves the full platform, or this deserves a clean script. The machine should fit the mission, and we will tell you which mission you have.

16

Cost, ownership and the economics of declared infrastructure

Infrastructure is a bill as well as a topology, and IaC makes cost an engineering feature rather than a finance-time surprise. When the platform is declared, cost is attributable, right-sized and reviewable — and unused things can be destroyed because they can always be recreated.

• Tags and ownership make cost attributable — every resource carries its team and purpose from the templates, so the monthly bill is a report, not a guessing game.
• Right-sizing is a reviewable change — a database instance size or a function concurrency limit is a line in a diff, so scaling up or down is a decision with a record and a reviewer.
• Disposability is the cheapest insurance — because environments are declared, staging can be destroyed on the weekend and rebuilt on Monday, paying only for what day actually needed.
• Budget alerts are declared with the platform — cost thresholds are part of the platform's wiring, not a spreadsheet a finance person updates in November.
• The money platform watches its own unit economics — the cost of running a transaction (compute, database, gateway, function) becomes a tracked, declared thing, because it flows straight into how the platform prices itself.
• Ownership is explicit — every resource names an owner in its declaration, so the eternal question 'who pays for this?' and 'who fixes this when it breaks?' share one answer.

Infrastructure must earn its bill, and declared infrastructure can prove it. We make cost a first-class, reviewable property of the platform.

17

How we run infrastructure engagements

We do not deliver a diagram and disappear. We audit the platform as it exists, import what deserves to survive, declare the rest, and hand over a platform the client's engineers can rebuild from files with confidence — then we stay until the first few honest failures become routine.

• Audit the existing platform — we map the click-built reality, the undocumented services, the console-only tweaks and the secrets that may already be in the wrong places.
• Import the platform into declarations — the surviving resources are captured into modules and files with names, tags and ownership, closing the gap between reality and code.
• Establish the review gate — the declaration enters the same review-and-plan discipline as application code, so future change to the platform travels through review.
• Move secrets into the managed store — credentials, gateway keys and signing secrets leave the code and the consoles and enter the manager with rotation and audit.
• Add the machine guards — drift detection, plan-before-apply and destroy-and-rebuild drills prove the declarations match and can restore reality.
• Wire cost and ownership — budgets, tags and owner records turn the bill into a report and the platform into a portfolio with names.
• Train the engineers and hand over — the client's team plans, applies and rebuilds from the files under our eye until the discipline is theirs, then it is genuinely theirs.

The goal of every infrastructure engagement is the same: the client's next engineer can rebuild the platform from the repository and sleep. That is the deliverable, and it is delivered.

18

Honesty about infrastructure as code

IaC is a genuinely transformative discipline and an enthusiastically oversold one. Here is the honest version, from people who have both rescued click-built platforms and fought through IaC that was itself a snowflake.

• The file can lie too — IaC without drift detection and without a plan-read review culture is paperwork, not reality; the tool does not guarantee the truth, it guarantees the possibility of checking it.
• Sites and scale both break the ideal — a platform spread across many providers and regions can fragment into multiple declarations, each drifting independently; we engineer one truthful story or name the fragments honestly.
• The first import is archaeology — bringing an existing click-built platform into declarations is slower and more painful than starting fresh, and pretending otherwise is how imports corrupt the discipline.
• IaC amplifies confidence in the declaration, not reality — a beautifully modular platform that nobody drifted-checks is a set of confident lies; the guard is the machine, and the machine must run.
• Not everything can be declared — some vendors, some consoles and some legacy systems resist automation; pretending otherwise creates fiction, and fiction is worse than honest manual work with a runbook.
• The discipline outlives the tools — tools change, clouds merge and modules evolve, but the property that matters survives: the platform is described, reviewed, reproducible and guarded. That is what we sell.

Infrastructure as code is not software that writes itself; it is care that makes itself repeatable. We bring the care, the machinery and the honesty — and the platform you get survives being rebuilt, along with the humans who read it.

The toolchain

The Infrastructure-as-Code toolchain

The same classes of machinery that keep our payment platform — ledger, policies, functions and crons — declared, reproducible and guarded. Every tool exists because an unreproducible platform taught us it was needed.

Lifecycle

The Infrastructure-as-Code lifecycle — from archaeology to owned platform

Whether we are declaring a greenfield platform or rescuing a click-built snowflake, the work passes through the same twelve stages — the ones that keep our own payment platform reproducible.

Closing

More than development

Infrastructure-as-code is how a platform stops living in someone's head and starts living in the repository — reviewable, reproducible and survivable. The work we bring to clients includes:

Infrastructure-as-code is not about hating consoles; it is about refusing to let the knowledge of your platform live in one person's memory.

We declare, shelter, drift-check and prove the reproduction of a live money platform every day. When your infrastructure deserves that standard, it is the standard you get.