How-to guides
The day-2 procedures your team runs without us. Every one is written as steps against your own repositories, with the verification and the way back included.
Why these exist
A how-to guide is a procedure a customer runs on their own platform, written so that the second engineer can run it as safely as the first. They exist because a system only one person can change is not production-ready, however good that person is.
Each guide below has a one-line description and a link into the documentation. Concept pages are public; procedure pages open with the entitlement for the product they belong to. The knowledge base explains how access works.
What every guide contains
What must already be true, and which stage you are in. A guide that starts in production says so in its first line.
The group that holds the permission. If the procedure needs a second approver, the guide names when that approval is required.
What else the change touches. A shared unit definition is instantiated by several accounts, and the guide says so before you edit it.
Commands and pull requests, pulled from the real repositories and pinned by content hash, so a sample never drifts from the code.
How to know it worked, in the same terms the pipeline reports: an empty plan, a green run, a synced application, a resolved finding.
How to get back. For a release that is the previous tag; for infrastructure it is usually reverting the pin or the pull request.
Change and release
Getting a change from a branch into production, and back out again.
Deploy a change to dev
Open a pull request, read the plan posted on it, merge, and let the pipeline deploy to dev.
Promote a release to staging and production
Promote the same immutable image forward through the stages; nothing is rebuilt on the way.
Roll back a release
Restore service by promoting the previous release tag, then investigate the failing one.
Review an infrastructure pull request
What to look for in a plan before approving it, and which changes need a second code owner.
Roll back the data pipeline image
Point the trigger function back at the previous image tag when a transform goes wrong.
Secrets
Secrets live encrypted in Git and reach workloads through the key policy, not through people.
Rotate a secret
The seven-step rotation, from editing the encrypted file to confirming the workload picked up the new value.
Add an application secret
Create the encrypted entry, wire the workload to it, and have the operator deliver it.
Review a secrets pull request
What a reviewer checks, and why a production secret needs a second approval and an environment reviewer.
Run an emergency manual sync
Push the encrypted values to the parameter store by hand when the workflow cannot, with the audit trail intact.
Rotate a database password
Rotate a generated credential that the module owns and that never appears in state.
Growing the platform
The foundation is built to be extended by its owners, not rebuilt by us.
Add an account
A map entry and a folder. Two pull requests, and the guardrails, identity and network follow.
Add a region
A folder whose name is the region. Address management, the region policy and the tag policy discover it.
Add a stage
Place the new stage in exactly one isolation domain, then wire it into the pipelines and environments.
Scale a stage
Change the sizing values for one stage: nodes, replicas, data store instances and autoscaling ceilings.
Create a new application repository
Stand up the infrastructure and code repositories for a new application on the existing foundation.
Plan capacity
What the address plan, the account structure and the sizing defaults allow before anything has to change.
People and access
Access changes are pull requests, so the access review is a diff rather than a spreadsheet.
Run the access review
Walk the groups, the permission sets and the unused-access findings, and remove what nobody used.
Onboard a new team
Create the groups, assign the permission sets, and give the team its own stage-scoped access.
Customize single sign-on
Change which groups map to which permission sets, and which accounts each one reaches.
Connect over the VPN
Get an engineer onto private resources through the federated VPN, with per-group authorization.
Onboard a developer to secrets
Give a developer the ability to read the stages they own, and no ability to read production.
Operations
The recurring work: what to check, what to fix, and what to do when something breaks.
Daily operations
The short list an operator walks each day: drift issues, findings, alarms, failed runs.
Resolve drift
Read the drift issue, decide whether the code or the environment is right, and close the gap in code.
Respond to an incident
The incident procedure: roles, communication, the change you are allowed to make, and the write-up.
Rotate a certificate
Replace a certificate before it expires, including the ones that are not renewed automatically.
Patch and upgrade
Apply provider, module and platform upgrades in order, lower stages first, with a plan in between.
Pull upstream updates
Compare your fork with upstream, branch, plan, review and merge the improvements you want.
Compliance, cost and integrations
The switches you will reach for once the platform is running.
Enable a compliance pack
Turn on the conformance pack for a framework and see what it finds, one flag at a time.
Collect audit evidence
Produce the evidence an auditor asks for from the sources the platform already maintains.
Review the cost toggles
Every paid feature switch, with its price beside it, so a decision is made with the number in view.
Configure notifications
Route findings, alarms and pipeline results to the inboxes and channels your team actually reads.
Send alerts to your chat tool
Attach your own messaging workspace to the notification topic the platform publishes to.
Attach your own monitoring or paging tool
The documented attachment points, so third-party tools read the platform rather than replace it.
One guide in full: promoting a release to production
Build once, promote the same artifact, and make the last step into production deliberate.
-
Merge to the main branch
The pipeline builds one immutable image, scans it, and deploys it to dev automatically. This is the only build; every later stage promotes this same artifact.
-
Verify in dev
Confirm the application is healthy in dev using its health endpoints and logs before promoting anything.
-
Cut a release
Creating a release promotes the image that is already in dev to staging. Nothing is rebuilt, so what you verified is what moves.
-
Verify in staging
Staging is sized for high availability like production, so this is the stage where a production-shaped problem appears.
-
Open the production deploy pull request
The production deploy is a pull request against the GitOps repository, raised by the pipeline rather than by a person with a token.
-
Get the approvals
A code owner reviews the pull request, and the production environment holds the apply until its named reviewers approve. Both are required.
-
Merge and sync
A person merges, then syncs the application manually. Production does not sync itself: the last step into production is deliberate.
-
Watch, and know the way back
Watch the health probes and the sync status. If the release is bad, promote the previous release tag; the artifact is still there.
Two things make this safe rather than ceremonial. Nothing is rebuilt between stages, so the artifact you approved is the artifact that runs. And the way back is a promotion of the previous tag, not a rebuild under pressure. The full procedure, with the commands, is in the documentation.
Related
- Troubleshooting covers what to do when a procedure does not behave as documented.
- Environments and promotion explains the model these procedures implement.
- GitOps explains why the pipeline is the only writer.
- BuiltForProd Managed is the option when you would rather someone else ran them.
Questions about the procedures
Who runs these procedures, us or BuiltForProd?
You do. The platform is handed over so that your team can run every day-2 procedure without us, and the handover session ends only after your engineers have performed the core ones unaided. BuiltForProd Managed exists for the work you choose not to do yourself, not for the work you cannot.
How do you promote a change to production?
One image is built when the change merges, and that same immutable artifact is promoted forward: automatically to dev, by cutting a release to staging, and into production through a deploy pull request that needs a code owner and the production environment reviewers. The final sync into production is performed by a person on purpose.
How do I roll back?
Promote the previous release tag. Because every stage runs an immutable image rather than a rebuild, the previous artifact still exists and restoring it is a promotion rather than a repair. For infrastructure, reverting the version pin or the pull request is the equivalent move.
How hard is it to add an account or a region later?
Adding an account is a map entry and a folder, which is two pull requests; adding a region is a folder whose name is the region, after which the address manager, the region-restriction policy and the tag policy discover it themselves. The AWS Enterprise Baseline address plan reserves capacity for 16 regions and 8 workload stages per region, so growth does not mean renumbering.
Can we change the procedures?
Yes. The guides describe your repositories, and you own them, so a procedure that does not fit your team is a pull request against the code and the documentation. Keep the change legible for the next engineer, which is the only rule the platform actually enforces about your own process.
Want your team running these on day one?
Handover is a working session: your engineers perform the real procedures unaided before the engagement closes. Ask us what that looks like for your team.