Cloud Landing Zone Decisions to Document First
Before migrating any workload, you need to document the core decisions that shape your cloud landing zone: the foundational account structure, networking topology, identity model, and governance guardrails. These decisions are expensive to change later, so writing them down early prevents rework and security gaps. This article explains which decisions to capture, why they matter, and how to document them in a way your team will actually use.
Why Document a Landing Zone at All
A landing zone is the set of cloud accounts, networking, identity, and policies that form the base for all workloads. Cloud providers offer landing zone accelerators, but those are starting points, not finished designs. Without written decisions, each team interprets the architecture differently, leading to inconsistent resource naming, overlapping network ranges, and security policies that drift apart. Documentation turns the landing zone from a one-time setup into a maintained contract that new workloads must follow.
Documentation also helps when things go wrong. If a network route breaks or an IAM policy blocks a deployment, the landing zone document is the first place to look. It answers questions like “Should this resource be in the shared services account?” and “Who approves a new VPC peering connection?” without interrupting the platform team.
Core Decisions to Capture
Not every detail needs to be written down, but these categories are the minimum for a useful landing zone document:
- Account structure: How many accounts, what they are named, and which workloads live where. For example, separate accounts for production, development, and shared services.
- Network topology: The IP address ranges for each VPC or virtual network, how they connect (peering, transit gateway, VPN), and where internet ingress and egress occur.
- Identity and access: The identity provider (e.g., Azure AD, AWS SSO), how human users and service accounts authenticate, and the baseline role hierarchy.
- Governance guardrails: Which policies are enforced (e.g., resource tagging, region restrictions, encryption requirements) and which are only recommended.
- Logging and monitoring: Where logs are aggregated, how long they are retained, and who has access to them.
- Cost management: Budgets, alerts, and who is responsible for reviewing spend.
For each decision, record the rationale and the date. A decision that made sense when the company had three employees may not fit a team of fifty, and the document should show when it was made and why.
How to Structure the Document
A single monolithic document becomes outdated quickly. Instead, structure the documentation as a set of linked pages or a wiki with a clear index. The index should list the decisions above, each with a status (proposed, accepted, deprecated) and an owner. This makes it easy to review changes and see what is still in flux.
Use a table for the most important decisions: decision, value, owner, date, and status. For example:
- Production account name:
prod— owner: platform team — 2024-01-15 — accepted - Default region:
us-east-1— owner: CTO — 2023-11-02 — accepted - Network range for shared services:
10.10.0.0/16— owner: network team — 2024-03-20 — proposed
Keep the document version-controlled, ideally in the same repository as the infrastructure-as-code that implements the landing zone. That way, a pull request that changes a network range also updates the documentation, and reviewers can see the impact.
Common Mistakes and How to Avoid Them
One frequent mistake is documenting only the happy path. If a decision has a known exception, write that down too. For example, “All resources must be tagged with cost-center, except for temporary resources created by CI/CD pipelines, which get tag auto-cleanup.” Without this, someone will eventually delete a pipeline resource that was supposed to be temporary.
Another mistake is confusing the landing zone document with the architecture diagram. Diagrams are useful, but they go stale quickly. The document should be text-first, with diagrams as supplements. When a diagram contradicts the text, the text wins.
A third mistake is not including the “why” behind a decision. If the document says “we use three accounts,” but not why, a future engineer might consolidate them to save money, not realizing the separation exists for compliance reasons. Write the rationale in one or two sentences per decision.
How to Choose What to Document First
Start with the decisions that are hardest to reverse. These are typically:
- Account structure and naming conventions
- Network IP ranges and connectivity
- Identity provider and federation
- Data residency and compliance boundaries
These choices affect every workload that follows. If you change an account name after workloads are deployed, you must update every script, pipeline, and IAM policy that references it. If you change a network range, you may have to re-IP entire environments. Document these first, even if other details are still being decided.
For each decision, ask: “If we get this wrong, how much work is it to fix?” If the answer is “days or weeks of rework,” document it now. If it is “a quick parameter change,” you can defer it.
Keeping the Documentation Alive
A landing zone document is only useful if it is current. Set a recurring review, such as quarterly, where the platform team goes through each decision and checks whether it still holds. Add a “last reviewed” date to each section so it is clear what is stale.
When a decision changes, do not just edit the document. Record the old value and the reason for the change in a changelog. This creates an audit trail and helps people understand why the landing zone looks the way it does. For example, “2024-05-01: Changed default region from us-east-1 to eu-west-1 because the data residency requirement applies to all new workloads.”
Finally, make the document easy to find. Link it from the onboarding guide, the infrastructure repository README, and any internal wiki. If people cannot find it, they will not use it, and the landing zone will drift.
Frequently Asked Questions
What is the difference between a landing zone and an account structure?
An account structure is just the list of cloud accounts. A landing zone includes that, plus the networking, identity, and policies that make the accounts usable. The landing zone is the full foundation; the account structure is one part of it.
Should we document decisions before or after building the landing zone?
Ideally, document as you go. Write down each decision when it is made, even if it is a draft. Trying to reconstruct decisions after the fact is error-prone because people forget the rationale. If you already have a landing zone, start by documenting the current state and mark any decisions that are uncertain.
How much detail is too much?
If a decision does not affect how workloads are deployed or operated, it may not need to be in the document. For example, the exact instance type for a database is a workload decision, not a landing zone decision. But the policy that requires all databases to be encrypted is a landing zone decision. Focus on the rules and boundaries, not the specifics of each workload.
Who should own the landing zone documentation?
One person or a small platform team should own it, but everyone should be able to suggest changes. The owner is responsible for keeping it accurate and reviewing change requests. Without a clear owner, the document gets ignored and becomes stale.
What if we use multiple cloud providers?
Document each provider’s landing zone separately, but keep a top-level document that explains the overall strategy. For example, “AWS is for production workloads, Azure is for Active Directory integration, and GCP is for data analytics.” The cross-provider decisions, like where data is replicated, belong in the top-level document.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.