Chapter 61 — Network design/refactoring: migrations, diagrams, IPAM, change safety

In one sentence

Network refactoring means changing paths, prefixes, policies, or dependencies without losing the ability to explain the system or roll it back.

The problem

Networks outlive the decisions that shaped them. Two companies merge and both used 10.0.0.0/16. A "temporary" VPN becomes the production path. A firewall rule nobody understands blocks a migration. Unlike application code, network state is spread across devices, cloud consoles, and DNS, and there's often no test suite. Refactoring it safely needs written artefacts and a staged process.

The artefacts professionals keep current

Diagram: L3 boundaries, routing domains, firewalls, load balancers, VPNs, NAT, internet edges. Ideally kept as code (Mermaid, D2, diagrams.net files in git) so it's reviewed alongside changes.
IPAM: who owns each prefix, gateway, VLAN/VPC/subnet, DHCP pool, and reserved range. A spreadsheet is a start; NetBox or a cloud IPAM is better.
Policy matrix: source → destination → protocol/port → reason → owner. Chapter 53's policytest turns it into tests.
Runbooks: how to test, fail over, and roll back.
Change log: when and why routes, firewall rules, DNS, and TLS changed.

IP address planning: decisions that last a decade

Allocate from one plan. Give each environment and region a large, non-overlapping block (for example 10.0.0.0/12 for prod, 10.16.0.0/12 for staging), and carve VPCs/VNets from it. Every future peering, VPN, and acquisition depends on this.
Leave room. Subnets are hard to resize. Kubernetes in particular consumes addresses fast (pod CIDRs, service CIDRs).
Avoid the popular defaults (10.0.0.0/16, 192.168.0.0/24, 172.17.0.0/16 for Docker) for anything that will ever be connected to something else. Someone else will have used them.
Plan IPv6 too. A /56 per site or VPC and /64 per subnet is conventional. IPv6 makes address scarcity go away but not address planning.

Build it in Go (30 min) — grow the subnet tool into an IPAM check

The subnet program from Chapter 10 already has the two operations every IPAM is built on: overlap detection and first-fit allocation:

$ go run ./subnet overlap 10.0.0.0/16 10.0.128.0/20 172.16.0.0/12
OVERLAP  10.0.0.0/16  <->  10.0.128.0/20

$ go run ./subnet alloc 10.0.0.0/16 22 10.0.0.0/24 10.0.4.0/22
allocated 10.0.8.0/22

Exercises (a small, real IPAM):

Read allocations from a CSV kept in git (prefix,owner,environment,purpose) and make overlap fail CI when a pull request adds a conflicting prefix. That single check prevents the most expensive network mistake there is.
Add alloc -owner team-payments -purpose "eks pods", which appends the new row to the CSV. Allocation now leaves a record of who asked and why.
Add a check-cloud command that compares the CSV with reality (for example, the output of aws ec2 describe-subnets saved as JSON) and reports prefixes in the cloud but not in IPAM, and the reverse. That's drift detection.

Migration pattern

1. Observe current traffic and dependencies (flow logs, DNS query logs, captures).
2. Add the new path in parallel.
3. Test with one client or canary prefix.
4. Move a small percentage (weighted DNS, LB weights, BGP prepending).
5. Monitor (error rate, latency, and the OLD path's traffic, which should fall).
6. Move the rest.
7. Keep rollback until the old path is demonstrably unused.
8. Remove the old path later, deliberately, as its own change.

Step 7 needs evidence: "nothing has used the old path for 7 days" from flow logs or counters, not "we think everything moved".

Change safety

Peer review every network change, as you would code, including firewall and DNS changes in the console. Infrastructure-as-code (Terraform, Pulumi) makes review possible.
Pre-flight and post-flight tests. Run the policy tests, netcheck, and a real transaction before and after. If the "before" run fails, stop: you can't verify a change against a baseline that's already broken.
Smallest blast radius first: one AZ, one region, one canary prefix.
Automatic rollback for anything that could cut off your own access (Chapter 53's safety rule).
Change freezes around critical business events, with an exception process for real emergencies.

Common migration failures

Failure	Prevention
Hidden dependency on old IP	flow logs, DNS logs, packet captures; grep configs for literal IPs
Firewall allows old subnet only	policy matrix and pre-flight tests from the new subnet
TTL too high for fast rollback	lower TTL ahead of migration (Chapter 55)
Asymmetric routing	trace both directions, check stateful firewalls
MTU changes in new path	test large packets and real application payloads (Chapter 54)
Overlapping CIDRs discovered mid-project	central IPAM with overlap checks in CI

Common confusions

"It's just a subnet change." Every prefix appears in firewall rules, route tables, security groups, allow-lists at partners, monitoring, and sometimes hard-coded in applications. Search for it before changing it.
"We'll document it after the migration." The diagram and IPAM are the plan. Without them you can't review the change.

Check yourself

Why is IP planning a leadership decision and not only a network one?
What evidence lets you remove an old path safely?
Design a CI check that would have prevented two VPCs from overlapping.
List the pre-flight tests you'd run before moving a subnet behind a new firewall.