Cross-Cloud IaC Translation with Parity Gates

Tier: Core · Hands-on time: ~35 minutes

Cross-cloud and cross-format IaC translation is one of the highest-frequency services-company tasks, and the research behind this track mirrors the pipeline-migration evidence from the DevOps track: assistants handle the mechanical 80% well, but LLMs are documented to hallucinate HCL resource types and attributes, so the translated stack is untrusted output until a deterministic harness — validate, plan, and a resource-inventory diff — says otherwise. The architect's job is the gate, not the typing.

When to use

• Format migrationa client standardizes on Terraform and hands you a CloudFormation or ARM estate to convert.
• Cloud-to-cloud movesan Azure workload is being re-platformed to AWS (or the reverse) and the IaC must follow.
• Multi-cloud paritythe same reference architecture must exist in two clouds and drift between the copies must be provable.
• Skip AI when the stack is under ~50 lines or uses only trivial resources — hand translation with the provider docs open is faster than reviewing a generated file.

Prerequisites

• Claude Code or a comparable repo-aware assistant with the source templates checked out.
• Terraform CLI (plus the source-format CLI — aws cloudformation validate-template, az bicep build) for the parity harness.
• A sandbox account or a plan-only workflowparity is proven by terraform plan output, not by applying to production.
• The vendor service-mapping pages for both clouds open in a browser tab. You will need them.

The workflow

1. 1.

   Inventory the source before translating. Ask the assistant for a resource inventory first — every resource type, count, and cross-reference in the source stack. This becomes the parity checklist the translation must satisfy.

2. 2.

   Translate with explicit anti-hallucination constraints. Sameer's GCC is converting a Meridian-style retail stack from CloudFormation to Terraform as part of a wave. His prompt:

   Copy

   Translate this CloudFormation stack (attached: web-tier.yaml, 14 resources)
   to Terraform using the hashicorp/aws provider.
   
   Rules:
   - Preserve resource-for-resource parity: same count, same types, same
     property values. Produce a mapping table (CFN logical ID -> Terraform
     address) as the first output.
   - If a CFN property has no Terraform equivalent, DO NOT invent an
     attribute. List it in a "gaps" section instead.
   - Do not add defaults the source did not set. If Terraform requires an
     argument CFN defaulted, flag it explicitly with the value you chose.
   - Keep names, tags, and retention/deletion policies identical.
   

3. 3.

   Run the deterministic chain. terraform init && terraform validate, then terraform plan against the sandbox. Validate catches invented resource types and attributes — the most common failure — for free, before any human review time is spent.

4. 4.

   Diff the inventories. Compare the plan's resource list against the step-1 inventory: same counts per type, no silent additions, no dropped resources. A translation that "simplifies" a DeletionPolicy or drops a bucket policy passes review by eye and fails here.

5. 5.

   Hunt the two classic service-mapping traps. When the translation crosses clouds, check every mapped service against both traps. Trap one: false equivalence — the AI maps to the service in the same category (SQS to Service Bus, CloudFront to Front Door) and assumes matching behavior; ordering guarantees, retry semantics, and feature flags differ, and the design silently changes. Trap two: silently different defaults — encryption, public-access posture, log retention, and instance families default differently across providers, so a property the source never set becomes a property the target sets wrong. Write both findings into the parity report even when the answer is "checked, no issue."

6. 6.

   Spot-check high-blast-radius properties by hand. IAM policies, network rules, deletion/retention settings, and anything encryption-related get a line-by-line human read regardless of what the harness says.

7. 7.

   Close the loop in the same conversation. Paste plan errors and inventory diffs back with "fix only the flagged resources, change nothing else" — scoped correction prevents the assistant from regenerating and re-breaking files that already passed.

8. 8.

   Ship the parity report with the code. Mapping table, gaps list, trap findings, plan output hash. The report is the reviewable artifact; the client signs the report, not the vibes.

Verify before you trust it

• Validate passes clean.terraform validate returns zero errors — invented attributes and resource types die here. If it fails, do not hand-patch; make the assistant fix its own output against the error text.
• Plan inventory matches source inventory. Resource counts per type are identical, and every source logical ID appears in the mapping table. Anything unmapped is a finding, not an oversight.
• Every cross-cloud service mapping is checked against vendor docs. For each mapped pair, confirm the specific features the design relies on (FIFO ordering, TLS policy, failover behavior) exist on the target service — never accept the AI's equivalence claim as fact.
• Defaults are enumerated, not assumed. For properties the source never set, list what the target provider will default them to, from the provider documentation — not from the assistant's memory.
• A second plan is a no-op. Run terraform plan again after apply in the sandbox; a non-empty diff means the translation encodes drift from day one.

Restricted-environment variant

Client MSAs govern what leaves the building: extract the AI-usage and data-handling constraints from the MSA before pointing any assistant at client templates. If public tools are prohibited, strip the templates first — replace account IDs, ARNs, CIDR ranges, hostnames, and client-identifying tags with placeholders, translate the sanitized version, then substitute values locally. Where the client offers approved tenancy (Bedrock or Azure OpenAI inside their subscription), run the assistant there instead. For fully restricted estates, a local model via Ollama can do the mechanical translation; the parity harness — validate, plan, inventory diff — is identical offline and does all the real trust work anyway.