<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Manoj Kumar Kagitha</title>
    <description>The latest articles on DEV Community by Manoj Kumar Kagitha (@manojkagitha).</description>
    <link>https://dev.to/manojkagitha</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4151562%2F47172455-168c-42e8-98fd-cbd3d4f57c9d.png</url>
      <title>DEV Community: Manoj Kumar Kagitha</title>
      <link>https://dev.to/manojkagitha</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/manojkagitha"/>
    <language>en</language>
    <item>
      <title>Multi-Cloud Terraform: One Codebase, Three Clouds</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Tue, 17 Nov 2026 17:24:14 +0000</pubDate>
      <link>https://dev.to/manojkagitha/multi-cloud-terraform-one-codebase-three-clouds-4pc7</link>
      <guid>https://dev.to/manojkagitha/multi-cloud-terraform-one-codebase-three-clouds-4pc7</guid>
      <description>&lt;p&gt;Every few years, someone proposes running everything on every cloud. The pitch is resilience and bargaining power. The reality is three times the state files, three times the pipelines, and three sets of cloud quirks living in your head. Multi-cloud with Terraform is absolutely doable. Whether you should do it is a separate question, and this post answers both.&lt;/p&gt;

&lt;p&gt;We will cover provider aliases, the module abstraction pattern that actually works, where abstractions break down, CI/CD across clouds, a realistic repo layout, and the operational reality check nobody puts in the sales deck.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why teams go multi-cloud
&lt;/h2&gt;

&lt;p&gt;The legitimate reasons, in rough order of how often they hold up:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Residency and compliance.&lt;/strong&gt; A regulator or a customer contract requires data in a specific cloud or region. This is the strongest reason. It is not a choice.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Resilience.&lt;/strong&gt; Surviving a cloud-wide outage. Real, but expensive, and most teams overestimate both the likelihood and their ability to fail over cleanly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Best of breed.&lt;/strong&gt; One cloud's managed database, another's ML platform. Valid for specific workloads, painful as a general strategy.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Bargaining power.&lt;/strong&gt; Threatening to leave gets you a discount. Actually leaving costs more than the discount.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If your reason is number 4, or "our architect read a blog post," stop here. The rest of this post is for teams with a real requirement.&lt;/p&gt;

&lt;h2&gt;
  
  
  Provider aliases: the mechanics
&lt;/h2&gt;

&lt;p&gt;Terraform supports multiple instances of the same provider through aliases. This is how you target two regions, or two accounts, from one configuration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;required_providers&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;aws&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;source&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"hashicorp/aws"&lt;/span&gt;
      &lt;span class="n"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"~&amp;gt; 5.0"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;# Default: primary region&lt;/span&gt;
&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;# Alias: DR region&lt;/span&gt;
&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;alias&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"west"&lt;/span&gt;
  &lt;span class="n"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-west-2"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket"&lt;/span&gt; &lt;span class="s2"&gt;"primary"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-data-primary"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket"&lt;/span&gt; &lt;span class="s2"&gt;"dr"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;west&lt;/span&gt;
  &lt;span class="n"&gt;bucket&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-data-dr"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Aliases also span accounts. Assume a role in each account:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;alias&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
  &lt;span class="n"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
  &lt;span class="n"&gt;assume_role&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;role_arn&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"arn:aws:iam::111122223333:role/terraform-prod"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;alias&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"staging"&lt;/span&gt;
  &lt;span class="n"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
  &lt;span class="n"&gt;assume_role&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;role_arn&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"arn:aws:iam::444455556666:role/terraform-staging"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Modules accept providers explicitly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"network_prod"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"./modules/network"&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;aws&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;prod&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;cidr_block&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"10.1.0.0/16"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"network_staging"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"./modules/network"&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;aws&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;staging&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;cidr_block&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"10.2.0.0/16"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the easy part. The hard part is not syntax. It is deciding what "the same" means across clouds that are not the same.&lt;/p&gt;

&lt;h2&gt;
  
  
  The abstraction pattern that works
&lt;/h2&gt;

&lt;p&gt;The pattern that survives contact with reality: &lt;strong&gt;one module per cloud, identical inputs, cloud-specific internals.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;You do not write one module that provisions "a network" on any cloud. You write three modules with the same interface:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;modules/
  network-aws/
    main.tf
    variables.tf
    outputs.tf
  network-azure/
    main.tf
    variables.tf
    outputs.tf
  network-gcp/
    main.tf
    variables.tf
    outputs.tf
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Same variables in, same outputs out. Different resources inside.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# modules/network-aws/variables.tf&lt;/span&gt;
&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Base name for network resources"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"cidr_block"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Primary CIDR for the VPC"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"availability_zones"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"AZs to spread subnets across"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"environment"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Environment label for tagging"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# modules/network-aws/outputs.tf&lt;/span&gt;
&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"network_id"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws_vpc&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"VPC ID"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"private_subnet_ids"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws_subnet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;private&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Private subnet IDs"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"public_subnet_ids"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws_subnet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Public subnet IDs"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# modules/network-azure/variables.tf: identical inputs&lt;/span&gt;
&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Base name for network resources"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"cidr_block"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Primary CIDR for the VNet"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"availability_zones"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Zones to spread subnets across"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"environment"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Environment label for tagging"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# modules/network-azure/outputs.tf: identical outputs&lt;/span&gt;
&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"network_id"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;azurerm_virtual_network&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"VNet ID"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"private_subnet_ids"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;azurerm_subnet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;private&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Private subnet IDs"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"public_subnet_ids"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;azurerm_subnet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;public&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Public subnet IDs"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The calling code does not care which cloud it is:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/prod-aws/main.tf&lt;/span&gt;
&lt;span class="n"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"network"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;source&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"../../modules/network-aws"&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;               &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
  &lt;span class="n"&gt;cidr_block&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"10.1.0.0/16"&lt;/span&gt;
  &lt;span class="n"&gt;availability_zones&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"us-east-1a"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1b"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1c"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;environment&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/prod-azure/main.tf&lt;/span&gt;
&lt;span class="n"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"network"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;source&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"../../modules/network-azure"&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;               &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
  &lt;span class="n"&gt;cidr_block&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"10.1.0.0/16"&lt;/span&gt;
  &lt;span class="n"&gt;availability_zones&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"2"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"3"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;environment&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice the availability zones input. AWS wants &lt;code&gt;us-east-1a&lt;/code&gt;. Azure wants &lt;code&gt;1&lt;/code&gt;. Same variable, different values. The interface is identical. The values are cloud-native. That is the right level of abstraction: common shape, native details.&lt;/p&gt;

&lt;h2&gt;
  
  
  When to share code vs when to diverge
&lt;/h2&gt;

&lt;p&gt;The temptation is to abstract harder: one module, conditionals per cloud, a &lt;code&gt;cloud&lt;/code&gt; variable that switches behavior. Resist it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Do not do this&lt;/span&gt;
&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_vpc"&lt;/span&gt; &lt;span class="s2"&gt;"main"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;count&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cloud&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
  &lt;span class="n"&gt;cidr_block&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cidr_block&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_virtual_network"&lt;/span&gt; &lt;span class="s2"&gt;"main"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;count&lt;/span&gt;               &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cloud&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"azure"&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;
  &lt;span class="n"&gt;address_space&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cidr_block&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="n"&gt;location&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;location&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This looks DRY. It is not. It is one module with two implementations stapled together, and every change has to reason about both. The conditionals multiply. The variable list becomes the union of every cloud's requirements, most of them irrelevant for any given apply. Code review becomes an exercise in tracking which branch you are in.&lt;/p&gt;

&lt;p&gt;The rule I use: &lt;strong&gt;abstract the interface, not the implementation.&lt;/strong&gt; Shared inputs and outputs. Separate internals. Duplication of structure across three small modules is cheaper than one clever module with cloud conditionals.&lt;/p&gt;

&lt;p&gt;Share code where clouds genuinely agree: naming conventions, tagging strategy, input validation, documentation patterns. Diverge where clouds differ: resource types, networking primitives, IAM models. The boundary between "genuinely agree" and "superficially similar" is where multi-cloud modules live or die.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cloud-specific realities
&lt;/h2&gt;

&lt;p&gt;Some differences you will hit in the first week:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Naming constraints.&lt;/strong&gt; Azure storage accounts: lowercase, alphanumeric, 3-24 characters, globally unique. AWS S3 buckets: lowercase, hyphens allowed, 3-63 characters, globally unique. GCP buckets: similar to S3 but with its own edge cases. Write a naming module per cloud, or at minimum a validation block:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"storage_name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Storage account name (Azure: 3-24 chars, lowercase alphanumeric)"&lt;/span&gt;

  &lt;span class="n"&gt;validation&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;condition&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;can&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;regex&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"^[a-z0-9]{3,24}$"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;storage_name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;error_message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Azure storage account names must be 3-24 lowercase alphanumeric characters."&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Tagging vs labels.&lt;/strong&gt; AWS uses tags (key-value, up to 50 per resource). Azure uses tags (key-value, up to 50). GCP uses labels (lowercase, specific character rules, up to 64 per resource). Your tagging module needs per-cloud normalization. Do not pass AWS-style tags straight into GCP labels. They will fail validation in ways that are annoying to debug.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Networking primitives do not map 1:1.&lt;/strong&gt; An AWS VPC with public and private subnets across AZs is not the same thing as an Azure VNet with subnets, and neither maps cleanly to a GCP VPC with its regional subnets. GCP subnets are regional. AWS subnets are zonal. Azure subnets live inside one VNet with no AZ affinity at the subnet level. Any abstraction that pretends these are identical is lying to you. The identical-inputs pattern handles this: the caller says "three zones," and each module translates that into its cloud's networking model.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;IAM is the deepest divergence.&lt;/strong&gt; AWS IAM (users, roles, policies, trust relationships), Azure RBAC (role definitions, assignments, scopes), GCP IAM (roles, bindings, conditions). There is no common abstraction here that survives contact with a real security review. Do IAM per cloud, natively, with per-cloud modules. Do not try to unify it.&lt;/p&gt;

&lt;h2&gt;
  
  
  CI/CD across clouds
&lt;/h2&gt;

&lt;p&gt;Each cloud needs its own authentication in the pipeline, and the pipeline needs to keep them separated.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AWS:&lt;/strong&gt; OIDC with GitHub Actions is the standard now. No long-lived keys.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# .github/workflows/terraform-aws.yml
&lt;/span&gt;&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;id-token&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;apply&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;aws-actions/configure-aws-credentials@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;role-to-assume&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;arn:aws:iam::111122223333:role/github-terraform&lt;/span&gt;
          &lt;span class="na"&gt;aws-region&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;us-east-1&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -backend-config="key=prod-aws.tfstate"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform apply -auto-approve plan.tfplan&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Azure:&lt;/strong&gt; federated credentials on the service principal, same OIDC pattern.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# .github/workflows/terraform-azure.yml
&lt;/span&gt;&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;id-token&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;apply&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;azure/login@v2&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;client-id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.AZURE_CLIENT_ID }}&lt;/span&gt;
          &lt;span class="na"&gt;tenant-id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.AZURE_TENANT_ID }}&lt;/span&gt;
          &lt;span class="na"&gt;subscription-id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.AZURE_SUBSCRIPTION_ID }}&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -backend-config="key=prod-azure.tfstate"&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform apply -auto-approve plan.tfplan&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;GCP:&lt;/strong&gt; workload identity federation.&lt;/p&gt;

&lt;p&gt;Separate workflows per cloud, not one mega-workflow with conditionals. Same reasoning as the modules: the orchestration shape is shared (plan on PR, apply on merge), the authentication is per cloud. If the Azure pipeline breaks, AWS deploys are unaffected.&lt;/p&gt;

&lt;p&gt;Backend state follows the same split. One state file per cloud per environment per component. From Article 1's layout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;prod/
  aws/
    network/terraform.tfstate
    compute/terraform.tfstate
  azure/
    network/terraform.tfstate
    compute/terraform.tfstate
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Yes, this is a lot of state files. That is the cost of multi-cloud, stated plainly.&lt;/p&gt;

&lt;h2&gt;
  
  
  A realistic repo layout
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;infra/
  modules/
    network-aws/
    network-azure/
    network-gcp/
    compute-aws/
    compute-azure/
    tagging/          # shared: naming and tag normalization per cloud
  envs/
    prod-aws/
      main.tf         # composes modules, sets AWS values
      variables.tf
      backend.tf
    prod-azure/
      main.tf         # composes modules, sets Azure values
      variables.tf
      backend.tf
    prod-gcp/
      main.tf
      variables.tf
      backend.tf
  bootstrap/
    aws/              # state backend per account (Article 1)
    azure/
    gcp/
.github/
  workflows/
    terraform-aws.yml
    terraform-azure.yml
    terraform-gcp.yml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each &lt;code&gt;envs/&lt;/code&gt; directory is independently deployable. Each has its own state, its own pipeline, its own blast radius. A bad apply in &lt;code&gt;prod-azure&lt;/code&gt; cannot touch &lt;code&gt;prod-aws&lt;/code&gt;. That isolation is the entire point of the layout.&lt;/p&gt;

&lt;h2&gt;
  
  
  The operational reality check
&lt;/h2&gt;

&lt;p&gt;Here is what multi-cloud actually costs, beyond the code:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;State files multiply.&lt;/strong&gt; Three clouds times N components times M environments. Each one needs a backend, locking, IAM, and someone who knows it exists.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pipelines multiply.&lt;/strong&gt; Per-cloud auth, per-cloud apply jobs, per-cloud failure modes. Your CI minutes go up. Your pipeline debugging surface triples.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cognitive load multiplies.&lt;/strong&gt; Your team now needs working knowledge of three clouds' networking, IAM, and quirks. Hiring gets harder. Onboarding takes longer. The person who knows all three becomes a single point of failure.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Drift detection triples.&lt;/strong&gt; Three clouds to scan, three sets of out-of-band changes to catch.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cost visibility fragments.&lt;/strong&gt; Each cloud has its own billing, its own cost explorer, its own tagging requirements. Unified cost views need additional tooling.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;None of this is an argument against multi-cloud. It is an argument for doing it for a real reason. Residency requirements, contractual obligations, genuine resilience needs: these justify the cost. "Optionality" and resume-driven architecture do not.&lt;/p&gt;

&lt;p&gt;Start with one cloud done well. Articles 1 through 6 of this series are about doing one cloud well: state, modules, CI/CD, drift, secrets. Add the second cloud when a requirement forces it, using the patterns above. Add the third when the second one taught you what you got wrong.&lt;/p&gt;

&lt;h2&gt;
  
  
  Series closing
&lt;/h2&gt;

&lt;p&gt;Seven articles, one arc:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Remote state.&lt;/strong&gt; The foundation everything stands on. Backends, bootstrapping, locking, blast radius.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reusable modules.&lt;/strong&gt; API gateways as the example, versioned registries, composition that survives team growth.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;CI/CD.&lt;/strong&gt; Plan on PR, apply on merge, per-environment pipelines with OIDC.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Drift detection.&lt;/strong&gt; Finding the gap between state and reality, and closing it without drama.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Workspaces vs directories.&lt;/strong&gt; Environment strategy, and why directories win at scale.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Vault integration.&lt;/strong&gt; Secrets belong in Vault, state is still a secrets surface, dynamic credentials over static ones.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Multi-cloud.&lt;/strong&gt; One codebase, three clouds, and the honesty to ask whether you need it.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The thread running through all seven: Terraform rewards boring discipline. Remote state, small modules, locked applies, secrets in the right place. None of it is exciting. All of it is what separates infrastructure that survives from infrastructure that pages you at 3 AM.&lt;/p&gt;

&lt;p&gt;Thanks for reading the series. If you are starting the HashiCorp Ambassador track, or just trying to run Terraform like you mean it, I hope something in here saved you an afternoon.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>aws</category>
      <category>azure</category>
      <category>gcp</category>
    </item>
    <item>
      <title>Secrets in Terraform: Vault Integration Without Leaking State</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Wed, 11 Nov 2026 19:42:39 +0000</pubDate>
      <link>https://dev.to/manojkagitha/secrets-in-terraform-vault-integration-without-leaking-state-id7</link>
      <guid>https://dev.to/manojkagitha/secrets-in-terraform-vault-integration-without-leaking-state-id7</guid>
      <description>&lt;p&gt;Terraform is bad at secrets. Not because it is poorly designed, but because secrets were never its job. Terraform manages infrastructure. Secrets belong to a secrets manager. The trouble starts when people treat Terraform like a secrets store, because Terraform will happily comply, and then it will store every secret it touches in plain text in your state file.&lt;/p&gt;

&lt;p&gt;This post covers how to integrate HashiCorp Vault with Terraform properly: dynamic secrets versus static reads, AppRole authentication for CI/CD, sensitive outputs, and the uncomfortable truth about what still leaks even when you do everything right.&lt;/p&gt;

&lt;h2&gt;
  
  
  The core problem
&lt;/h2&gt;

&lt;p&gt;Three ways secrets leak in a typical Terraform workflow:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;State files.&lt;/strong&gt; Terraform state stores every attribute of every resource in plain text. Database passwords, API keys, connection strings. If you read Article 1, you already encrypt your state bucket and restrict IAM access. That is necessary. It is not sufficient, because anyone with read access to state can read every secret in it.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Variables and logs.&lt;/strong&gt; Secrets passed as variables end up in plan output, in CI logs, and in shell history. &lt;code&gt;terraform plan -var="db_password=hunter2"&lt;/code&gt; is now in three places you do not control.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Code.&lt;/strong&gt; Secrets committed to &lt;code&gt;.tf&lt;/code&gt; files or &lt;code&gt;.tfvars&lt;/code&gt; files end up in git history forever. Deleting the file later does not delete the commit.&lt;/p&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Vault solves the storage problem. It does not automatically solve the state problem. You have to design for both.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Vault provider
&lt;/h2&gt;

&lt;p&gt;The Vault provider lets Terraform read secrets from Vault at plan and apply time, and lets you manage Vault resources (policies, mounts, roles) with Terraform itself. These are two different jobs. Keep them separate in your head.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reading secrets (data sources):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;required_providers&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;vault&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;source&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"hashicorp/vault"&lt;/span&gt;
      &lt;span class="n"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"~&amp;gt; 4.0"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"vault"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="c1"&gt;# Address and auth configured via environment or AppRole (see below)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Managing Vault itself (resources):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_mount"&lt;/span&gt; &lt;span class="s2"&gt;"db"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"database"&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"database"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_policy"&lt;/span&gt; &lt;span class="s2"&gt;"app_reader"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app-reader"&lt;/span&gt;
  &lt;span class="n"&gt;policy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;lt;-&lt;/span&gt;&lt;span class="no"&gt;EOT&lt;/span&gt;
    &lt;span class="n"&gt;path&lt;/span&gt; &lt;span class="s2"&gt;"secret/data/app/*"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;capabilities&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"read"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="no"&gt;EOT&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;One Terraform project manages Vault's configuration. Separate projects read secrets from Vault at runtime. Do not mix these in the same state file. The project that configures Vault needs admin-level access. The projects that read secrets should have the minimum Vault policy for their needs.&lt;/p&gt;

&lt;h2&gt;
  
  
  Static secrets vs dynamic secrets
&lt;/h2&gt;

&lt;p&gt;Vault gives you two models. They solve different problems.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Static secrets&lt;/strong&gt; are values someone wrote into Vault. An API key, a TLS certificate, a third-party token. Terraform reads them with a data source:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="s2"&gt;"vault_kv_secret_v2"&lt;/span&gt; &lt;span class="s2"&gt;"api_key"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;mount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"secret"&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app/payments-api-key"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_ssm_parameter"&lt;/span&gt; &lt;span class="s2"&gt;"payments_key"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"/prod/payments/api-key"&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"SecureString"&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_kv_secret_v2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api_key&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"key"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is fine for secrets that change rarely. The weakness: Terraform stores the read value in state. You used Vault for storage, but the secret still lands in your state file in plain text. Vault did not fix the state problem. It just moved the secret one hop.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Dynamic secrets&lt;/strong&gt; are credentials Vault generates on demand, with a time-to-live. This is the model you want for databases. Instead of storing a database password anywhere, Vault creates a temporary user, hands Terraform the credentials, and revokes them when the lease expires.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Configure the database secrets engine (in your Vault-management project)&lt;/span&gt;
&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_database_secret_backend_connection"&lt;/span&gt; &lt;span class="s2"&gt;"postgres"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vault_mount&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;          &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod-postgres"&lt;/span&gt;
  &lt;span class="n"&gt;allowed_roles&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"app-role"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

  &lt;span class="n"&gt;postgresql&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;connection_url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"postgresql://{{username}}:{{password}}@db.internal:5432/app"&lt;/span&gt;
    &lt;span class="n"&gt;username&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_admin_user&lt;/span&gt;
    &lt;span class="n"&gt;password&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_admin_password&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_database_secret_backend_role"&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vault_mount&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app-role"&lt;/span&gt;
  &lt;span class="n"&gt;db_name&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vault_database_secret_backend_connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;postgres&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;
  &lt;span class="n"&gt;creation_statements&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="s2"&gt;"CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="s2"&gt;"GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;default_ttl&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3600&lt;/span&gt;
  &lt;span class="n"&gt;max_ttl&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;86400&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then the consuming project reads a fresh credential:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="s2"&gt;"vault_database_secret_backend_static_role"&lt;/span&gt; &lt;span class="s2"&gt;"db_creds"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"database"&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app-role"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Dynamic credentials shrink the blast radius. A leaked credential expires within hours. There is no long-lived password to rotate, because there is no long-lived password. This is the single biggest upgrade you can make to database credential handling in Terraform.&lt;/p&gt;

&lt;h2&gt;
  
  
  Full example: RDS with Vault-managed credentials
&lt;/h2&gt;

&lt;p&gt;Here is the pattern end to end. Terraform provisions the database. Vault manages who can talk to it. Terraform never stores a database password.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# 1. Provision the database (infrastructure project)&lt;/span&gt;
&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_db_instance"&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;identifier&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app-prod"&lt;/span&gt;
  &lt;span class="n"&gt;engine&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"postgres"&lt;/span&gt;
  &lt;span class="n"&gt;engine_version&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"15.4"&lt;/span&gt;
  &lt;span class="n"&gt;instance_class&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"db.r6g.large"&lt;/span&gt;
  &lt;span class="n"&gt;allocated_storage&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;

  &lt;span class="n"&gt;db_name&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt;
  &lt;span class="n"&gt;username&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"admin"&lt;/span&gt;
  &lt;span class="c1"&gt;# The admin password comes from Vault, set once at creation&lt;/span&gt;
  &lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_kv_secret_v2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db_admin&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"password"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;

  &lt;span class="n"&gt;vpc_security_group_ids&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;aws_security_group&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;db_subnet_group_name&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws_db_subnet_group&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;

  &lt;span class="n"&gt;backup_retention_period&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;7&lt;/span&gt;
  &lt;span class="n"&gt;storage_encrypted&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="n"&gt;skip_final_snapshot&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;

  &lt;span class="c1"&gt;# Prevent accidental password churn on every apply&lt;/span&gt;
  &lt;span class="n"&gt;lifecycle&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;ignore_changes&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;password&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;ignore_changes&lt;/code&gt; on password matters. Without it, any drift in how Vault reports the secret triggers a password reset on every apply. You want the password set once at creation, then managed by your rotation process, not by Terraform diff noise.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# 2. Application gets dynamic credentials (separate, least-privilege)&lt;/span&gt;
&lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="s2"&gt;"vault_kv_secret_v2"&lt;/span&gt; &lt;span class="s2"&gt;"db_admin"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;mount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"secret"&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"db/prod-admin"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;# The app's Kubernetes secret uses a Vault-injected dynamic credential,&lt;/span&gt;
&lt;span class="c1"&gt;# not a Terraform-managed static password&lt;/span&gt;
&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"kubernetes_secret"&lt;/span&gt; &lt;span class="s2"&gt;"db"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;metadata&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;name&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"db-credentials"&lt;/span&gt;
    &lt;span class="n"&gt;namespace&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;# In production, prefer Vault Agent sidecar injection over&lt;/span&gt;
    &lt;span class="c1"&gt;# Terraform-managed Kubernetes secrets. This example shows the&lt;/span&gt;
    &lt;span class="c1"&gt;# Terraform path for completeness.&lt;/span&gt;
    &lt;span class="n"&gt;username&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app-service"&lt;/span&gt;
    &lt;span class="n"&gt;password&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_kv_secret_v2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db_admin&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"password"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Opaque"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The boundary here is deliberate. Terraform provisions the database and the network around it. Vault owns credential lifecycle. The application authenticates through Vault, not through values Terraform wrote into state six months ago.&lt;/p&gt;

&lt;h2&gt;
  
  
  AppRole auth for CI/CD
&lt;/h2&gt;

&lt;p&gt;The provider needs to authenticate to Vault. Hardcoding a token in CI/CD variables recreates the exact problem Vault was supposed to solve. Use AppRole instead.&lt;/p&gt;

&lt;p&gt;AppRole has two parts: a RoleID (like a username, safe to embed in pipeline config) and a SecretID (like a password, delivered securely per run). The pipeline combines them to get a short-lived Vault token.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Vault side: define the AppRole (in your Vault-management project)&lt;/span&gt;
&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_auth_backend"&lt;/span&gt; &lt;span class="s2"&gt;"approle"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"approle"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"vault_approle_auth_backend_role"&lt;/span&gt; &lt;span class="s2"&gt;"ci"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vault_auth_backend&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;approle&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;
  &lt;span class="n"&gt;role_name&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-ci"&lt;/span&gt;
  &lt;span class="n"&gt;token_policies&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"terraform-ci-policy"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;token_ttl&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;600&lt;/span&gt;
  &lt;span class="n"&gt;token_max_ttl&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1800&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# CI side: the Terraform project authenticates with AppRole&lt;/span&gt;
&lt;span class="n"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"vault"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;address&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"https://vault.internal:8200"&lt;/span&gt;
  &lt;span class="n"&gt;auth_login&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;path&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"auth/approle/login"&lt;/span&gt;
    &lt;span class="n"&gt;parameters&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;role_id&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_role_id&lt;/span&gt;
      &lt;span class="n"&gt;secret_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kd"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_secret_id&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In your pipeline, the RoleID lives in pipeline variables (it is not secret). The SecretID is injected per run from your CI system's secret store, or better, delivered through your cloud's native mechanism. On AWS, the pipeline role can fetch the SecretID from Secrets Manager at runtime. On GitHub Actions, use OIDC to Vault so there is no SecretID to manage at all.&lt;/p&gt;

&lt;p&gt;The token TTL is 10 minutes. Even if it leaks into a log, it is dead before anyone can use it. Short TTLs are the whole point.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sensitive outputs and plan redaction
&lt;/h2&gt;

&lt;p&gt;Mark outputs that carry secrets as sensitive:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"db_endpoint"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;aws_db_instance&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;endpoint&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Database endpoint (not secret)"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"db_password"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;vault_kv_secret_v2&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;db_admin&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"password"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="n"&gt;sensitive&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Database admin password (secret)"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;sensitive = true&lt;/code&gt; redacts the value from plan and apply output. It shows as &lt;code&gt;(sensitive value)&lt;/code&gt; instead of the real string. This keeps secrets out of CI logs and terminal scrollback.&lt;/p&gt;

&lt;p&gt;But understand what it does not do. Sensitive outputs are still stored in state in plain text. The redaction is display-only. It protects your logs, not your state file. Anyone with state read access sees the value.&lt;/p&gt;

&lt;p&gt;Also note: sensitivity propagates. If a non-sensitive output derives from a sensitive value, Terraform marks the whole chain sensitive. This is correct behavior, but it can surprise you when half your outputs suddenly show as redacted. Trace the chain back to find the sensitive input.&lt;/p&gt;

&lt;h2&gt;
  
  
  What still leaks, honestly
&lt;/h2&gt;

&lt;p&gt;Even with Vault, AppRole, and sensitive outputs, some things still leak. You should know exactly what.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;State files remain a secrets surface.&lt;/strong&gt; Any secret Terraform reads, even from Vault, lands in state in plain text. Data sources are not exempt. &lt;code&gt;data.vault_kv_secret_v2.api_key&lt;/code&gt; puts the key in state. There is no way around this inside Terraform. The mitigations are the ones from Article 1: backend encryption, tight IAM on the state bucket, and minimal read access.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Plan files.&lt;/strong&gt; &lt;code&gt;terraform plan -out=plan.tfplan&lt;/code&gt; saves the plan to disk, including any non-redacted values. Do not archive plan files in artifact storage without thinking about what is inside them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The real fix is architectural, not configurational.&lt;/strong&gt; The less Terraform touches secrets directly, the less leaks. Prefer these patterns in order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Best: the application authenticates to Vault directly at runtime (Vault Agent sidecar, cloud auth). Terraform never sees the secret at all.&lt;/li&gt;
&lt;li&gt;Good: Terraform reads from Vault and passes to a managed secret store (AWS Secrets Manager, Azure Key Vault). The secret transits through state once, then lives in the right place.&lt;/li&gt;
&lt;li&gt;Acceptable: Terraform reads from Vault for one-time provisioning (initial admin password). Documented, audited, rotated after.&lt;/li&gt;
&lt;li&gt;Avoid: Terraform as the system of record for secrets. Static passwords in &lt;code&gt;.tfvars&lt;/code&gt;, checked into git, passed through five modules.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Most teams live at level 2 or 3. That is fine. Just know which level you are at.&lt;/p&gt;

&lt;h2&gt;
  
  
  Rotation: what happens when secrets change
&lt;/h2&gt;

&lt;p&gt;Secrets rotate. Your Terraform needs to handle it without drama.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Vault-managed rotation:&lt;/strong&gt; if Vault rotates a dynamic credential, the old lease expires and the application picks up new credentials on its next Vault read. Terraform does not need to do anything, because Terraform should not be holding the credential in the first place. This is the payoff of the dynamic model.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Static secret rotation:&lt;/strong&gt; when someone rotates the API key in Vault, the next &lt;code&gt;terraform plan&lt;/code&gt; shows a diff on every resource that consumed the old value. This is correct. Apply it, and the new value propagates. The risk is surprise: a rotation at 2 AM produces a diff nobody expected at 9 AM. Coordinate rotations with the team that owns the consuming Terraform.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Forcing re-reads:&lt;/strong&gt; if Terraform is not picking up a rotated secret, the data source may be cached in state. &lt;code&gt;terraform apply -refresh-only&lt;/code&gt; re-reads all data sources without changing infrastructure. Use it after rotations to confirm the new values flow through.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Tainting:&lt;/strong&gt; if a resource was provisioned with a compromised credential, &lt;code&gt;terraform taint&lt;/code&gt; marks it for recreation on the next apply. Taint the database, not the secret. The secret lives in Vault. Terraform recreates the infrastructure around the new credential.&lt;/p&gt;

&lt;h2&gt;
  
  
  The boundary
&lt;/h2&gt;

&lt;p&gt;Here is the mental model I use. Draw a line:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Terraform manages:&lt;/strong&gt; infrastructure, Vault's own configuration (mounts, policies, roles, auth backends), IAM bindings, network.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Vault manages:&lt;/strong&gt; credential lifecycle, rotation, lease revocation, audit of who read what.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The application manages:&lt;/strong&gt; authenticating to Vault at runtime and using the credentials it gets.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Terraform configures the lock. Vault holds the keys. The application turns the handle. When each system stays in its lane, secrets stop leaking through the cracks between them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pre-flight checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] No secrets in &lt;code&gt;.tf&lt;/code&gt;, &lt;code&gt;.tfvars&lt;/code&gt;, or git history (check with &lt;code&gt;git log -S 'password'&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;[ ] Vault provider configured; Vault-management project separated from secret-consuming projects&lt;/li&gt;
&lt;li&gt;[ ] Dynamic credentials for databases (database secrets engine with TTLs), not static passwords&lt;/li&gt;
&lt;li&gt;[ ] CI/CD authenticates via AppRole or OIDC, never a hardcoded token&lt;/li&gt;
&lt;li&gt;[ ] Vault tokens issued with short TTLs (minutes, not days)&lt;/li&gt;
&lt;li&gt;[ ] Outputs carrying secrets marked &lt;code&gt;sensitive = true&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] State backend encrypted, IAM restricted, versioning on (Article 1 checklist still applies)&lt;/li&gt;
&lt;li&gt;[ ] Rotation procedure documented: who rotates, who gets notified, what Terraform does after&lt;/li&gt;
&lt;li&gt;[ ] Team knows the architectural goal: Terraform touches secrets as little as possible&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;Vault does not make Terraform good at secrets. Nothing does. What Vault gives you is a clean boundary: secrets live in Vault, infrastructure lives in Terraform, and the two meet through short-lived, least-privilege reads. Dynamic credentials over static ones. AppRole over hardcoded tokens. And always, always assume the state file knows everything, because it does.&lt;/p&gt;

&lt;p&gt;Next week is the finale: multi-cloud Terraform. One codebase, three clouds, and an honest look at when the abstraction is worth it and when it is not.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>security</category>
      <category>vault</category>
      <category>devops</category>
    </item>
    <item>
      <title>Terraform Workspaces vs Directory-per-Environment: An Enterprise Take</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Tue, 10 Nov 2026 16:37:32 +0000</pubDate>
      <link>https://dev.to/manojkagitha/terraform-workspaces-vs-directory-per-environment-an-enterprise-take-5eib</link>
      <guid>https://dev.to/manojkagitha/terraform-workspaces-vs-directory-per-environment-an-enterprise-take-5eib</guid>
      <description>&lt;p&gt;Every Terraform team eventually faces the same question: how do we manage dev, staging, and prod from one codebase? Terraform offers two answers. Workspaces let you reuse one configuration with separate state per workspace. Directory-per-environment gives each environment its own directory, its own backend config, and its own variables. Both work. Both have sharp edges. Picking the wrong one for your team size creates the kind of mess that takes a quarter to unwind.&lt;/p&gt;

&lt;p&gt;This post explains how each approach actually works, where each one breaks down, and the hybrid pattern most growing teams land on.&lt;/p&gt;

&lt;h2&gt;
  
  
  How workspaces actually work
&lt;/h2&gt;

&lt;p&gt;A workspace is a named container for state inside a single backend. One configuration, multiple state files. The commands are simple:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform workspace new staging    &lt;span class="c"&gt;# create and switch to staging&lt;/span&gt;
terraform workspace list           &lt;span class="c"&gt;# show all workspaces, * marks current&lt;/span&gt;
terraform workspace &lt;span class="k"&gt;select&lt;/span&gt; prod    &lt;span class="c"&gt;# switch to prod&lt;/span&gt;
terraform workspace show           &lt;span class="c"&gt;# print the current workspace name&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With an S3 backend, each workspace gets its own state path. You control the layout with &lt;code&gt;workspace_key_prefix&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt; &lt;span class="s2"&gt;"s3"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;bucket&lt;/span&gt;               &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state"&lt;/span&gt;
    &lt;span class="n"&gt;key&lt;/span&gt;                  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app/terraform.tfstate"&lt;/span&gt;
    &lt;span class="n"&gt;workspace_key_prefix&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"workspaces"&lt;/span&gt;
    &lt;span class="n"&gt;region&lt;/span&gt;               &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
    &lt;span class="n"&gt;dynamodb_table&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks"&lt;/span&gt;
    &lt;span class="n"&gt;encrypt&lt;/span&gt;              &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With this config, the &lt;code&gt;staging&lt;/code&gt; workspace stores state at &lt;code&gt;workspaces/staging/app/terraform.tfstate&lt;/code&gt;. The &lt;code&gt;default&lt;/code&gt; workspace uses the key as-is: &lt;code&gt;app/terraform.tfstate&lt;/code&gt;. Many teams delete or ignore the default workspace to avoid confusion, since its state path looks different from all the others.&lt;/p&gt;

&lt;p&gt;Inside your configuration, &lt;code&gt;terraform.workspace&lt;/code&gt; exposes the current workspace name, so resources can vary by environment:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket"&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-app-${terraform.workspace}"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_instance"&lt;/span&gt; &lt;span class="s2"&gt;"web"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;ami&lt;/span&gt;           &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"ami-0c55b159cbfafe1f0"&lt;/span&gt;
  &lt;span class="n"&gt;instance_type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;terraform&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;workspace&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;"t3.large"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"t3.micro"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That conditional is where workspaces start showing their limits, as we will see.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where workspaces shine
&lt;/h2&gt;

&lt;p&gt;Workspaces are excellent for environments that are temporary, numerous, or structurally identical.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Ephemeral environments.&lt;/strong&gt; Spinning up a short-lived environment for a demo or a load test is one command: &lt;code&gt;terraform workspace new loadtest-2026-11&lt;/code&gt;. When you are done, &lt;code&gt;terraform workspace delete&lt;/code&gt; after destroying. No new directories, no new backend configs.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Feature branch environments.&lt;/strong&gt; A developer working on a networking change creates a workspace named after the branch, tests the change in isolation, and tears it down on merge. The state is separate, so experiments cannot corrupt shared environments.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Personal sandboxes.&lt;/strong&gt; Each engineer gets a workspace for learning and experimentation. Cheap, isolated, disposable.&lt;/p&gt;

&lt;p&gt;The common thread: workspaces are great when environments come and go, when they are structurally identical, and when the blast radius of a mistake is small.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where workspaces break down
&lt;/h2&gt;

&lt;p&gt;Production is none of those things. Here is where workspaces hurt.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The wrong-workspace disaster.&lt;/strong&gt; Every workspace shares one backend configuration and one set of code. The only thing standing between you and applying the dev configuration to prod state is the output of &lt;code&gt;terraform workspace show&lt;/code&gt;. Forget to check, and you apply against the wrong state file. The blast radius is the entire environment. This is the classic workspaces failure mode, and it happens to careful engineers, because the safety mechanism is human attention, and human attention fails.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Variable management pain.&lt;/strong&gt; Workspaces share one backend block, which means one backend configuration for all environments. Per-environment differences have to come from somewhere else: tfvars files you must remember to pass, or conditionals on &lt;code&gt;terraform.workspace&lt;/code&gt; scattered through the code. A three-environment setup accumulates ternaries like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="n"&gt;instance_type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;terraform&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;workspace&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;    &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;"t3.large"&lt;/span&gt;  &lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="n"&gt;terraform&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;workspace&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"staging"&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="s2"&gt;"t3.medium"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="s2"&gt;"t3.micro"&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This works for three environments. It does not survive ten. And every conditional is a place where someone adds a new workspace name and forgets to update the logic.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Backend differences are impossible.&lt;/strong&gt; Some teams need different backends per environment: separate AWS accounts, separate state buckets for compliance, different regions. Workspaces cannot do this. One backend block, one bucket, one region. If compliance requires prod state in a separate account from dev state, workspaces are disqualified on arrival.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;CI/CD ambiguity.&lt;/strong&gt; A pipeline applying workspaces must select the right workspace before every operation. That is one more step that can go wrong, and unlike a human, a pipeline will not notice it selected wrong. You end up writing wrapper scripts to make workspace selection safe, which is a sign the abstraction is fighting you.&lt;/p&gt;

&lt;h2&gt;
  
  
  The directory-per-environment pattern
&lt;/h2&gt;

&lt;p&gt;Each environment gets its own directory with its own backend configuration and its own variables:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;envs/
  dev/
    main.tf
    variables.tf
    backend.hcl
    terraform.tfvars
  staging/
    main.tf
    variables.tf
    backend.hcl
    terraform.tfvars
  prod/
    main.tf
    variables.tf
    backend.hcl
    terraform.tfvars
modules/
  app/
    main.tf
    variables.tf
    outputs.tf
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The shared logic lives in &lt;code&gt;modules/app&lt;/code&gt;. Each environment directory is thin: it calls the module with environment-specific inputs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/prod/main.tf&lt;/span&gt;
&lt;span class="n"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"app"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"../../modules/app"&lt;/span&gt;

  &lt;span class="n"&gt;environment&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
  &lt;span class="n"&gt;instance_type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"t3.large"&lt;/span&gt;
  &lt;span class="n"&gt;replica_count&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/prod/backend.hcl&lt;/span&gt;
&lt;span class="n"&gt;bucket&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state-prod"&lt;/span&gt;
&lt;span class="n"&gt;key&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app/terraform.tfstate"&lt;/span&gt;
&lt;span class="n"&gt;region&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
&lt;span class="n"&gt;dynamodb_table&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks-prod"&lt;/span&gt;
&lt;span class="n"&gt;encrypt&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/dev/backend.hcl&lt;/span&gt;
&lt;span class="n"&gt;bucket&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state-dev"&lt;/span&gt;
&lt;span class="n"&gt;key&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app/terraform.tfstate"&lt;/span&gt;
&lt;span class="n"&gt;region&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
&lt;span class="n"&gt;dynamodb_table&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks-dev"&lt;/span&gt;
&lt;span class="n"&gt;encrypt&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Initialize with the backend config for that directory:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; envs/prod
terraform init -backend-config=backend.hcl
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice what this buys you. Prod and dev can use entirely different state buckets, different lock tables, different accounts, different regions. There is no workspace to forget to select, because the directory you are standing in is the environment. &lt;code&gt;terraform apply&lt;/code&gt; in &lt;code&gt;envs/prod&lt;/code&gt; can only ever touch prod state. The safety mechanism is the filesystem, not human attention.&lt;/p&gt;

&lt;p&gt;Variables live in &lt;code&gt;terraform.tfvars&lt;/code&gt; per directory, loaded automatically. No ternaries on workspace names. No remembering to pass &lt;code&gt;-var-file&lt;/code&gt;. Each environment's configuration is explicit and reviewable in a pull request.&lt;/p&gt;

&lt;h2&gt;
  
  
  Head-to-head comparison
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Concern&lt;/th&gt;
&lt;th&gt;Workspaces&lt;/th&gt;
&lt;th&gt;Directory-per-environment&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Safety&lt;/td&gt;
&lt;td&gt;Low. One forgotten &lt;code&gt;workspace select&lt;/code&gt; applies to the wrong environment.&lt;/td&gt;
&lt;td&gt;High. The directory is the environment. Wrong-directory applies are caught by code review of the path.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Clarity&lt;/td&gt;
&lt;td&gt;Medium. Logic branches on &lt;code&gt;terraform.workspace&lt;/code&gt; hide environment differences in conditionals.&lt;/td&gt;
&lt;td&gt;High. Each environment's inputs are explicit in its own files.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CI/CD fit&lt;/td&gt;
&lt;td&gt;Awkward. Pipeline must select workspace before every run. Wrapper scripts common.&lt;/td&gt;
&lt;td&gt;Natural. Pipeline checks out and runs in the environment directory. The path is the selector.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Team scaling&lt;/td&gt;
&lt;td&gt;Poor past a few environments. Conditionals multiply, backend is shared.&lt;/td&gt;
&lt;td&gt;Good. New environment is a new directory. Teams own their directories.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Backend isolation&lt;/td&gt;
&lt;td&gt;Impossible. One backend block for all workspaces.&lt;/td&gt;
&lt;td&gt;Full. Different buckets, accounts, regions per environment.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ephemeral envs&lt;/td&gt;
&lt;td&gt;Excellent. One command to create, one to delete.&lt;/td&gt;
&lt;td&gt;Heavy. New directory plus backend config for something lasting a day.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Variable management&lt;/td&gt;
&lt;td&gt;Painful. Ternaries or external var files you must remember.&lt;/td&gt;
&lt;td&gt;Clean. &lt;code&gt;terraform.tfvars&lt;/code&gt; per directory, auto-loaded.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compliance separation&lt;/td&gt;
&lt;td&gt;Fails. Cannot separate state storage per environment.&lt;/td&gt;
&lt;td&gt;Passes. Prod state can live in its own account and region.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  The recommended hybrid
&lt;/h2&gt;

&lt;p&gt;Most growing teams land here: directories for real environments, workspaces for temporary ones.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;envs/
  dev/
  staging/
  prod/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Dev, staging, and prod each get a directory with isolated backends. These are the environments where a mistake costs money or customers, so they get the safest pattern.&lt;/p&gt;

&lt;p&gt;For ephemeral needs, workspaces inside the dev directory:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; envs/dev
terraform workspace new feature-x
&lt;span class="c"&gt;# test, then destroy and delete the workspace&lt;/span&gt;
terraform workspace &lt;span class="k"&gt;select&lt;/span&gt; default
terraform workspace delete feature-x
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Dev is the right home for experimental workspaces because the blast radius is contained and the backend is already the dev one. Nobody creates experimental workspaces in prod. That rule is worth writing down.&lt;/p&gt;

&lt;p&gt;This hybrid gives you the safety of directories where it matters and the convenience of workspaces where speed matters. It also matches how teams actually grow: you start with workspaces everywhere, you get burned once or twice, and you graduate the important environments to directories.&lt;/p&gt;

&lt;h2&gt;
  
  
  What about Terragrunt?
&lt;/h2&gt;

&lt;p&gt;If the directory pattern looks repetitive, you are noticing the real tradeoff. Each environment directory repeats similar &lt;code&gt;main.tf&lt;/code&gt; calls and backend configs. Terragrunt exists to remove that duplication: one root configuration defines the backend and provider setup once, and each environment directory holds only its inputs.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# terragrunt.hcl at the repo root&lt;/span&gt;
&lt;span class="n"&gt;remote_state&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;backend&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"s3"&lt;/span&gt;
  &lt;span class="n"&gt;config&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;bucket&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state"&lt;/span&gt;
    &lt;span class="n"&gt;key&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"${path_relative_to_include()}/terraform.tfstate"&lt;/span&gt;
    &lt;span class="n"&gt;region&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
    &lt;span class="n"&gt;dynamodb_table&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks"&lt;/span&gt;
    &lt;span class="n"&gt;encrypt&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# envs/prod/terragrunt.hcl&lt;/span&gt;
&lt;span class="n"&gt;include&lt;/span&gt; &lt;span class="s2"&gt;"root"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;path&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;find_in_parent_folders&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;inputs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;environment&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;
  &lt;span class="n"&gt;instance_type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"t3.large"&lt;/span&gt;
  &lt;span class="n"&gt;replica_count&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Terragrunt is a legitimate answer to the duplication problem, and teams running dozens of environments often adopt it. The honest cost: it is another tool to learn, another layer between you and Terraform when something breaks, and debugging a Terragrunt problem requires understanding both tools. For three to five environments, plain directories with small amounts of repetition are simpler and easier for new team members to follow. Consider Terragrunt when the repetition genuinely hurts, not before.&lt;/p&gt;

&lt;h2&gt;
  
  
  Migrating from workspaces to directories
&lt;/h2&gt;

&lt;p&gt;If you are on workspaces today and want to move, the migration is mechanical. Do it one environment at a time, starting with the least critical.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# 1. From the old workspace-based project root, export the state&lt;/span&gt;
terraform workspace &lt;span class="k"&gt;select&lt;/span&gt; staging
terraform state pull &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /tmp/staging-state.json

&lt;span class="c"&gt;# 2. Set up the new directory with its own backend config&lt;/span&gt;
mkdir -p envs/staging
&lt;span class="c"&gt;# (write main.tf calling the shared module, backend.hcl, terraform.tfvars)&lt;/span&gt;

&lt;span class="c"&gt;# 3. Initialize and push the exported state into the new backend&lt;/span&gt;
&lt;span class="nb"&gt;cd&lt;/span&gt; envs/staging
terraform init -backend-config=backend.hcl
terraform state push /tmp/staging-state.json

&lt;span class="c"&gt;# 4. Verify: this must show no changes&lt;/span&gt;
terraform plan
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Step 4 is the whole migration. If the plan is clean, the new directory manages exactly what the workspace managed, and you can delete the old workspace. If the plan shows changes, stop: something differs between the old configuration and the new module call. Fix it before proceeding.&lt;/p&gt;

&lt;p&gt;Keep the old workspace project untouched until every environment is migrated and verified. Do not delete the old backend until the new one has survived at least one full apply cycle. Migrations done in a hurry are how you end up managing the same infrastructure from two places.&lt;/p&gt;

&lt;p&gt;One more note: &lt;code&gt;terraform state push&lt;/code&gt; overwrites whatever is in the target backend. Since you just initialized a fresh backend, it is empty, which is what you want. Never push into a backend that already has state for the same resources.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pre-flight checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Real environments (dev, staging, prod) use directory-per-environment with isolated backends&lt;/li&gt;
&lt;li&gt;[ ] Each environment directory has its own &lt;code&gt;backend.hcl&lt;/code&gt; and &lt;code&gt;terraform.tfvars&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] Shared logic lives in versioned modules, environment directories are thin callers&lt;/li&gt;
&lt;li&gt;[ ] No &lt;code&gt;terraform.workspace&lt;/code&gt; conditionals in code managing real environments&lt;/li&gt;
&lt;li&gt;[ ] Workspaces restricted to ephemeral use inside dev, with a written rule against prod workspaces&lt;/li&gt;
&lt;li&gt;[ ] CI/CD pipelines run in the environment directory, no workspace selection step&lt;/li&gt;
&lt;li&gt;[ ] Migration verified with clean &lt;code&gt;terraform plan&lt;/code&gt; before old workspaces are deleted&lt;/li&gt;
&lt;li&gt;[ ] Old backend retained until the new layout survives a full apply cycle&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;Workspaces and directories are both fine tools used in the right place. Workspaces optimize for speed of creating environments. Directories optimize for safety of operating them. Production deserves safety. Experiments deserve speed. Give each what it needs and stop fighting the tool.&lt;/p&gt;

&lt;p&gt;Next week: secrets in Terraform. State files contain secrets, variables contain secrets, and every team eventually learns this the embarrassing way. Vault integration, dynamic secrets, and keeping sensitive values out of state, logs, and version control.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>devops</category>
      <category>cloud</category>
      <category>aws</category>
    </item>
    <item>
      <title>Compliance packs for regulated APIs: PCI-DSS and SOC 2 as code</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Thu, 05 Nov 2026 22:44:26 +0000</pubDate>
      <link>https://dev.to/manojkagitha/compliance-packs-for-regulated-apis-pci-dss-and-soc-2-as-code-58ak</link>
      <guid>https://dev.to/manojkagitha/compliance-packs-for-regulated-apis-pci-dss-and-soc-2-as-code-58ak</guid>
      <description>&lt;h1&gt;
  
  
  Compliance packs for regulated APIs: PCI-DSS and SOC 2 as code
&lt;/h1&gt;

&lt;p&gt;Every regulated API I have onboarded followed the same pattern. The team&lt;br&gt;
builds the API, wires up auth, ships to staging, and then someone from&lt;br&gt;
security asks for the compliance checklist. The answers live in a thread.&lt;br&gt;
The fixes come back as rework. The API ships late, or it ships with a&lt;br&gt;
waiver nobody remembers signing.&lt;/p&gt;

&lt;p&gt;The fix is not a better checklist. The fix is to stop treating compliance&lt;br&gt;
as a review step and start treating it as config.&lt;/p&gt;
&lt;h2&gt;
  
  
  One line in the spec
&lt;/h2&gt;

&lt;p&gt;In&lt;br&gt;
&lt;a href="https://github.com/kagithamanoj/api-onboarding-kit" rel="noopener noreferrer"&gt;api-onboarding-kit&lt;/a&gt;,&lt;br&gt;
a consumer declares its compliance baseline the same way it declares its&lt;br&gt;
auth method. One line:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;policies&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;compliance:pci-dss&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That line is a bundle, not a flag. It expands into the policies the&lt;br&gt;
baseline actually requires. The PCI-DSS pack expands to JWT auth, a&lt;br&gt;
standard rate limit, and an office IP allowlist. The SOC 2 pack expands&lt;br&gt;
to JWT auth and the standard rate limit. Both packs are owned by the&lt;br&gt;
security team in the policy library, so the team that writes the rules&lt;br&gt;
owns the rules.&lt;/p&gt;

&lt;p&gt;The point is boring on purpose. Nobody has to remember what PCI-DSS&lt;br&gt;
means for an API consumer. The bundle remembers.&lt;/p&gt;
&lt;h2&gt;
  
  
  The validator enforces it
&lt;/h2&gt;

&lt;p&gt;A bundle that only suggests is a checklist with better formatting. So&lt;br&gt;
the validator treats compliance packs as hard rules:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A compliance pack with API key auth fails validation. PCI-DSS and
SOC 2 packs require OAuth2 or mTLS. An API key is not enough, and
the lint error says so in plain language.&lt;/li&gt;
&lt;li&gt;A compliance pack going to prod without an IP allowlist policy gets
flagged. Staging can be loose. Prod cannot.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Here is the full spec for a payment-adjacent consumer, from the repo&lt;br&gt;
examples:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;apiVersion&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;onboarding/v1&lt;/span&gt;
&lt;span class="na"&gt;consumer&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;card-processing&lt;/span&gt;
  &lt;span class="na"&gt;contact&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;payments-platform@example.com&lt;/span&gt;
  &lt;span class="na"&gt;environments&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;staging&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;prod&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
&lt;span class="na"&gt;traffic&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;expectedRps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;150&lt;/span&gt;
  &lt;span class="na"&gt;burstRps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="m"&gt;400&lt;/span&gt;
&lt;span class="na"&gt;auth&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;method&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;mtls&lt;/span&gt;
&lt;span class="na"&gt;policies&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="s"&gt;compliance:pci-dss&lt;/span&gt;
&lt;span class="na"&gt;certificates&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;domains&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;payments.example.com&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
  &lt;span class="na"&gt;autoRenew&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run the linter on that spec and it passes. Change &lt;code&gt;mtls&lt;/code&gt; to &lt;code&gt;apikey&lt;/code&gt;&lt;br&gt;
and it fails before anything is rendered. The bad config never reaches&lt;br&gt;
a gateway. That is the whole idea: catch the compliance miss where the&lt;br&gt;
config is written, not in a review meeting three weeks later.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why a bundle beats a checklist
&lt;/h2&gt;

&lt;p&gt;Three properties matter, and none of them are about the policies&lt;br&gt;
themselves.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Versioned.&lt;/strong&gt; The pack lives in the policy library, in git. When the&lt;br&gt;
security team tightens the baseline, the change is a commit. Every&lt;br&gt;
consumer that picks up the new library version gets the new rules, and&lt;br&gt;
the diff shows exactly what changed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Owned.&lt;/strong&gt; Each pack names an owner. The PCI-DSS and SOC 2 packs belong&lt;br&gt;
to the security team, not to whoever onboarded the last API. If a&lt;br&gt;
consumer team wants an exception, they ask the owner, and the answer&lt;br&gt;
is recorded in the same place as the rule.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reviewed like code.&lt;/strong&gt; A change to a compliance pack goes through the&lt;br&gt;
same pull request review as a change to a gateway policy. The security&lt;br&gt;
team reviews the rule once, in the library, instead of reviewing the&lt;br&gt;
same decision separately for every consumer.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a pack does not do
&lt;/h2&gt;

&lt;p&gt;Honesty matters here. A compliance pack is not certification. PCI-DSS&lt;br&gt;
and SOC 2 each cover far more than gateway config: data handling,&lt;br&gt;
access reviews, incident response, and a long list of controls no&lt;br&gt;
linter can check. The pack covers the API surface only.&lt;/p&gt;

&lt;p&gt;What it does give you is evidence. Every render and promotion is&lt;br&gt;
appended to an audit ledger, and &lt;code&gt;onboard history&lt;/code&gt; shows it. When an&lt;br&gt;
auditor asks which policies a consumer shipped with and when, the&lt;br&gt;
answer is a log, not a memory. That is a small thing, and it is the&lt;br&gt;
thing auditors actually ask for first.&lt;/p&gt;

&lt;p&gt;I wrote a paper on compliance automation for infrastructure back in&lt;br&gt;
2021, and the lesson from that work still holds: the controls that&lt;br&gt;
survive are the ones that run automatically. A control that depends on&lt;br&gt;
someone remembering to check is a control that fails quietly.&lt;/p&gt;

&lt;h2&gt;
  
  
  The takeaway
&lt;/h2&gt;

&lt;p&gt;Regulated APIs do not need more review meetings. They need the baseline&lt;br&gt;
written down once, owned by the team that understands it, and enforced&lt;br&gt;
by the same pipeline that ships the config. One line in the spec, checked&lt;br&gt;
in CI, logged for the audit. The checklist still exists. It just runs&lt;br&gt;
itself now.&lt;/p&gt;

&lt;p&gt;Repo: &lt;a href="https://github.com/kagithamanoj/api-onboarding-kit" rel="noopener noreferrer"&gt;kagithamanoj/api-onboarding-kit&lt;/a&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>security</category>
      <category>compliance</category>
      <category>devops</category>
    </item>
    <item>
      <title>Drift Detection and Remediation: Keeping Production Honest</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Mon, 02 Nov 2026 15:06:25 +0000</pubDate>
      <link>https://dev.to/manojkagitha/drift-detection-and-remediation-keeping-production-honest-di6</link>
      <guid>https://dev.to/manojkagitha/drift-detection-and-remediation-keeping-production-honest-di6</guid>
      <description>&lt;p&gt;Terraform state is a snapshot. Reality moves on. The gap between what Terraform thinks exists and what actually exists is called drift, and every team running Terraform in production deals with it. This post covers how drift happens, how to detect it automatically, how to fix it when you find it, and how to prevent most of it in the first place.&lt;/p&gt;

&lt;h2&gt;
  
  
  What drift actually is
&lt;/h2&gt;

&lt;p&gt;When you run &lt;code&gt;terraform apply&lt;/code&gt;, Terraform writes the real-world state of every resource into the state file. From that moment, the state file starts going stale. Anything that changes infrastructure outside of Terraform creates drift: the state says one thing, the cloud says another.&lt;/p&gt;

&lt;p&gt;A little drift is normal. A lot of drift is dangerous, because the next &lt;code&gt;terraform apply&lt;/code&gt; will try to reconcile the difference, and that reconciliation can surprise you. If someone manually resized a database in the console and your next apply scales it back down, you get an unplanned outage wearing the disguise of a routine deploy.&lt;/p&gt;

&lt;h2&gt;
  
  
  How drift happens
&lt;/h2&gt;

&lt;p&gt;Drift has three usual sources.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Console ClickOps.&lt;/strong&gt; Someone fixes something urgent at 2 AM in the cloud console. The fix works. Nobody writes it down. The Terraform code still describes the old configuration. This is the most common source and the hardest to eliminate, because the console exists for a reason: sometimes you need it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Out-of-band automation.&lt;/strong&gt; A Lambda function that adjusts autoscaling limits. A cron job that rotates something. Another team's pipeline that touches shared resources. These are not people making mistakes. They are systems doing their jobs. But if they modify resources Terraform manages, the result is drift all the same.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Other teams touching shared infrastructure.&lt;/strong&gt; The security team tightens a security group. The networking team updates a route table. Both changes are legitimate. Neither team knew Terraform owned those resources, because nothing told them.&lt;/p&gt;

&lt;p&gt;Not all drift is bad. Sometimes the manual change was the right call and the code was wrong. The problem is never the change itself. The problem is undocumented change that nobody reconciles.&lt;/p&gt;

&lt;h2&gt;
  
  
  Using plan as a drift detector
&lt;/h2&gt;

&lt;p&gt;Every &lt;code&gt;terraform plan&lt;/code&gt; already does drift detection. Before comparing config to state, Terraform refreshes: it queries the real infrastructure and updates its picture. Any difference between the refreshed reality and the state file shows up in the plan output.&lt;/p&gt;

&lt;p&gt;For dedicated drift checks, use refresh-only mode:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform plan &lt;span class="nt"&gt;-refresh-only&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This updates the state to match reality and shows you what changed, without proposing any config-driven modifications. It answers one question: what moved outside of Terraform since the last apply?&lt;/p&gt;

&lt;p&gt;For automation, add &lt;code&gt;-detailed-exitcode&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform plan &lt;span class="nt"&gt;-refresh-only&lt;/span&gt; &lt;span class="nt"&gt;-detailed-exitcode&lt;/span&gt; &lt;span class="nt"&gt;-no-color&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The exit codes are the whole interface: &lt;code&gt;0&lt;/code&gt; means no drift, &lt;code&gt;1&lt;/code&gt; means an error occurred, &lt;code&gt;2&lt;/code&gt; means drift was detected. CI pipelines branch on these codes. That is all you need to build scheduled detection.&lt;/p&gt;

&lt;h2&gt;
  
  
  Scheduled drift detection in CI
&lt;/h2&gt;

&lt;p&gt;Drift comes from outside Terraform, so it will never be caught by your normal pull request pipeline. You need a separate scheduled job whose only purpose is asking: does reality still match the code?&lt;/p&gt;

&lt;p&gt;Here is a nightly workflow using GitHub Actions. It runs a read-only refresh plan against every environment and reports the result:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Nightly Drift Detection&lt;/span&gt;

&lt;span class="na"&gt;on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;schedule&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;cron&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;0&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;6&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;*&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;*&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;*'&lt;/span&gt;  &lt;span class="c1"&gt;# 6 AM UTC daily&lt;/span&gt;
  &lt;span class="na"&gt;workflow_dispatch&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;      &lt;span class="c1"&gt;# allow manual runs too&lt;/span&gt;

&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;
  &lt;span class="na"&gt;id-token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;        &lt;span class="c1"&gt;# for OIDC auth to cloud&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;drift-check&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;strategy&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;fail-fast&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
      &lt;span class="na"&gt;matrix&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;dev&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;staging&lt;/span&gt;&lt;span class="pi"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;prod&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v4&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;hashicorp/setup-terraform@v3&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;terraform_version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;1.9.8&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Configure cloud credentials (read-only role)&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;aws-actions/configure-aws-credentials@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;role-to-assume&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;arn:aws:iam::123456789012:role/terraform-drift-reader&lt;/span&gt;
          &lt;span class="na"&gt;aws-region&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;us-east-1&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Terraform init&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;envs/${{ matrix.environment }}&lt;/span&gt;
        &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -input=false&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Refresh-only plan&lt;/span&gt;
        &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;drift&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;envs/${{ matrix.environment }}&lt;/span&gt;
        &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;|&lt;/span&gt;
          &lt;span class="s"&gt;set +e&lt;/span&gt;
          &lt;span class="s"&gt;terraform plan -refresh-only -detailed-exitcode -no-color -input=false \&lt;/span&gt;
            &lt;span class="s"&gt;&amp;gt; drift-output.txt 2&amp;gt;&amp;amp;1&lt;/span&gt;
          &lt;span class="s"&gt;echo "exit_code=$?" &amp;gt;&amp;gt; "$GITHUB_OUTPUT"&lt;/span&gt;
          &lt;span class="s"&gt;set -e&lt;/span&gt;
          &lt;span class="s"&gt;cat drift-output.txt&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Upload drift report&lt;/span&gt;
        &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;steps.drift.outputs.exit_code == '2'&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/upload-artifact@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;drift-report-${{ matrix.environment }}&lt;/span&gt;
          &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;envs/${{ matrix.environment }}/drift-output.txt&lt;/span&gt;

      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Notify Slack&lt;/span&gt;
        &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;steps.drift.outputs.exit_code == '2'&lt;/span&gt;
        &lt;span class="na"&gt;env&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;SLACK_WEBHOOK_URL&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.DRIFT_SLACK_WEBHOOK }}&lt;/span&gt;
        &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;|&lt;/span&gt;
          &lt;span class="s"&gt;curl -s -X POST "$SLACK_WEBHOOK_URL" \&lt;/span&gt;
            &lt;span class="s"&gt;-H 'Content-Type: application/json' \&lt;/span&gt;
            &lt;span class="s"&gt;-d "{\"text\":\":warning: Drift detected in *${{ matrix.environment }}*. See the workflow run for the full report.\"}"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few design decisions worth noting:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Read-only credentials.&lt;/strong&gt; The drift job only needs to read infrastructure and state. Give it a dedicated IAM role with read permissions. If the job can only read, it cannot make anything worse, which matters when it runs unattended at 6 AM.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Matrix over environments.&lt;/strong&gt; One job definition, every environment checked. Prod drift and dev drift both get reported. You decide which ones page someone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Artifacts, not just logs.&lt;/strong&gt; When drift is found, the full plan output is saved as a workflow artifact. The person investigating gets the complete report, not a Slack message saying "something changed."&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Never auto-remediate from this job.&lt;/strong&gt; It is tempting to follow detection with an automatic &lt;code&gt;terraform apply&lt;/code&gt;. Do not. Remediation is a judgment call (see below). The job detects and reports. A human decides.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reading a drift report
&lt;/h2&gt;

&lt;p&gt;Refresh-only output has a distinctive header. Learn to recognize it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the
last "terraform apply":

  # aws_instance.web has changed
  ~ instance_type = "t3.medium" -&amp;gt; "t3.large"

  # aws_security_group.app has changed
  ~ ingress = [
      + {
          + cidr_blocks = ["10.0.0.0/8"]
          + from_port   = 443
          + to_port     = 443
          + protocol    = "tcp"
        },
      ]
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Read it like this: the left side is what Terraform last recorded, the right side is what exists now. Someone resized the instance from medium to large and added an ingress rule.&lt;/p&gt;

&lt;p&gt;The skill is telling meaningful drift from noise. Some attributes always show diffs because the provider computes them fresh on every refresh (timestamps, generated IDs, default values the API fills in). If you see the same handful of attributes flagging every night with no real change, that is provider noise, not drift. Note which ones they are so the team stops investigating them. Real drift is a value someone deliberately changed: sizes, counts, rules, policies.&lt;/p&gt;

&lt;p&gt;For machine-readable reports, &lt;code&gt;terraform show -json&lt;/code&gt; on a saved plan file gives you structured output you can feed into ticketing or dashboards. Most teams do not need this until drift volume gets high. Start with the human-readable report.&lt;/p&gt;

&lt;h2&gt;
  
  
  Remediation: three options
&lt;/h2&gt;

&lt;p&gt;Finding drift is the easy part. Deciding what to do about it is the real work. There are three options, and the right one depends on whether the manual change was correct.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 1: Apply to converge.&lt;/strong&gt; If the manual change was wrong or temporary, run a normal &lt;code&gt;terraform apply&lt;/code&gt;. Terraform reverts reality to match the code. This is the right call for accidental console edits and for emergency fixes whose emergency is over. Announce it first: reverting someone's change without warning creates a different kind of incident.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 2: Import the unmanaged resource.&lt;/strong&gt; If someone created something entirely outside Terraform that should be managed going forward, bring it into state instead of destroying it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# Write the resource block first, matching reality as closely as you can&lt;/span&gt;
&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket"&lt;/span&gt; &lt;span class="s2"&gt;"logs"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-manual-logs-bucket"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform import aws_s3_bucket.logs myorg-manual-logs-bucket
terraform plan
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The plan after import shows you every attribute where your config differs from reality. Adjust the config until the plan is clean. The resource is now managed, and the next apply changes nothing. Import is for things that should have been in code all along.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 3: Update the code to accept the change.&lt;/strong&gt; Sometimes the console change was right and the code was wrong. The instance needed to be larger. The firewall rule was genuinely missing. In that case, update the Terraform configuration to describe the new reality, then apply. The apply is a no-op, the drift is resolved, and the change is now documented in version control where it belongs.&lt;/p&gt;

&lt;p&gt;The decision framework is one question: was the manual change correct? If yes, codify it (option 2 or 3). If no, revert it (option 1). If nobody knows, find out before touching anything. Reverting a change you do not understand is how you turn drift into an outage.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preventing drift with guardrails
&lt;/h2&gt;

&lt;p&gt;Detection and remediation are necessary. Prevention is better. The most effective guardrail is also the simplest: most humans should not be able to change production infrastructure directly.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;IAM scoping.&lt;/strong&gt; Engineers get read access to production. The CI/CD pipeline role gets write access. This single change eliminates the majority of accidental drift, because the console becomes a viewing tool rather than an editing tool for everyday work. Break-glass admin access still exists for real emergencies, with the understanding that anything done through it gets codified afterward.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AWS Service Control Policies.&lt;/strong&gt; For destructive actions, add an organization-level backstop that denies them to everyone except the pipeline role:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_organizations_policy"&lt;/span&gt; &lt;span class="s2"&gt;"prod_guardrail"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"deny-prod-changes-outside-pipeline"&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"SERVICE_CONTROL_POLICY"&lt;/span&gt;

  &lt;span class="nx"&gt;content&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;jsonencode&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;Version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"2012-10-17"&lt;/span&gt;
    &lt;span class="nx"&gt;Statement&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nx"&gt;Sid&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"DenyDestructiveActionsOutsidePipeline"&lt;/span&gt;
        &lt;span class="nx"&gt;Effect&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Deny"&lt;/span&gt;
        &lt;span class="nx"&gt;Action&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
          &lt;span class="s2"&gt;"ec2:TerminateInstances"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="s2"&gt;"rds:DeleteDBInstance"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="s2"&gt;"s3:DeleteBucket"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;]&lt;/span&gt;
        &lt;span class="nx"&gt;Resource&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"*"&lt;/span&gt;
        &lt;span class="nx"&gt;Condition&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="nx"&gt;StringNotEquals&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="s2"&gt;"aws:PrincipalArn"&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"arn:aws:iam::123456789012:role/terraform-pipeline"&lt;/span&gt;
          &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;})&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;SCPs cannot distinguish Terraform from the console. They distinguish principals. The pattern is: only the pipeline role may perform these actions, everyone else is denied at the organization level. Be honest about the tradeoff: this also blocks legitimate emergency work, which is why break-glass procedures must exist alongside it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Azure equivalents.&lt;/strong&gt; Resource locks (&lt;code&gt;CanNotDelete&lt;/code&gt;) on critical scopes, Azure Policy deny assignments for specific actions, and RBAC scoped so humans hold Reader on production while the pipeline service principal holds Contributor. Note the same tradeoff as SCPs: locks block Terraform too, so the pipeline must manage lock lifecycle or you scope locks to the resources where deletion would be catastrophic.&lt;/p&gt;

&lt;p&gt;Guardrails do not replace the drift job. They reduce the volume. Run both.&lt;/p&gt;

&lt;h2&gt;
  
  
  Alerting without the noise
&lt;/h2&gt;

&lt;p&gt;A drift alert that fires constantly gets ignored, and an ignored alert is worse than no alert because it creates false confidence. A few rules:&lt;/p&gt;

&lt;p&gt;Alert on prod immediately, every time. Aggregate dev and staging into a daily digest. Nobody needs a 3 AM page for dev drift.&lt;/p&gt;

&lt;p&gt;Include the environment, a link to the workflow run, and the artifact with the full report. "Drift detected in prod" with no link is an alert that creates work instead of directing it.&lt;/p&gt;

&lt;p&gt;Track who owns remediation. The team that owns the Terraform code owns the drift in it. If the drift came from another team's automation, the alert should route to both teams, because the fix might be a conversation, not a command.&lt;/p&gt;

&lt;h2&gt;
  
  
  The cultural piece
&lt;/h2&gt;

&lt;p&gt;Tools catch drift. Culture prevents it. The goal is a team where console changes to Terraform-managed infrastructure feel wrong, not because anyone gets punished, but because everyone has seen what undocumented changes cost.&lt;/p&gt;

&lt;p&gt;Blameless matters here. If someone fixes prod in the console at 2 AM and the response is blame, the next person will fix it in the console and not tell anyone. If the response is "good catch, let's get it into code today," people report their own drift.&lt;/p&gt;

&lt;p&gt;Have an explicit break-glass procedure: who can do it, how it gets recorded, and who codifies it afterward. If the only way to fix production in an emergency is the console, that is a process gap, not a people problem. Close the gap and the culture follows.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pre-flight checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Nightly (or daily) refresh-only plan job running against every environment&lt;/li&gt;
&lt;li&gt;[ ] Drift job uses dedicated read-only credentials&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;-detailed-exitcode&lt;/code&gt; drives branching: 0 clean, 1 error, 2 drift&lt;/li&gt;
&lt;li&gt;[ ] Drift reports saved as artifacts, linked from alerts&lt;/li&gt;
&lt;li&gt;[ ] Prod drift alerts immediately; non-prod aggregates into a digest&lt;/li&gt;
&lt;li&gt;[ ] Team knows the three remediation options and when each applies&lt;/li&gt;
&lt;li&gt;[ ] IAM scoped so humans read prod and only the pipeline writes it&lt;/li&gt;
&lt;li&gt;[ ] Guardrails (SCPs, Policy, locks) on destructive actions, with break-glass documented&lt;/li&gt;
&lt;li&gt;[ ] Break-glass procedure written down: who, how it is recorded, who codifies after&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;Drift is not a sign your team is careless. It is a sign your infrastructure is alive: people and systems touch it for good reasons. The mature response is not zero drift. It is detected drift, understood drift, and remediated drift, with guardrails shrinking the volume over time.&lt;/p&gt;

&lt;p&gt;Next week: Terraform workspaces versus directory-per-environment. Both organize multiple environments, both have sharp edges, and picking the wrong one for your team size creates the kind of mess that takes a quarter to unwind.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>devops</category>
      <category>cloud</category>
      <category>sre</category>
    </item>
    <item>
      <title>Terraform in CI/CD: Plan/Apply Gates with GitHub Actions</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Mon, 26 Oct 2026 14:07:54 +0000</pubDate>
      <link>https://dev.to/manojkagitha/terraform-in-cicd-planapply-gates-with-github-actions-1onn</link>
      <guid>https://dev.to/manojkagitha/terraform-in-cicd-planapply-gates-with-github-actions-1onn</guid>
      <description>&lt;p&gt;Versioned modules mean nothing if engineers still run apply from their laptops. Laptop applies are unreviewed, unlogged, and unrepeatable. The fix is a pipeline: every change goes through plan on pull request, review, then apply from CI with short-lived credentials. This post builds that pipeline on GitHub Actions from scratch.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why CI/CD runs apply
&lt;/h2&gt;

&lt;p&gt;Four reasons, in order of how much pain each one prevents.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Review.&lt;/strong&gt; A plan posted as a PR comment lets reviewers see exactly what will change before it changes. No more "I applied and something broke, let me check what I did."&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Audit trail.&lt;/strong&gt; Every apply is tied to a commit, a PR, and a GitHub Actions run. When something breaks at 2 AM, you know exactly which change did it and who approved it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;No credential sprawl.&lt;/strong&gt; Engineers do not need cloud credentials on their laptops. The pipeline assumes a role with OIDC. Credentials live for the duration of the run, then vanish.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Repeatability.&lt;/strong&gt; The same code, the same Terraform version, the same provider versions, every time. "Works on my machine" stops being a sentence anyone says.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pipeline stages
&lt;/h2&gt;

&lt;p&gt;A solid Terraform pipeline has four stages. Each one gates the next.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;fmt.&lt;/strong&gt; &lt;code&gt;terraform fmt -check&lt;/code&gt; fails the run if any file is misformatted. Cheap, fast, non-negotiable. Formatting arguments are not worth human review time.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;validate.&lt;/strong&gt; &lt;code&gt;terraform init -backend=false&lt;/code&gt; followed by &lt;code&gt;terraform validate&lt;/code&gt;. Catches syntax errors and invalid references without touching state or cloud APIs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;plan.&lt;/strong&gt; Full init against the real backend, then &lt;code&gt;terraform plan -out=tfplan&lt;/code&gt;. The plan file is saved as an artifact. On pull requests, the human-readable plan is posted as a PR comment.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;apply.&lt;/strong&gt; Only on merge to main. Downloads the exact plan artifact from the plan stage and applies it. Never re-plans at apply time. You apply what was reviewed, not something subtly different.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Linting with &lt;code&gt;tflint&lt;/code&gt; slots in between validate and plan. Security scanning with &lt;code&gt;tfsec&lt;/code&gt; or Checkov goes there too.&lt;/p&gt;

&lt;h2&gt;
  
  
  The plan artifact pattern
&lt;/h2&gt;

&lt;p&gt;The critical detail: apply consumes the saved plan file, not a fresh plan. Here is why it matters.&lt;/p&gt;

&lt;p&gt;Between plan and apply, time passes. A reviewer takes an hour. Someone merges another PR. The cloud state drifts. If apply re-plans, it applies something nobody reviewed. By saving the plan with &lt;code&gt;-out=tfplan&lt;/code&gt; and applying that exact file, the reviewed change is the applied change. If the world moved underneath, the apply fails loudly instead of silently doing something unexpected. That failure is correct behavior.&lt;/p&gt;

&lt;h2&gt;
  
  
  Posting plan output as a PR comment
&lt;/h2&gt;

&lt;p&gt;A plan artifact is a binary file. Reviewers cannot read it on GitHub. So the pipeline also renders the plan as text and posts it as a comment:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Render plan&lt;/span&gt;
  &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform show -no-color tfplan &amp;gt; tfplan.txt&lt;/span&gt;
  &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;

&lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Post plan comment&lt;/span&gt;
  &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;github.event_name == 'pull_request'&lt;/span&gt;
  &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/github-script@v7&lt;/span&gt;
  &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;script&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;|&lt;/span&gt;
      &lt;span class="s"&gt;const fs = require('fs');&lt;/span&gt;
      &lt;span class="s"&gt;const plan = fs.readFileSync(process.env.WORKING_DIR + '/tfplan.txt', 'utf8');&lt;/span&gt;
      &lt;span class="s"&gt;const body = `## Terraform Plan\n\n\`\`\`\n${plan.substring(0, 60000)}\n\`\`\``;&lt;/span&gt;
      &lt;span class="s"&gt;github.rest.issues.createComment({&lt;/span&gt;
        &lt;span class="s"&gt;issue_number: context.issue.number,&lt;/span&gt;
        &lt;span class="s"&gt;owner: context.repo.owner,&lt;/span&gt;
        &lt;span class="s"&gt;repo: context.repo.repo,&lt;/span&gt;
        &lt;span class="s"&gt;body: body&lt;/span&gt;
      &lt;span class="s"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Long plans get truncated at 60,000 characters, which fits GitHub's comment limits. For most changes, the full plan fits. Reviewers see adds, changes, and destroys inline, right where they already review code.&lt;/p&gt;

&lt;h2&gt;
  
  
  OIDC auth: no stored secrets
&lt;/h2&gt;

&lt;p&gt;The old way: a long-lived AWS access key or Azure service principal secret sitting in GitHub Secrets, rotating never, shared by everyone. The new way: OpenID Connect. GitHub mints a short-lived token per run. The cloud trusts GitHub's identity provider and hands back temporary credentials scoped to one IAM role.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AWS setup.&lt;/strong&gt; Create an IAM role with a trust policy that allows GitHub's OIDC provider to assume it, scoped to your repo:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"Version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"2012-10-17"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"Statement"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Effect"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Allow"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Principal"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"Federated"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Action"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"sts:AssumeRoleWithWebIdentity"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"Condition"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"StringEquals"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"token.actions.githubusercontent.com:aud"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"sts.amazonaws.com"&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"StringLike"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"token.actions.githubusercontent.com:sub"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"repo:myorg/infra:*"&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}]&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;sub&lt;/code&gt; condition restricts assumption to your infrastructure repo. Tighten it further with branch conditions if you want: only &lt;code&gt;main&lt;/code&gt; can assume the production role, while any branch can assume the dev role.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Azure setup.&lt;/strong&gt; Register an app, add a federated credential trusting &lt;code&gt;repo:myorg/infra:ref:refs/heads/main&lt;/code&gt;, and log in with &lt;code&gt;azure/login@v2&lt;/code&gt; using client ID, tenant ID, and subscription ID. No secret needed.&lt;/p&gt;

&lt;p&gt;The workflow needs one permission block:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;id-token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;
  &lt;span class="na"&gt;pull-requests&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;id-token: write&lt;/code&gt; is what lets the run mint the OIDC token. Without it, the credential step fails with an unhelpful error.&lt;/p&gt;

&lt;h2&gt;
  
  
  Apply gates
&lt;/h2&gt;

&lt;p&gt;Not every merge should auto-apply to production. GitHub Environments give you gates.&lt;/p&gt;

&lt;p&gt;Define an environment per target: &lt;code&gt;dev&lt;/code&gt;, &lt;code&gt;staging&lt;/code&gt;, &lt;code&gt;production&lt;/code&gt;. Attach rules:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;dev:&lt;/strong&gt; auto-apply on merge. Fast feedback, low blast radius.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;staging:&lt;/strong&gt; apply on merge, but the job waits for no one. Actually, make staging auto-apply too. Staging exists to catch what dev missed, and manual gates on staging just slow the signal.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;production:&lt;/strong&gt; required reviewers. The apply job pauses until a designated approver clicks approve. The approver sees the plan diff from the PR. This is the gate that matters.
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;apply-prod&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
  &lt;span class="na"&gt;needs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;plan-prod&lt;/span&gt;
  &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;github.ref == 'refs/heads/main'&lt;/span&gt;
  &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;production&lt;/span&gt;
  &lt;span class="na"&gt;concurrency&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;group&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform-prod&lt;/span&gt;
    &lt;span class="na"&gt;cancel-in-progress&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;environment: production&lt;/code&gt; line is what triggers the approval gate. Configure the required reviewers in the repo settings under Environments.&lt;/p&gt;

&lt;h2&gt;
  
  
  Full working workflow
&lt;/h2&gt;

&lt;p&gt;Here is a complete workflow for one environment. It runs fmt and validate on every PR, plans and comments, and applies only on merge to main behind the production gate.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Terraform Prod&lt;/span&gt;

&lt;span class="na"&gt;on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;push&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;branches&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="nv"&gt;main&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
    &lt;span class="na"&gt;paths&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;envs/prod/**'&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;
  &lt;span class="na"&gt;pull_request&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;paths&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'&lt;/span&gt;&lt;span class="s"&gt;envs/prod/**'&lt;/span&gt;&lt;span class="pi"&gt;]&lt;/span&gt;

&lt;span class="na"&gt;permissions&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;id-token&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;
  &lt;span class="na"&gt;contents&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;read&lt;/span&gt;
  &lt;span class="na"&gt;pull-requests&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;write&lt;/span&gt;

&lt;span class="na"&gt;env&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;TF_VERSION&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;1.9.0"&lt;/span&gt;
  &lt;span class="na"&gt;WORKING_DIR&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;envs/prod&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;fmt&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v4&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;hashicorp/setup-terraform@v3&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;terraform_version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.TF_VERSION }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform fmt -check -recursive&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;

  &lt;span class="na"&gt;validate&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;needs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;fmt&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v4&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;hashicorp/setup-terraform@v3&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;terraform_version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.TF_VERSION }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -backend=false&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform validate&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;

  &lt;span class="na"&gt;plan&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;needs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;validate&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v4&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;hashicorp/setup-terraform@v3&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;terraform_version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.TF_VERSION }}&lt;/span&gt;
          &lt;span class="na"&gt;terraform_wrapper&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Configure AWS credentials&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;aws-actions/configure-aws-credentials@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;role-to-assume&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;arn:aws:iam::123456789012:role/terraform-ci-prod&lt;/span&gt;
          &lt;span class="na"&gt;aws-region&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;us-east-1&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -input=false&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform plan -out=tfplan -input=false&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform show -no-color tfplan &amp;gt; tfplan.txt&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/upload-artifact@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;tfplan-prod&lt;/span&gt;
          &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}/tfplan&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Post plan comment&lt;/span&gt;
        &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;github.event_name == 'pull_request'&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/github-script@v7&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;script&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="pi"&gt;|&lt;/span&gt;
            &lt;span class="s"&gt;const fs = require('fs');&lt;/span&gt;
            &lt;span class="s"&gt;const plan = fs.readFileSync(process.env.WORKING_DIR + '/tfplan.txt', 'utf8');&lt;/span&gt;
            &lt;span class="s"&gt;const body = `## Terraform Plan (prod)\n\n\`\`\`\n${plan.substring(0, 60000)}\n\`\`\``;&lt;/span&gt;
            &lt;span class="s"&gt;github.rest.issues.createComment({&lt;/span&gt;
              &lt;span class="s"&gt;issue_number: context.issue.number,&lt;/span&gt;
              &lt;span class="s"&gt;owner: context.repo.owner,&lt;/span&gt;
              &lt;span class="s"&gt;repo: context.repo.repo,&lt;/span&gt;
              &lt;span class="s"&gt;body: body&lt;/span&gt;
            &lt;span class="s"&gt;});&lt;/span&gt;

  &lt;span class="na"&gt;apply&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;needs&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;plan&lt;/span&gt;
    &lt;span class="na"&gt;if&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;github.ref == 'refs/heads/main' &amp;amp;&amp;amp; github.event_name == 'push'&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;production&lt;/span&gt;
    &lt;span class="na"&gt;concurrency&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;group&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform-prod&lt;/span&gt;
      &lt;span class="na"&gt;cancel-in-progress&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v4&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;hashicorp/setup-terraform@v3&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;terraform_version&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.TF_VERSION }}&lt;/span&gt;
          &lt;span class="na"&gt;terraform_wrapper&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Configure AWS credentials&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;aws-actions/configure-aws-credentials@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;role-to-assume&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;arn:aws:iam::123456789012:role/terraform-ci-prod&lt;/span&gt;
          &lt;span class="na"&gt;aws-region&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;us-east-1&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/download-artifact@v4&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;tfplan-prod&lt;/span&gt;
          &lt;span class="na"&gt;path&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform init -input=false&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
      &lt;span class="pi"&gt;-&lt;/span&gt; &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform apply -input=false tfplan&lt;/span&gt;
        &lt;span class="na"&gt;working-directory&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ env.WORKING_DIR }}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details worth calling out. First, &lt;code&gt;terraform_wrapper: false&lt;/code&gt; on the setup-terraform action. The wrapper captures output for PR comments in the action's own way, which conflicts with the manual plan-comment pattern. Disable it when you post comments yourself.&lt;/p&gt;

&lt;p&gt;Second, the apply job downloads the plan artifact and applies that file. It does not run plan again. Reviewed plan in, applied plan out.&lt;/p&gt;

&lt;h2&gt;
  
  
  Multi-environment promotion
&lt;/h2&gt;

&lt;p&gt;One repo, one workflow per environment, or one workflow with a matrix. The promotion flow:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Merge to main. Dev applies automatically. No gate, fast feedback.&lt;/li&gt;
&lt;li&gt;Staging applies automatically after dev succeeds. Use &lt;code&gt;needs: [apply-dev]&lt;/code&gt; to serialize.&lt;/li&gt;
&lt;li&gt;Production waits. The &lt;code&gt;environment: production&lt;/code&gt; gate pauses for a human approver.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Sequential, not parallel. Prod never applies before staging succeeds. If staging apply fails, prod never starts, and the team fixes forward instead of debating whether prod is safe.&lt;/p&gt;

&lt;p&gt;Keep one workflow file per environment rather than one mega-workflow with conditionals. &lt;code&gt;terraform-prod.yml&lt;/code&gt;, &lt;code&gt;terraform-staging.yml&lt;/code&gt;, &lt;code&gt;terraform-dev.yml&lt;/code&gt;. Each is readable on its own. Shared steps go into composite actions or reusable workflows if duplication bothers you, but duplication across three files is cheaper than one clever file nobody understands.&lt;/p&gt;

&lt;h2&gt;
  
  
  Concurrency groups: serialize applies per environment
&lt;/h2&gt;

&lt;p&gt;Two merges in quick succession can queue two applies against the same state. State locking makes the second one wait or fail, but it is cleaner to serialize at the workflow level:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;concurrency&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;group&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;terraform-prod&lt;/span&gt;
  &lt;span class="na"&gt;cancel-in-progress&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;cancel-in-progress: false&lt;/code&gt; is the important part. You want the second run to wait, not to cancel the first run mid-apply. Cancelling mid-apply is how you get tainted resources and half-created infrastructure.&lt;/p&gt;

&lt;p&gt;One concurrency group per environment. Dev, staging, and prod apply independently. Two environments never block each other.&lt;/p&gt;

&lt;h2&gt;
  
  
  State locking and CI
&lt;/h2&gt;

&lt;p&gt;State locking still applies in CI. If a run crashes mid-apply, the lock can stick. The next run fails with a lock error. The fix is the same as locally: &lt;code&gt;terraform force-unlock&lt;/code&gt;, but run it deliberately, not in the pipeline.&lt;/p&gt;

&lt;p&gt;Do not add auto-unlock to the pipeline. An automatic force-unlock can release a lock held by a genuinely running apply, recreating the race condition locking exists to prevent. When CI reports a stuck lock, a human checks that nothing is actually applying, runs force-unlock once, and re-runs the workflow.&lt;/p&gt;

&lt;h2&gt;
  
  
  When apply fails mid-run
&lt;/h2&gt;

&lt;p&gt;It happens. A network blip, a cloud API quota, a resource that fails to create. Terraform marks the failed resource as tainted. The next apply destroys and recreates it. Usually that is the right behavior.&lt;/p&gt;

&lt;p&gt;When it is not, for example a database that took twenty minutes to provision and failed on a tagging step, you have options:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;terraform apply -replace="aws_db_instance.main"&lt;/code&gt; recreates one specific resource on the next run, without waiting for a failure to taint it.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;terraform state rm&lt;/code&gt; followed by &lt;code&gt;terraform import&lt;/code&gt; detaches a resource from management when you need to stop Terraform from touching it while you fix things by hand. Use sparingly.&lt;/li&gt;
&lt;li&gt;As a last resort, &lt;code&gt;-target&lt;/code&gt; applies to a subset of resources. It bypasses dependency ordering guarantees, so treat it as emergency surgery, not routine practice. Every &lt;code&gt;-target&lt;/code&gt; apply should be followed by a full, untargeted plan to confirm the state is coherent.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;After any recovery, run a full plan. If the plan is empty, you are back to a clean state. If it is not, keep going until it is.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] fmt, validate, plan, apply as separate gated stages&lt;/li&gt;
&lt;li&gt;[ ] Plan saved with &lt;code&gt;-out=tfplan&lt;/code&gt;, applied from the artifact. No re-planning at apply time.&lt;/li&gt;
&lt;li&gt;[ ] Plan output posted as a PR comment for review&lt;/li&gt;
&lt;li&gt;[ ] OIDC auth configured. No long-lived credentials in GitHub Secrets.&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;id-token: write&lt;/code&gt; permission set on the workflow&lt;/li&gt;
&lt;li&gt;[ ] Production apply behind a GitHub Environment approval gate&lt;/li&gt;
&lt;li&gt;[ ] Concurrency group per environment, &lt;code&gt;cancel-in-progress: false&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] Promotion order enforced: dev, then staging, then prod&lt;/li&gt;
&lt;li&gt;[ ] No auto-unlock in the pipeline. Stuck locks get human attention.&lt;/li&gt;
&lt;li&gt;[ ] Terraform, provider, and module versions pinned (see article 2)&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Next
&lt;/h2&gt;

&lt;p&gt;The pipeline applies cleanly and every change is reviewed. But infrastructure does not stay as Terraform left it. Someone tweaks a setting in the console. A cloud provider changes a default. The next plan shows diffs nobody made.&lt;/p&gt;

&lt;p&gt;Next article: drift detection and remediation. Scheduled scans, telling real drift from cosmetic noise, and the workflow for bringing reality back in line with code.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>devops</category>
      <category>github</category>
      <category>automation</category>
    </item>
    <item>
      <title>Who Is Paying for This? Token Metering at the LLM Gateway</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Fri, 23 Oct 2026 14:52:27 +0000</pubDate>
      <link>https://dev.to/manojkagitha/who-is-paying-for-this-token-metering-at-the-llm-gateway-3jlp</link>
      <guid>https://dev.to/manojkagitha/who-is-paying-for-this-token-metering-at-the-llm-gateway-3jlp</guid>
      <description>&lt;p&gt;Once you put a large language model behind a company API gateway, someone asks a simple question.&lt;/p&gt;

&lt;p&gt;Who is paying for this?&lt;/p&gt;

&lt;p&gt;The model bill arrives as one number. Finance sees one number. Every team in the company sees one endpoint. Nobody can tell you which team burned forty percent of the budget, which use case is growing, or which experiment someone forgot to shut off six weeks ago. That gap between one bill and one endpoint is where metering lives.&lt;/p&gt;

&lt;p&gt;We built metering into our LLM gateway before we scaled usage, and it changed how teams behaved. Here is what we learned.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why LLM metering is not like API metering
&lt;/h2&gt;

&lt;p&gt;With a normal REST API, metering is easy. One request costs one request. You count requests per subscription key, and you are done.&lt;/p&gt;

&lt;p&gt;LLM calls do not work that way. One request to a chat endpoint can cost five tokens or five thousand. A prompt injection test script someone ran in a loop overnight can spend more than an entire product team's monthly budget in eight hours. If you count requests, you learn nothing. The unit of cost is the token, and the token count lives in the response, not the request.&lt;/p&gt;

&lt;p&gt;That detail shapes everything. Your metering code has to read the response body, extract the usage block, and attribute it before the data is gone.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"usage"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"prompt_tokens"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1240&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"completion_tokens"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;312&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"total_tokens"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;1552&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Azure OpenAI returns this on every response. If you do not capture it at the gateway, you have to reconstruct it later from logs, and that is a losing fight.&lt;/p&gt;

&lt;h2&gt;
  
  
  Capture it at the gateway, not in the app
&lt;/h2&gt;

&lt;p&gt;Every team wanted to do metering in their own application code. We said no. The gateway is the one layer every call passes through, regardless of language, framework, or team. A metering implementation that depends on each team instrumenting their own service is an implementation that covers sixty percent of traffic on a good month.&lt;/p&gt;

&lt;p&gt;We put a policy on the gateway's inbound path to stamp each request with metadata: the subscription the key belongs to, the product, the environment. On the outbound path, another policy parses the response, pulls the token counts, and ships an event to our analytics pipeline. The policy does not touch the request or response bodies in ways the caller can see. It observes and reports.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight xml"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;policies&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;outbound&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;choose&amp;gt;&lt;/span&gt;
            &lt;span class="nt"&gt;&amp;lt;when&lt;/span&gt; &lt;span class="na"&gt;condition=&lt;/span&gt;&lt;span class="s"&gt;"@(context.Response.StatusCode == 200)"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
                &lt;span class="nt"&gt;&amp;lt;set-body&amp;gt;&lt;/span&gt;@{
                    // parse the usage block and forward a metering event
                    // key: subscription id, product, environment, model
                    // value: prompt_tokens, completion_tokens, latency
                }&lt;span class="nt"&gt;&amp;lt;/set-body&amp;gt;&lt;/span&gt;
            &lt;span class="nt"&gt;&amp;lt;/when&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;/choose&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;/outbound&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/policies&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is pseudo-code, not a real policy file, because every gateway has its own syntax. The shape matters more than the syntax: stamp metadata on the way in, extract cost on the way out, send it somewhere durable.&lt;/p&gt;

&lt;h2&gt;
  
  
  Attribute everything, including the failures
&lt;/h2&gt;

&lt;p&gt;The first version of our metering only counted successful calls. That lasted about two weeks. Someone ran a batch job against a deprecated model deployment that returned 400s all day. The calls were cheap individually, but there were hundreds of thousands of them, and the model provider still charged for the input tokens on each failed request.&lt;/p&gt;

&lt;p&gt;Failed requests still consume input tokens. Rate-limited requests still consume them. Requests that hit a content filter still consume them. If you only meter the 200s, your bill and your dashboard will disagree, and finance will believe the bill.&lt;/p&gt;

&lt;p&gt;Our outbound policy records every response code. Failures get their own bucket so teams can see them separately, but they are not excluded from the total. The first time a team saw how much they were spending on 400s, they fixed their client code that afternoon.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give teams their own numbers, not the whole company
&lt;/h2&gt;

&lt;p&gt;A company-wide dashboard that says the LLM bill is fifty thousand dollars a month helps nobody. A dashboard that says your team spent nine thousand, up forty percent from last month, on a specific model, changes behavior overnight.&lt;/p&gt;

&lt;p&gt;We publish per-team views: tokens and estimated cost by team, by model, by day. The estimated cost part matters. Tokens are abstract. Dollars are not. We maintain a small price table per model and multiply. The estimate is not perfect, and we say that on the dashboard. It is close enough to drive decisions.&lt;/p&gt;

&lt;p&gt;The behavioral change was immediate. Teams started batching requests. They cached repeated prompts. One team switched a summarization job from a large model to a smaller one after seeing the per-run cost. None of that happened when the bill was a single line item.&lt;/p&gt;

&lt;h2&gt;
  
  
  Budgets need teeth, but start with visibility
&lt;/h2&gt;

&lt;p&gt;Once teams can see their spend, the next question is limits. We added budget alerts first, hard stops second. The sequence matters.&lt;/p&gt;

&lt;p&gt;Alerts went to the team's channel when they crossed fifty, eighty, and one hundred percent of their monthly budget. Most teams self-corrected at fifty. For the ones that did not, a hard stop at the gateway rate-limits further calls until someone raises the budget.&lt;/p&gt;

&lt;p&gt;We deliberately did not lead with hard stops. An engineer running a time-sensitive demo who hits a hard limit learns that the gateway is the enemy. An engineer who gets a warning at fifty percent learns to watch their budget. The hard stop exists for the runaway loops, not for normal work.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we would do differently
&lt;/h2&gt;

&lt;p&gt;Three things we would change if we started over.&lt;/p&gt;

&lt;p&gt;First, we would meter streaming responses from day one. Token counts arrive at the end of a streamed response, and our first implementation missed them. Streaming became popular faster than we expected.&lt;/p&gt;

&lt;p&gt;Second, we would standardize the metadata stamp earlier. We let teams add custom attributes organically, and we ended up with three different keys for the same project name. Normalizing that retroactively was tedious.&lt;/p&gt;

&lt;p&gt;Third, we would keep the price table in version control with a review step. Model prices change. When they do, old estimates look wrong. We now treat the price table like code: a pull request, a reviewer, a changelog.&lt;/p&gt;

&lt;h2&gt;
  
  
  The real lesson
&lt;/h2&gt;

&lt;p&gt;Metering is not a billing feature. It is a feedback loop. The moment teams could see what their calls cost, they started engineering like the cost mattered. Architecture improved. Waste fell. Nobody needed a policy document telling them to be careful with the expensive model, because the numbers told the story better than any document could.&lt;/p&gt;

&lt;p&gt;If you are standing up an LLM gateway and nobody has asked about cost attribution yet, they will. Build the metering in before the bill becomes a conversation.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>azure</category>
      <category>devops</category>
      <category>apimanagement</category>
    </item>
    <item>
      <title>Cross-cloud cost math: when serverless beats fixed tiers</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Fri, 23 Oct 2026 02:33:42 +0000</pubDate>
      <link>https://dev.to/manojkagitha/cross-cloud-cost-math-when-serverless-beats-fixed-tiers-3og3</link>
      <guid>https://dev.to/manojkagitha/cross-cloud-cost-math-when-serverless-beats-fixed-tiers-3og3</guid>
      <description>&lt;h1&gt;
  
  
  Cross-cloud cost math: when serverless beats fixed tiers
&lt;/h1&gt;

&lt;p&gt;Every API consumer asks the same question sooner or later: which gateway&lt;br&gt;
tier should this run on? Most teams answer from habit. The right answer is&lt;br&gt;
arithmetic.&lt;/p&gt;

&lt;p&gt;I added a &lt;code&gt;cost&lt;/code&gt; command to&lt;br&gt;
&lt;a href="https://github.com/kagithamanoj/api-onboarding-kit" rel="noopener noreferrer"&gt;api-onboarding-kit&lt;/a&gt;&lt;br&gt;
because onboarding should include the answer. It reads the consumer spec,&lt;br&gt;
does the multiplication across every gateway tier, and prints the options&lt;br&gt;
cheapest first. The point is not that the numbers are perfect. They are&lt;br&gt;
from public list pricing and they move. The point is that the method is&lt;br&gt;
boring and it beats arguing from gut feeling.&lt;/p&gt;
&lt;h2&gt;
  
  
  The shape of the math
&lt;/h2&gt;

&lt;p&gt;Every tier is one of two shapes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Serverless:&lt;/strong&gt; &lt;code&gt;cost = requests x per-million price&lt;/code&gt;, no base.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fixed:&lt;/strong&gt; &lt;code&gt;cost = flat monthly base&lt;/code&gt;, no per-request term.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Requests per month come straight from the spec:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;monthly_requests = expected_rps x 86,400 x 30
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So a consumer at 10 rps average does about 25.9 million requests a month.&lt;br&gt;
Run that through the pricing table in the repo and you get:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Azure APIM Consumption: 25.92 x $4.00 = &lt;strong&gt;$103.68&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;AWS API Gateway HTTP API: 25.92 x $1.00 = &lt;strong&gt;$25.92&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;GCP API Gateway: 25.92 x $3.00 = &lt;strong&gt;$77.76&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Azure APIM Standard: &lt;strong&gt;$700.00&lt;/strong&gt; flat&lt;/li&gt;
&lt;li&gt;Apigee X pay-as-you-go: 25.92 x $40.00 = &lt;strong&gt;$1,036.80&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;At this traffic level, serverless wins everywhere and the fixed tier looks&lt;br&gt;
absurd. That reverses fast.&lt;/p&gt;
&lt;h2&gt;
  
  
  The crossover point
&lt;/h2&gt;

&lt;p&gt;Fixed beats serverless when:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;monthly_millions &amp;gt; base_usd / per_million_usd
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Take Azure APIM Standard ($700 flat) against Consumption ($4 per million):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# 700 / 4 = 175 million requests per month
&lt;/span&gt;&lt;span class="n"&gt;crossover_millions&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mf"&gt;700.0&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mf"&gt;4.00&lt;/span&gt;
&lt;span class="n"&gt;crossover_rps&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;crossover_millions&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mf"&gt;1e6&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;86_400&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="c1"&gt;# =&amp;gt; ~67 rps sustained, all month
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Below ~67 rps sustained, the consumption tier is cheaper. Above it, the&lt;br&gt;
fixed tier wins and every request past the line is effectively free.&lt;br&gt;
That is the whole decision. One division.&lt;/p&gt;
&lt;h2&gt;
  
  
  What the math misses
&lt;/h2&gt;

&lt;p&gt;Cheapest is not always right. Two things I learned the hard way:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Serverless tiers drop features.&lt;/strong&gt; In APIM, the consumption tier does&lt;br&gt;
not give you VNet support or the production SLA. If your security review&lt;br&gt;
requires private networking, the "cheaper" tier is not an option and the&lt;br&gt;
comparison is over before it starts. The estimator flags these notes on&lt;br&gt;
every row for a reason.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Averages lie.&lt;/strong&gt; &lt;code&gt;expectedRps&lt;/code&gt; drives the cost, but &lt;code&gt;burstRps&lt;/code&gt;&lt;br&gt;
decides whether the tier survives. A consumer that averages 5 rps and&lt;br&gt;
bursts to 500 rps can blow through a per-request tier's limits during the&lt;br&gt;
spike while costing nothing on paper. Burst is a capacity question, not a&lt;br&gt;
pricing question. Model it separately.&lt;/p&gt;

&lt;p&gt;So the working rule I give teams: run the arithmetic to pick the tier,&lt;br&gt;
then check the feature list and the burst behavior to confirm the tier&lt;br&gt;
is even allowed. Cost picks the winner among legal options.&lt;/p&gt;
&lt;h2&gt;
  
  
  The command
&lt;/h2&gt;


&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;onboard cost &lt;span class="nt"&gt;--all&lt;/span&gt; &lt;span class="nt"&gt;--spec&lt;/span&gt; payments-team.yaml
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;It reads &lt;code&gt;expectedRps&lt;/code&gt; from the spec and prints every gateway, every&lt;br&gt;
tier, cheapest first. Adding a tier is one dictionary entry:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="n"&gt;PRICING&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;azure-apim&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;][&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;tiers&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;][&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;premium&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;base_usd&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;2600.0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;per_million_usd&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mf"&gt;0.0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;note&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;Multi-region, higher throughput&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then the crossover math just works, because it is arithmetic, not logic.&lt;/p&gt;

&lt;h2&gt;
  
  
  The takeaway
&lt;/h2&gt;

&lt;p&gt;Gateway cost is not a negotiation or a vendor pitch. It is one division&lt;br&gt;
problem per tier. Do it in CI, on every new consumer, before the traffic&lt;br&gt;
exists. The numbers move and the features change, but the method does not.&lt;/p&gt;

&lt;p&gt;Repo: &lt;a href="https://github.com/kagithamanoj/api-onboarding-kit" rel="noopener noreferrer"&gt;kagithamanoj/api-onboarding-kit&lt;/a&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>azure</category>
      <category>aws</category>
      <category>serverless</category>
    </item>
    <item>
      <title>Every API Breaks Eventually. Versioning Decides Who Feels It.</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Wed, 21 Oct 2026 14:12:37 +0000</pubDate>
      <link>https://dev.to/manojkagitha/every-api-breaks-eventually-versioning-decides-who-feels-it-20jl</link>
      <guid>https://dev.to/manojkagitha/every-api-breaks-eventually-versioning-decides-who-feels-it-20jl</guid>
      <description>&lt;p&gt;If you have run APIs at enterprise scale, you know the call. A partner's app starts throwing 400s at noon on a Tuesday. Someone renamed a field in a response payload. Nobody versioned anything, so every client got the change at once. The fix takes ten minutes. The trust takes months to rebuild.&lt;/p&gt;

&lt;p&gt;Breaking changes are normal. Software grows. Fields get renamed, auth schemes get tightened, pagination shows up where it did not exist before. What is not normal is shipping a breaking change without a version. Versioning decides who feels a breaking change: nobody, or everyone.&lt;/p&gt;

&lt;p&gt;Here is how we run API versioning across a multi-gateway estate. I work with Apigee X and Azure APIM side by side, plus backing services on Azure. The estate is the hard part. One versioning policy only works if it holds on every gateway at once.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pick one versioning scheme and mean it
&lt;/h2&gt;

&lt;p&gt;There are three schemes people argue about: path versioning (&lt;code&gt;/v1/orders&lt;/code&gt;), header versioning (&lt;code&gt;Accept: application/vnd.orders.v2+json&lt;/code&gt;), and query params (&lt;code&gt;?version=2&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Path versioning wins in practice. Here is why. Every client knows how to hit a different path. Every log aggregator groups by path without custom parsing. Every gateway routes on path without policy gymnastics. Headers get stripped by proxies you do not control. Query params get swallowed by caches. Paths survive.&lt;/p&gt;

&lt;p&gt;The rule is simple: the version lives in the path, it is mandatory, and it never changes meaning. &lt;code&gt;/v1&lt;/code&gt; stays &lt;code&gt;/v1&lt;/code&gt; forever. If v1 needs a fix, you ship &lt;code&gt;/v2&lt;/code&gt; and deprecate v1. You never mutate v1 under the same URL.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put the policy in the gateway, not in every backend team
&lt;/h2&gt;

&lt;p&gt;The biggest versioning failure I have seen was not a bad scheme. It was a good scheme enforced nowhere. Teams were told to version their APIs. Half did it their way, half forgot, and one shipped &lt;code&gt;/v1.2-final-2&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The gateway is the enforcement point. It sits in front of every service. That is where the versioning policy lives, written once, applied to every API that crosses it.&lt;/p&gt;

&lt;p&gt;A practical gateway policy does three things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Rejects requests with unknown or missing versions with a clear 400.&lt;/li&gt;
&lt;li&gt;Routes each version to the right backend. &lt;code&gt;/v1/orders&lt;/code&gt; and &lt;code&gt;/v2/orders&lt;/code&gt; can point at the same service or different ones. The client never knows.&lt;/li&gt;
&lt;li&gt;Normalizes version metadata for logging, so analytics can answer "how much traffic is still on v1" without a forensic exercise.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;In Azure APIM this is an inbound policy on the product or gateway scope. Something like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight xml"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;policies&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;inbound&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;base&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;choose&amp;gt;&lt;/span&gt;
      &lt;span class="nt"&gt;&amp;lt;when&lt;/span&gt; &lt;span class="na"&gt;condition=&lt;/span&gt;&lt;span class="s"&gt;"@(context.Request.OriginalUrl.Path.StartsWith("&lt;/span&gt;&lt;span class="err"&gt;/v1")&lt;/span&gt;
          &lt;span class="err"&gt;||&lt;/span&gt; &lt;span class="err"&gt;context.Request.OriginalUrl.Path.StartsWith("/v2"))"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;set-header&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"x-api-version"&lt;/span&gt; &lt;span class="na"&gt;exists-action=&lt;/span&gt;&lt;span class="s"&gt;"override"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
          &lt;span class="nt"&gt;&amp;lt;value&amp;gt;&lt;/span&gt;@(context.Request.OriginalUrl.Path.Substring(1, 2))&lt;span class="nt"&gt;&amp;lt;/value&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;/set-header&amp;gt;&lt;/span&gt;
      &lt;span class="nt"&gt;&amp;lt;/when&amp;gt;&lt;/span&gt;
      &lt;span class="nt"&gt;&amp;lt;otherwise&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;return-response&amp;gt;&lt;/span&gt;
          &lt;span class="nt"&gt;&amp;lt;set-status&lt;/span&gt; &lt;span class="na"&gt;code=&lt;/span&gt;&lt;span class="s"&gt;"400"&lt;/span&gt; &lt;span class="na"&gt;reason=&lt;/span&gt;&lt;span class="s"&gt;"Bad Request"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
          &lt;span class="nt"&gt;&amp;lt;set-body&amp;gt;&lt;/span&gt;{"error": "unknown API version. Use /v1 or /v2."}&lt;span class="nt"&gt;&amp;lt;/set-body&amp;gt;&lt;/span&gt;
        &lt;span class="nt"&gt;&amp;lt;/return-response&amp;gt;&lt;/span&gt;
      &lt;span class="nt"&gt;&amp;lt;/otherwise&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;/choose&amp;gt;&lt;/span&gt;
  &lt;span class="nt"&gt;&amp;lt;/inbound&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/policies&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The same logic exists in Apigee as a set of conditional flows and a RaiseFault policy. Different syntax, same behavior. That is the point. The behavior is one policy, expressed twice. We keep a short spec doc for "version enforcement behavior" and review both gateway implementations against it whenever either changes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Versions need a registry, not just a URL pattern
&lt;/h2&gt;

&lt;p&gt;A URL pattern tells clients where to go. It does not tell anyone what is live, what is deprecated, or who still calls the old version. For that you need a registry: every API, every active version, the owner team, the deprecation date, and the known consumers.&lt;/p&gt;

&lt;p&gt;This sounds like paperwork. It is the thing that makes deprecation possible. Without a consumer list, deprecating v1 means guessing. With one, it means sending each consumer a date and a migration guide, then watching the traffic shift on the dashboard.&lt;/p&gt;

&lt;p&gt;The registry does not need to be fancy. A structured API catalog backed by the same onboarding flow teams already use works. The important part is that publishing a new version and updating the registry are the same action, not two separate chores that drift apart.&lt;/p&gt;

&lt;h2&gt;
  
  
  Deprecation is a schedule, not an announcement
&lt;/h2&gt;

&lt;p&gt;Announcing a deprecation and executing one are different jobs. Announcements get read and forgotten. Schedules get followed. A deprecation schedule has four parts:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A published end-of-life date, at least 90 days out for internal consumers, longer for partners. Nobody gets surprised.&lt;/li&gt;
&lt;li&gt;Sunset headers on responses from the deprecated version, so clients see the date every time they call. &lt;code&gt;Sunset&lt;/code&gt; and &lt;code&gt;Deprecation&lt;/code&gt; headers exist for exactly this.&lt;/li&gt;
&lt;li&gt;Staged traffic reduction: monitor v1 traffic weekly, reach out to the stragglers directly. The last 5 percent of traffic is always the hardest and always belongs to the team you least expect.&lt;/li&gt;
&lt;li&gt;A hard cutoff, enforced at the gateway, on the published date. The gateway returns 410 Gone with a link to the migration guide. Soft cutoffs become permanent.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is where the gateway policy pays for itself a second time. The cutoff is a one-line change in the routing policy, not a coordinated deploy across backend teams.&lt;/p&gt;

&lt;h2&gt;
  
  
  Validate the contract, not just the shape
&lt;/h2&gt;

&lt;p&gt;Versioning keeps clients on the contract they coded against. Contract validation keeps the contract honest. At the gateway, that means schema validation on requests and responses where it is cheap enough to run.&lt;/p&gt;

&lt;p&gt;The practical version: JSON Schema validation on the inbound side for critical endpoints. It catches the "we added a required field without bumping the version" mistake before it ships. Pair it with contract tests in CI on the backend side. The gateway check is the backstop, not the test suite.&lt;/p&gt;

&lt;p&gt;Keep validation scoped. Validating every payload on a high-throughput API adds latency you will feel at P99. Validate the versioned endpoints that carry breaking-change risk, and let observability cover the rest.&lt;/p&gt;

&lt;h2&gt;
  
  
  The short version
&lt;/h2&gt;

&lt;p&gt;Breaking changes are inevitable. Surprises are optional. One versioning scheme, enforced at every gateway, tracked in a registry, deprecated on a schedule, with contract validation at the choke point. That is the whole playbook. It is unglamorous work. It is also the difference between a Tuesday afternoon incident call and a migration that finishes before anyone notices.&lt;/p&gt;

</description>
      <category>api</category>
      <category>azure</category>
      <category>devops</category>
      <category>architecture</category>
    </item>
    <item>
      <title>Reusable Terraform Modules for API Gateway Provisioning Across Azure and AWS</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Mon, 19 Oct 2026 14:07:00 +0000</pubDate>
      <link>https://dev.to/manojkagitha/reusable-terraform-modules-for-api-gateway-provisioning-across-azure-and-aws-1hm2</link>
      <guid>https://dev.to/manojkagitha/reusable-terraform-modules-for-api-gateway-provisioning-across-azure-and-aws-1hm2</guid>
      <description>&lt;p&gt;Every team starts by copy-pasting Terraform. One folder becomes two. Two become ten. Then someone fixes a bug in one copy and the other nine keep the bug. Modules exist to end that cycle. A module is a packaged, versioned, reusable unit of infrastructure. Done well, it is the difference between a team that ships gateways in an afternoon and a team that hand-builds each one.&lt;/p&gt;

&lt;p&gt;This post builds two real modules: one for Azure API Management, one for AWS API Gateway. Along the way: module anatomy, the common-interface pattern for multi-cloud teams, versioning, composition, testing, and the anti-patterns to avoid.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why modules
&lt;/h2&gt;

&lt;p&gt;Three reasons.&lt;/p&gt;

&lt;p&gt;First, DRY. An API gateway has dozens of settings: SKUs, policies, products, subscriptions, backends. Define them once in a module. Every team consumes the same hardened configuration.&lt;/p&gt;

&lt;p&gt;Second, consistency. When security requires a new policy on every gateway, you change it in one place and roll it out by bumping a version pin. Without modules, you are editing ten folders and hoping you caught them all.&lt;/p&gt;

&lt;p&gt;Third, onboarding. A new engineer does not need to learn every APIM setting to ship an API. They call the module with five variables and get a production-ready gateway.&lt;/p&gt;

&lt;h2&gt;
  
  
  Anatomy of a good module
&lt;/h2&gt;

&lt;p&gt;A module is a folder with a contract. The contract has three parts.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Variables with validation.&lt;/strong&gt; Every input declares its type, a description, and where it matters, a validation block. Validation catches bad input at plan time instead of apply time.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Outputs.&lt;/strong&gt; A module that creates things but tells you nothing about them is a black box. Output the IDs, URLs, and names callers need.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;README.&lt;/strong&gt; Document the purpose, inputs, outputs, and one full example. If the README does not show a working example, the module is not done.&lt;/p&gt;

&lt;p&gt;Standard layout:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="err"&gt;modules/apim/&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="err"&gt;main.tf&lt;/span&gt;&lt;span class="w"&gt;        &lt;/span&gt;&lt;span class="err"&gt;#&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;resources&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="err"&gt;variables.tf&lt;/span&gt;&lt;span class="w"&gt;   &lt;/span&gt;&lt;span class="err"&gt;#&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;inputs&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;with&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;validation&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="err"&gt;outputs.tf&lt;/span&gt;&lt;span class="w"&gt;     &lt;/span&gt;&lt;span class="err"&gt;#&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;what&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;callers&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;get&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;back&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="err"&gt;versions.tf&lt;/span&gt;&lt;span class="w"&gt;    &lt;/span&gt;&lt;span class="err"&gt;#&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;required&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;providers&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="err"&gt;README.md&lt;/span&gt;&lt;span class="w"&gt;      &lt;/span&gt;&lt;span class="err"&gt;#&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;purpose,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="err"&gt;example&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;versions.tf&lt;/code&gt; pins the provider so the module never silently picks up a breaking provider release:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;required_version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"&amp;gt;= 1.5"&lt;/span&gt;
  &lt;span class="nx"&gt;required_providers&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;azurerm&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;source&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"hashicorp/azurerm"&lt;/span&gt;
      &lt;span class="nx"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"&amp;gt;= 3.0, &amp;lt; 4.0"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Azure APIM module
&lt;/h2&gt;

&lt;p&gt;Here is a module that provisions an API Management service and registers a list of APIs on it, each with a rate-limit policy and a product assignment.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;variables.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Name of the API Management service."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"location"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Azure region for the service."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"resource_group_name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Resource group for the APIM service."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"sku_name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"APIM SKU."&lt;/span&gt;
  &lt;span class="nx"&gt;default&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Developer_1"&lt;/span&gt;

  &lt;span class="nx"&gt;validation&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;condition&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;contains&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s2"&gt;"Developer_1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Basic_1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Standard_1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Premium_1"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sku_name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nx"&gt;error_message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"SKU must be one of Developer_1, Basic_1, Standard_1, Premium_1."&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"publisher_name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Publisher name shown in the developer portal."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"publisher_email"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Publisher contact email."&lt;/span&gt;

  &lt;span class="nx"&gt;validation&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;condition&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;can&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;regex&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"^[^@]+@[^@]+&lt;/span&gt;&lt;span class="err"&gt;\\&lt;/span&gt;&lt;span class="s2"&gt;.[^@]+$"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publisher_email&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="nx"&gt;error_message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Publisher email must be a valid email address."&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"apis"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;name&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
    &lt;span class="nx"&gt;display_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
    &lt;span class="nx"&gt;path&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
    &lt;span class="nx"&gt;protocols&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;list&lt;/span&gt;&lt;span class="err"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nx"&gt;backend_url&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="p"&gt;}))&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"APIs to register on the gateway."&lt;/span&gt;
  &lt;span class="nx"&gt;default&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;main.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_api_management"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;location&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;location&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_name&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publisher_name&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_email&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publisher_email&lt;/span&gt;
  &lt;span class="nx"&gt;sku_name&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sku_name&lt;/span&gt;

  &lt;span class="nx"&gt;identity&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"SystemAssigned"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_api_management_api"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;for&lt;/span&gt; &lt;span class="nx"&gt;api&lt;/span&gt; &lt;span class="nx"&gt;in&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;apis&lt;/span&gt; &lt;span class="o"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;api&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nx"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="nx"&gt;api_management_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;revision&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"1"&lt;/span&gt;
  &lt;span class="nx"&gt;display_name&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;display_name&lt;/span&gt;
  &lt;span class="nx"&gt;path&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;path&lt;/span&gt;
  &lt;span class="nx"&gt;protocols&lt;/span&gt;           &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;protocols&lt;/span&gt;
  &lt;span class="nx"&gt;service_url&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;backend_url&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_api_management_api_policy"&lt;/span&gt; &lt;span class="s2"&gt;"rate_limit"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;

  &lt;span class="nx"&gt;api_name&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="nx"&gt;api_management_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;

  &lt;span class="nx"&gt;xml_content&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;XML&lt;/span&gt;
&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;policies&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;inbound&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;rate-limit&lt;/span&gt; &lt;span class="nx"&gt;calls&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"100"&lt;/span&gt; &lt;span class="nx"&gt;renewal-period&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"60"&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;base&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nx"&gt;inbound&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;backend&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;base&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nx"&gt;backend&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;outbound&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;base&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nx"&gt;outbound&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;on-error&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
    &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;base&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
  &lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nx"&gt;on-error&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="o"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nx"&gt;policies&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nx"&gt;XML&lt;/span&gt;
&lt;span class="err"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_api_management_product"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;product_id&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"default-product"&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="nx"&gt;api_management_name&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;display_name&lt;/span&gt;          &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Default Product"&lt;/span&gt;
  &lt;span class="nx"&gt;subscription_required&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="nx"&gt;approval_required&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
  &lt;span class="nx"&gt;published&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"azurerm_api_management_product_api"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;

  &lt;span class="nx"&gt;api_name&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;product_id&lt;/span&gt;          &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management_product&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;product_id&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;resource_group_name&lt;/span&gt;
  &lt;span class="nx"&gt;api_management_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;outputs.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"gateway_url"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"The gateway URL of the APIM service."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;gateway_url&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"service_id"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"The resource ID of the APIM service."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"api_ids"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Map of API name to resource ID."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;for&lt;/span&gt; &lt;span class="nx"&gt;k&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;v&lt;/span&gt; &lt;span class="nx"&gt;in&lt;/span&gt; &lt;span class="nx"&gt;azurerm_api_management_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt; &lt;span class="o"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;k&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;v&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice the pattern: &lt;code&gt;for_each&lt;/code&gt; over a map keyed by name. This keeps resource addresses stable when the list order changes. If you use &lt;code&gt;count&lt;/code&gt; with a list, reordering the list destroys and recreates APIs. With &lt;code&gt;for_each&lt;/code&gt; keyed by name, only real changes trigger updates.&lt;/p&gt;

&lt;h2&gt;
  
  
  AWS API Gateway module
&lt;/h2&gt;

&lt;p&gt;Same idea, AWS REST API flavor. The module takes a list of endpoints and builds resources, methods, proxy integrations, a deployment, and a stage.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;variables.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Name of the REST API."&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"description"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Description of the REST API."&lt;/span&gt;
  &lt;span class="nx"&gt;default&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Managed by Terraform"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"stage_name"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Deployment stage name."&lt;/span&gt;
  &lt;span class="nx"&gt;default&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prod"&lt;/span&gt;

  &lt;span class="nx"&gt;validation&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;condition&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;can&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;regex&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"^[a-z0-9-]+$"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stage_name&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="nx"&gt;error_message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Stage name must be lowercase alphanumeric with dashes."&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;variable&lt;/span&gt; &lt;span class="s2"&gt;"endpoints"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;list&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;path_part&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
    &lt;span class="nx"&gt;http_method&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
    &lt;span class="nx"&gt;backend_uri&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;string&lt;/span&gt;
  &lt;span class="err"&gt;}&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Endpoints to expose through the gateway."&lt;/span&gt;
  &lt;span class="nx"&gt;default&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[]&lt;/span&gt;

  &lt;span class="nx"&gt;validation&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;condition&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;alltrue&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;
      &lt;span class="nx"&gt;for&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt; &lt;span class="nx"&gt;in&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;endpoints&lt;/span&gt; &lt;span class="o"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;contains&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="s2"&gt;"GET"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"POST"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"PUT"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"PATCH"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"DELETE"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;http_method&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;])&lt;/span&gt;
    &lt;span class="nx"&gt;error_message&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"HTTP methods must be one of GET, POST, PUT, PATCH, DELETE."&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;main.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;locals&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;endpoints&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;for&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt; &lt;span class="nx"&gt;in&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;endpoints&lt;/span&gt; &lt;span class="o"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"${e.http_method}-${e.path_part}"&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_rest_api"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;description&lt;/span&gt;

  &lt;span class="nx"&gt;endpoint_configuration&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;types&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"REGIONAL"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_resource"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;endpoints&lt;/span&gt;

  &lt;span class="nx"&gt;rest_api_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;parent_id&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;root_resource_id&lt;/span&gt;
  &lt;span class="nx"&gt;path_part&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;path_part&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_method"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;endpoints&lt;/span&gt;

  &lt;span class="nx"&gt;rest_api_id&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;resource_id&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_resource&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;http_method&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;http_method&lt;/span&gt;
  &lt;span class="nx"&gt;authorization&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"NONE"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_integration"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;for_each&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;endpoints&lt;/span&gt;

  &lt;span class="nx"&gt;rest_api_id&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;resource_id&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_resource&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;http_method&lt;/span&gt;             &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_method&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;key&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;http_method&lt;/span&gt;
  &lt;span class="nx"&gt;integration_http_method&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"POST"&lt;/span&gt;
  &lt;span class="nx"&gt;type&lt;/span&gt;                    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"HTTP_PROXY"&lt;/span&gt;
  &lt;span class="nx"&gt;uri&lt;/span&gt;                     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;each&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;backend_uri&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_deployment"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;rest_api_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;

  &lt;span class="nx"&gt;triggers&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;redeploy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sha1&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;jsonencode&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;
      &lt;span class="nx"&gt;aws_api_gateway_resource&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;aws_api_gateway_method&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;aws_api_gateway_integration&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;]))&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nx"&gt;lifecycle&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;create_before_destroy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_api_gateway_stage"&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;deployment_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_deployment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;rest_api_id&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;stage_name&lt;/span&gt;    &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;var&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stage_name&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things worth noting. First, the &lt;code&gt;triggers&lt;/code&gt; block with a SHA hash: API Gateway deployments are immutable snapshots. Without the trigger, changing a method does not create a new deployment and your change never goes live. The hash forces redeployment whenever the API configuration changes. This is the single most common gotcha with Terraform-managed API Gateway.&lt;/p&gt;

&lt;p&gt;Second, &lt;code&gt;create_before_destroy&lt;/code&gt; on the deployment. Without it, Terraform destroys the old deployment before creating the new one, and the stage briefly points at nothing. With it, the new deployment exists before the old one is removed.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;outputs.tf&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"invoke_url"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"The invoke URL of the deployed stage."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_stage&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;invoke_url&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"rest_api_id"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"The ID of the REST API."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;output&lt;/span&gt; &lt;span class="s2"&gt;"execution_arn"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;description&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"The execution ARN for IAM permissions."&lt;/span&gt;
  &lt;span class="nx"&gt;value&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_api_gateway_rest_api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;execution_arn&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The common-interface pattern
&lt;/h2&gt;

&lt;p&gt;Here is the move that pays off for multi-cloud teams: give both modules the same variable names for the same concepts.&lt;/p&gt;

&lt;p&gt;Both modules accept &lt;code&gt;name&lt;/code&gt;. Both accept a list of backend definitions shaped as objects with a path, a method, and a backend URL. Callers learn one interface. When a team moves a workload from Azure to AWS, the module call changes but the shape of the inputs does not.&lt;/p&gt;

&lt;p&gt;This does not mean the modules are identical inside. Cloud services differ, and each module should use its platform well. APIM gets products and XML policies. API Gateway gets deployments and stages. The interface is shared. The implementation is native.&lt;/p&gt;

&lt;p&gt;Where the clouds genuinely diverge, let the variables diverge too. Do not force a fake common variable that maps to nothing on one side. Common where it is real, specific where it is not.&lt;/p&gt;

&lt;h2&gt;
  
  
  Versioned module sources
&lt;/h2&gt;

&lt;p&gt;Never consume a module from a moving target. Pin to a Git tag:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"apim"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"git::https://github.com/myorg/terraform-modules.git//modules/apim?ref=v1.2.0"&lt;/span&gt;

  &lt;span class="nx"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"apim-prod"&lt;/span&gt;
  &lt;span class="nx"&gt;location&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"eastus"&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_resource_group&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_name&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Platform Team"&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_email&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"platform@example.com"&lt;/span&gt;
  &lt;span class="nx"&gt;apis&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;apis&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;?ref=v1.2.0&lt;/code&gt; is the whole game. Without it, every &lt;code&gt;terraform init&lt;/code&gt; can pull different code. With it, upgrades are deliberate: bump the ref, run plan, review the diff, apply.&lt;/p&gt;

&lt;p&gt;Tag releases with semantic versioning. Breaking input changes bump the major version. New optional variables bump the minor. Fixes bump the patch. Write a short changelog per release so consumers know what changed before they bump.&lt;/p&gt;

&lt;h2&gt;
  
  
  Private registry option
&lt;/h2&gt;

&lt;p&gt;If Git URLs get unwieldy across dozens of call sites, Terraform Cloud and Terraform Enterprise offer a private registry. Modules get versioned releases with a changelog UI, and the call site becomes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"apim"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"app.terraform.io/myorg/apim/azurerm"&lt;/span&gt;
  &lt;span class="nx"&gt;version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"1.2.0"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Cleaner to read, easier to browse. It costs money and ties you to the platform. For most teams, Git tags are enough until the module count gets large. Start with tags. Move to a registry when discovery becomes the problem.&lt;/p&gt;

&lt;h2&gt;
  
  
  Composition pattern
&lt;/h2&gt;

&lt;p&gt;Modules compose. A root module for an environment calls child modules and wires outputs to inputs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"network"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"git::https://github.com/myorg/terraform-modules.git//modules/network?ref=v2.0.1"&lt;/span&gt;

  &lt;span class="nx"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"vnet-prod"&lt;/span&gt;
  &lt;span class="nx"&gt;location&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"eastus"&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_resource_group&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;address_space&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"10.0.0.0/16"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"apim"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"git::https://github.com/myorg/terraform-modules.git//modules/apim?ref=v1.2.0"&lt;/span&gt;

  &lt;span class="nx"&gt;name&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"apim-prod"&lt;/span&gt;
  &lt;span class="nx"&gt;location&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"eastus"&lt;/span&gt;
  &lt;span class="nx"&gt;resource_group_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;azurerm_resource_group&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;main&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;name&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_name&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Platform Team"&lt;/span&gt;
  &lt;span class="nx"&gt;publisher_email&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"platform@example.com"&lt;/span&gt;
  &lt;span class="nx"&gt;apis&lt;/span&gt;                &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;local&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;apis&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;module&lt;/span&gt; &lt;span class="s2"&gt;"dns"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;source&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"git::https://github.com/myorg/terraform-modules.git//modules/dns?ref=v1.0.3"&lt;/span&gt;

  &lt;span class="nx"&gt;zone_name&lt;/span&gt;   &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"api.example.com"&lt;/span&gt;
  &lt;span class="nx"&gt;gateway_url&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;module&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;apim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;gateway_url&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each child owns one concern. The root owns the wiring. Nobody edits child module internals from the root, and no child reaches into another child's state. Data flows through outputs, in one direction.&lt;/p&gt;

&lt;h2&gt;
  
  
  Version pinning discipline
&lt;/h2&gt;

&lt;p&gt;Pin everything. Module sources get &lt;code&gt;?ref=&lt;/code&gt;. Providers get version constraints in &lt;code&gt;versions.tf&lt;/code&gt;. Terraform itself gets &lt;code&gt;required_version&lt;/code&gt; in the root.&lt;/p&gt;

&lt;p&gt;Then automate the upgrades. Renovate or Dependabot can open pull requests when new module tags land. Each PR shows a plan diff against the new version. You review the diff, merge, and apply. Upgrades become routine instead of scary, and you never discover six months later that half your environments run a different module version than the other half.&lt;/p&gt;

&lt;p&gt;One rule for the team: no PR merges with an unpinned module source. Enforce it in CI with a simple grep if you have to. The discipline matters more than the tool.&lt;/p&gt;

&lt;h2&gt;
  
  
  Module testing basics
&lt;/h2&gt;

&lt;p&gt;Untested modules rot. Someone changes a default, nothing validates it, and three teams discover the breakage on their next apply. Three levels of testing, cheapest first:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;code&gt;terraform validate&lt;/code&gt; and &lt;code&gt;tflint&lt;/code&gt; in CI on every pull request. Catches syntax errors, deprecated syntax, and style issues. Fast and free.&lt;/li&gt;
&lt;li&gt;Example configurations in &lt;code&gt;examples/&lt;/code&gt; folders that get planned in CI. If the example does not plan cleanly, the module is broken. This catches the most common real-world breakage: a variable change that no longer matches how callers use the module.&lt;/li&gt;
&lt;li&gt;Terratest (Go) for modules that must actually apply. It provisions real infrastructure, asserts on outputs, then destroys. Slower and costs cloud spend, so reserve it for widely used modules where a bad release hurts many teams.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;At minimum, do levels 1 and 2. They catch most breakage for almost no cost.&lt;/p&gt;

&lt;h2&gt;
  
  
  Anti-patterns
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Mega-modules.&lt;/strong&gt; One module that provisions networking, gateways, databases, and DNS is not reusable. It is a snowflake with inputs. Split by concern. A module should do one thing well enough that a team can adopt it without adopting everything around it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Unpinned versions.&lt;/strong&gt; A source with no &lt;code&gt;?ref=&lt;/code&gt; is a time bomb. Today it works. Tomorrow someone pushes a breaking change and your next init breaks every environment at once. Pin always.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Provider config in child modules.&lt;/strong&gt; Child modules must never declare &lt;code&gt;provider&lt;/code&gt; blocks with credentials or aliases they invent. Providers are configured in the root and passed down. A child that configures its own provider cannot be reused across accounts, regions, or environments.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Boolean sprawl.&lt;/strong&gt; A module with fifteen boolean flags (&lt;code&gt;enable_x&lt;/code&gt;, &lt;code&gt;create_y&lt;/code&gt;, &lt;code&gt;skip_z&lt;/code&gt;) is twelve modules wearing a trench coat. If the flags cluster into real use cases, split the module along those lines. A few well-chosen flags are fine. Fifteen is a design smell.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Outputs nobody uses.&lt;/strong&gt; Every output is a promise to maintain. If no caller reads it, delete it. Review outputs when you review the module.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;[ ] One concern per module. No mega-modules.&lt;/li&gt;
&lt;li&gt;[ ] Every variable has a type, a description, and validation where it matters.&lt;/li&gt;
&lt;li&gt;[ ] Outputs expose what callers need: IDs, URLs, names. Nothing more.&lt;/li&gt;
&lt;li&gt;[ ] README with a working example that actually plans.&lt;/li&gt;
&lt;li&gt;[ ] All module sources pinned with &lt;code&gt;?ref=&lt;/code&gt; tags. No exceptions.&lt;/li&gt;
&lt;li&gt;[ ] Providers declared in &lt;code&gt;versions.tf&lt;/code&gt;, configured only in the root module.&lt;/li&gt;
&lt;li&gt;[ ] Semantic versioning on releases. Breaking changes bump major.&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;validate&lt;/code&gt;, &lt;code&gt;tflint&lt;/code&gt;, and example plans running in CI.&lt;/li&gt;
&lt;li&gt;[ ] Common variable names across cloud-specific modules where the concepts genuinely match.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Next
&lt;/h2&gt;

&lt;p&gt;Modules give you reusable building blocks with versioned releases. But who runs them, and when? If engineers still apply from laptops, you have versioned modules and unversioned process.&lt;/p&gt;

&lt;p&gt;Next article: Terraform in CI/CD with GitHub Actions. Plan/apply gates, OIDC auth with no stored secrets, plan output posted as PR comments for review, and multi-environment promotion from dev to prod.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>azure</category>
      <category>aws</category>
      <category>api</category>
    </item>
    <item>
      <title>Terraform Remote State at Enterprise Scale: Backends, Locking, Bootstrapping, and Team Workflows</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Wed, 14 Oct 2026 04:59:01 +0000</pubDate>
      <link>https://dev.to/manojkagitha/terraform-remote-state-at-enterprise-scale-backends-locking-bootstrapping-and-team-workflows-m6e</link>
      <guid>https://dev.to/manojkagitha/terraform-remote-state-at-enterprise-scale-backends-locking-bootstrapping-and-team-workflows-m6e</guid>
      <description>&lt;p&gt;When you are the only one running Terraform, local state is fine. The moment a second engineer runs apply, you are one race condition away from a broken environment. And when you are running dozens of environments across teams, the questions get harder: who creates the state bucket, how do you split state so one bad apply cannot take down everything, and how do you give a team of twenty engineers safe access without handing everyone the keys to production?&lt;/p&gt;

&lt;p&gt;This post covers the full picture: choosing a backend, the bootstrapping problem nobody warns you about, state layout strategy, locking, surgery when things go wrong, and the team workflow that holds it together.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why local state breaks
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;terraform.tfstate&lt;/code&gt; on your laptop is a single point of failure. It cannot be shared. It cannot be locked. If your laptop dies, your state dies with it. Worse, if two people apply at the same time, the last write wins and the loser’s changes vanish from state while still existing in the cloud. That gap between state and reality is called drift, and it is painful to fix.&lt;/p&gt;

&lt;p&gt;Remote state solves three problems: shared access, locking, and durability. But setting it up raises a question most tutorials skip.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bootstrapping problem
&lt;/h2&gt;

&lt;p&gt;Here is the chicken-and-egg problem: Terraform needs a backend to store state, but the backend itself (an S3 bucket, a DynamoDB table, a storage account) is infrastructure. Who creates it?&lt;/p&gt;

&lt;p&gt;You have three options, and only one of them is right for teams.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 1: ClickOps.&lt;/strong&gt; Someone creates the bucket by hand in the console. This works exactly once. Then nobody remembers the settings, the bucket has no versioning, no encryption, no lifecycle policy, and six months later someone asks why state history only goes back two weeks.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 2: A separate bootstrap Terraform project with local state.&lt;/strong&gt; This is the standard answer. You keep one tiny Terraform project whose only job is to create the backend infrastructure. Its state stays local (or in a second-level backend), because it has to exist before everything else.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Option 3: Terraform managing its own backend.&lt;/strong&gt; Do not do this. A Terraform project cannot reliably create the bucket that holds its own state. The init sequence makes this circular and fragile.&lt;/p&gt;

&lt;p&gt;Here is what a bootstrap project looks like on AWS:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="c1"&gt;# bootstrap/main.tf - run once per account, state stays local&lt;/span&gt;
&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;required_version&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"&amp;gt;= 1.5"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;provider&lt;/span&gt; &lt;span class="s2"&gt;"aws"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;region&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket"&lt;/span&gt; &lt;span class="s2"&gt;"tfstate"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state-prod"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket_versioning"&lt;/span&gt; &lt;span class="s2"&gt;"tfstate"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_s3_bucket&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tfstate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;versioning_configuration&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Enabled"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket_server_side_encryption_configuration"&lt;/span&gt; &lt;span class="s2"&gt;"tfstate"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_s3_bucket&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tfstate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;rule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;apply_server_side_encryption_by_default&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;sse_algorithm&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"aws:kms"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_s3_bucket_public_access_block"&lt;/span&gt; &lt;span class="s2"&gt;"tfstate"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;bucket&lt;/span&gt;                  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;aws_s3_bucket&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;tfstate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="nx"&gt;block_public_acls&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="nx"&gt;block_public_policy&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="nx"&gt;ignore_public_acls&lt;/span&gt;      &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="nx"&gt;restrict_public_buckets&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nx"&gt;resource&lt;/span&gt; &lt;span class="s2"&gt;"aws_dynamodb_table"&lt;/span&gt; &lt;span class="s2"&gt;"tflocks"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;name&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks"&lt;/span&gt;
  &lt;span class="nx"&gt;billing_mode&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"PAY_PER_REQUEST"&lt;/span&gt;
  &lt;span class="nx"&gt;hash_key&lt;/span&gt;     &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"LockID"&lt;/span&gt;

  &lt;span class="nx"&gt;attribute&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"LockID"&lt;/span&gt;
    &lt;span class="nx"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"S"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Versioning matters more than people think. If a state file gets corrupted, versioning lets you roll back to the last good version. Without it, you are reconstructing state from &lt;code&gt;terraform import&lt;/code&gt;, resource by resource, which is exactly as fun as it sounds.&lt;/p&gt;

&lt;p&gt;Run this once per account. Commit it to git. Then every other project points at the backend it created.&lt;/p&gt;

&lt;h2&gt;
  
  
  Picking a backend
&lt;/h2&gt;

&lt;p&gt;Every major cloud has a native backend. The pattern is the same everywhere: an object store for the state file plus a locking mechanism.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AWS (S3 + DynamoDB):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;backend&lt;/span&gt; &lt;span class="s2"&gt;"s3"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;bucket&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state-prod"&lt;/span&gt;
    &lt;span class="nx"&gt;key&lt;/span&gt;            &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"network/terraform.tfstate"&lt;/span&gt;
    &lt;span class="nx"&gt;region&lt;/span&gt;         &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"us-east-1"&lt;/span&gt;
    &lt;span class="nx"&gt;dynamodb_table&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"terraform-state-locks"&lt;/span&gt;
    &lt;span class="nx"&gt;encrypt&lt;/span&gt;        &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Azure (Blob Storage):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;backend&lt;/span&gt; &lt;span class="s2"&gt;"azurerm"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;resource_group_name&lt;/span&gt;  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"tfstate-rg"&lt;/span&gt;
    &lt;span class="nx"&gt;storage_account_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"tfstatestore"&lt;/span&gt;
    &lt;span class="nx"&gt;container_name&lt;/span&gt;       &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"tfstate"&lt;/span&gt;
    &lt;span class="nx"&gt;key&lt;/span&gt;                  &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"network.terraform.tfstate"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Azure handles locking natively through blob leases. No separate lock table to manage. One less moving part, and one less thing to misconfigure.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;GCP (GCS):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;backend&lt;/span&gt; &lt;span class="s2"&gt;"gcs"&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;bucket&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"myorg-terraform-state"&lt;/span&gt;
    &lt;span class="nx"&gt;prefix&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"network"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;GCS locking is native as well.&lt;/p&gt;

&lt;h2&gt;
  
  
  State layout: one file per blast radius
&lt;/h2&gt;

&lt;p&gt;Do not put your entire infrastructure in one state file. Split by environment and by component. A layout that works:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;prod/
  network/terraform.tfstate
  compute/terraform.tfstate
  data/terraform.tfstate
  dns/terraform.tfstate
staging/
  network/terraform.tfstate
  compute/terraform.tfstate
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three reasons for this:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Blast radius.&lt;/strong&gt; If the network state gets corrupted, compute and data are untouched. A bad apply can only destroy what is in its state file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Speed.&lt;/strong&gt; A plan against a 5,000-resource state file is slow. A plan against 200 resources is fast. Engineers stop running plan when it takes ten minutes. Then they apply blind.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Access control.&lt;/strong&gt; Not everyone needs access to every state file. The data team does not need write access to network state. Smaller state files map cleanly to IAM boundaries.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The tradeoff is cross-component references. When compute needs the VPC ID from network state, use &lt;code&gt;terraform_remote_state&lt;/code&gt; data sources or, better, pass values through a shared outputs pattern. It adds a little friction. The blast radius protection is worth it.&lt;/p&gt;

&lt;h2&gt;
  
  
  State locking in practice
&lt;/h2&gt;

&lt;p&gt;Locking is automatic once the backend supports it. When you run apply, Terraform acquires the lock. Anyone else who tries gets an error instead of corrupting your state.&lt;/p&gt;

&lt;p&gt;Two rules I follow:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Never use &lt;code&gt;-lock=false&lt;/code&gt; in a shared workflow. It exists for emergencies, like a stuck lock after a crashed apply. If you use it, tell the team first.&lt;/li&gt;
&lt;li&gt;If a lock gets stuck, &lt;code&gt;terraform force-unlock &amp;lt;lock-id&amp;gt;&lt;/code&gt; clears it. Check with the team before you do. Someone might actually be mid-apply, and force-unlocking under them recreates the exact race condition locking was built to prevent.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  State surgery: when you need to move resources
&lt;/h2&gt;

&lt;p&gt;Sometimes the layout needs to change. You split a monolith state into components, or you move a resource from one team’s state to another’s. Terraform has tools for this, and they all operate on state without touching real infrastructure.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Move a resource between modules or addresses:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform state &lt;span class="nb"&gt;mv&lt;/span&gt; &lt;span class="s1"&gt;'aws_instance.web'&lt;/span&gt; &lt;span class="s1"&gt;'module.compute.aws_instance.web'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This rewrites the state file. The EC2 instance keeps running. Nothing is destroyed. But get the address wrong and Terraform will plan to destroy the old address and create the new one. Always run &lt;code&gt;terraform plan&lt;/code&gt; immediately after a state mv. If the plan shows creates or destroys, you got the address wrong. Fix it before anyone applies.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pull state down, fix it, push it back:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform state pull &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; /tmp/state.json
&lt;span class="c"&gt;# edit carefully&lt;/span&gt;
terraform state push /tmp/state.json
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the escape hatch for corrupted state. It is also the fastest way to make things worse if you edit the JSON by hand without understanding the schema. Use it as a last resort, and keep a backup of the original pull.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Remove something from state without destroying it:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform state &lt;span class="nb"&gt;rm&lt;/span&gt; &lt;span class="s1"&gt;'aws_s3_bucket.legacy'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The bucket keeps existing in AWS. Terraform just stops managing it. Useful when decommissioning Terraform management of a resource, or when handing a resource to another team’s state file (rm here, import there).&lt;/p&gt;

&lt;h2&gt;
  
  
  Migrating from local to remote state
&lt;/h2&gt;

&lt;p&gt;If you already have local state and need to move it, the process is straightforward:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Add the backend block to your configuration.&lt;/li&gt;
&lt;li&gt;Run &lt;code&gt;terraform init&lt;/code&gt;. Terraform detects the migration and asks: "Do you want to copy existing state to the new backend?" Say yes.&lt;/li&gt;
&lt;li&gt;Verify with &lt;code&gt;terraform plan&lt;/code&gt;. It should show no changes.&lt;/li&gt;
&lt;li&gt;Delete the local &lt;code&gt;terraform.tfstate&lt;/code&gt; and the backup. Commit the backend config.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The init migration is one of the few genuinely smooth operations in Terraform. It just works.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep secrets out of hardcoded config
&lt;/h2&gt;

&lt;p&gt;Do not hardcode bucket names or credentials in your backend block. Use partial backend configuration and pass values at init time:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight hcl"&gt;&lt;code&gt;&lt;span class="nx"&gt;terraform&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;backend&lt;/span&gt; &lt;span class="s2"&gt;"s3"&lt;/span&gt; &lt;span class="p"&gt;{}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;terraform init &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-backend-config&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"bucket=myorg-terraform-state-prod"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-backend-config&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"key=network/terraform.tfstate"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-backend-config&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"region=us-east-1"&lt;/span&gt; &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="nt"&gt;-backend-config&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"dynamodb_table=terraform-state-locks"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This keeps environment-specific values out of version control and lets the same code work across dev, staging, and prod. In CI/CD, these values come from pipeline variables, not from the repo.&lt;/p&gt;

&lt;h2&gt;
  
  
  State files contain secrets
&lt;/h2&gt;

&lt;p&gt;This one catches people. Terraform state stores every attribute of every resource, including passwords, keys, and connection strings, in plain text. Treat your state bucket like a secrets store:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Enable encryption at rest (the &lt;code&gt;encrypt = true&lt;/code&gt; above, or the KMS config in the bootstrap).&lt;/li&gt;
&lt;li&gt;Restrict IAM access to the state bucket to the CI/CD role and break-glass admins only. Engineers get read access for planning, not write.&lt;/li&gt;
&lt;li&gt;Never commit a state file to git. Add &lt;code&gt;*.tfstate&lt;/code&gt; and &lt;code&gt;*.tfstate.backup&lt;/code&gt; to &lt;code&gt;.gitignore&lt;/code&gt; on day one.&lt;/li&gt;
&lt;li&gt;Enable bucket versioning so a corrupted state can be rolled back.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you are already using Vault or a secrets manager for application secrets, that does not cover Terraform state. State is a separate secrets surface. Treat it as one.&lt;/p&gt;

&lt;h2&gt;
  
  
  The team workflow
&lt;/h2&gt;

&lt;p&gt;The setup that works for most teams:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Engineers run &lt;code&gt;terraform plan&lt;/code&gt; locally against the remote state. Plans are safe. They change nothing. Read access to state is enough.&lt;/li&gt;
&lt;li&gt;Pull requests include the plan output. Reviewers check what will change before it changes.&lt;/li&gt;
&lt;li&gt;Only CI/CD runs &lt;code&gt;terraform apply&lt;/code&gt;, after the plan is approved. The pipeline uses a dedicated IAM role with write access to state.&lt;/li&gt;
&lt;li&gt;Applies run serially per state file. The lock enforces this mechanically, but the pipeline should also avoid queuing parallel applies to the same state.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Local plan, reviewed apply, locked state. That is the whole discipline. It scales from two engineers to two hundred without changing shape.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pre-flight checklist
&lt;/h2&gt;

&lt;p&gt;Before you call your remote state setup done:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;[ ] Backend infrastructure created via a bootstrap project, not by hand&lt;/li&gt;
&lt;li&gt;[ ] Versioning enabled on the state bucket&lt;/li&gt;
&lt;li&gt;[ ] Encryption at rest enabled&lt;/li&gt;
&lt;li&gt;[ ] Public access blocked on the state bucket&lt;/li&gt;
&lt;li&gt;[ ] Locking configured and tested (run two applies, confirm the second waits or fails cleanly)&lt;/li&gt;
&lt;li&gt;[ ] State split by environment and component, not one giant file&lt;/li&gt;
&lt;li&gt;[ ] &lt;code&gt;.gitignore&lt;/code&gt; covers &lt;code&gt;*.tfstate&lt;/code&gt; and &lt;code&gt;*.tfstate.backup&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;[ ] IAM: engineers read, CI/CD writes, break-glass admins only&lt;/li&gt;
&lt;li&gt;[ ] Backend values passed via &lt;code&gt;-backend-config&lt;/code&gt;, not hardcoded&lt;/li&gt;
&lt;li&gt;[ ] Team knows the &lt;code&gt;force-unlock&lt;/code&gt; procedure and when not to use it&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Closing
&lt;/h2&gt;

&lt;p&gt;Remote state is not exciting work. Nobody demos a backend block at a conference. But every production Terraform setup stands on it, and every Terraform horror story I have heard starts with someone skipping one of the items on that checklist.&lt;/p&gt;

&lt;p&gt;Get the backend right, split your state by blast radius, lock everything, and keep secrets out of git. The rest of your Terraform practice gets easier from there.&lt;/p&gt;

&lt;p&gt;Next week: reusable Terraform modules for API gateway provisioning across Azure and AWS, with versioned module registries and composition patterns that survive team growth.&lt;/p&gt;

</description>
      <category>terraform</category>
      <category>aws</category>
      <category>azure</category>
      <category>devops</category>
    </item>
    <item>
      <title>I Gave My AI Agents an Org Chart</title>
      <dc:creator>Manoj Kumar Kagitha</dc:creator>
      <pubDate>Thu, 08 Oct 2026 21:31:44 +0000</pubDate>
      <link>https://dev.to/manojkagitha/i-gave-my-ai-agents-an-org-chart-3f0h</link>
      <guid>https://dev.to/manojkagitha/i-gave-my-ai-agents-an-org-chart-3f0h</guid>
      <description>&lt;h1&gt;
  
  
  I Gave My AI Agents an Org Chart
&lt;/h1&gt;

&lt;p&gt;Most agent frameworks hand you a pile of scripts and wish you luck. You wire up three agents, write the orchestration glue yourself, and six weeks later you have a system nobody can explain. I kept running into this, so I built something with a different shape: a company.&lt;/p&gt;

&lt;p&gt;It is called Botropolis. Twenty specialist agents across ten departments, one CEO orchestrator, and a training pipeline so each agent can eventually get its own fine-tuned model. It is open source, MIT licensed, and it runs with no API keys.&lt;/p&gt;

&lt;h2&gt;
  
  
  The idea
&lt;/h2&gt;

&lt;p&gt;Companies figured out coordination centuries ago. When work gets complex, you do not throw twenty generalists into a chat room. You create departments, give people job titles, and let a manager break big requests into pieces. Botropolis is that idea in Python.&lt;/p&gt;

&lt;p&gt;You ask Manoj, the CEO, for something. He looks at the request, decides which departments need to be involved, and routes the work. Research goes to Scout, code goes to Coder, the numbers go to Analyst. Each agent has a YAML spec: name, title, specialty, tools it may call, example tasks. Anyone reading the repo can see who does what, the way an org chart tells you who owns what.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it actually does
&lt;/h2&gt;

&lt;p&gt;The roster covers ten departments: research, health, finance, code, data, legal, marketing, ops, security, and support. Some highlights:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Teaming.&lt;/strong&gt; One agent alone is fine, a team is better. You name the agents and the rounds, and they draft, critique, and revise in sequence. Each agent sees everything its teammates produced before it. Manoj writes the final synthesis.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Real tools, no vendor lock-in.&lt;/strong&gt; Agents with toolkits run a think-act-observe loop over a plain-text protocol. No provider function calling involved, so it works with OpenAI, Anthropic, Gemini, Ollama, or a model you trained yourself. Fourteen tools ship in the box: web search, shell, file tools, Gmail, calendar, a shared company notebook.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A web UI with no build step.&lt;/strong&gt; Plain HTML, CSS, and JS served by the same FastAPI process. Chat with the CEO, a war room for talking to one agent directly with live tool-call streaming, teaming controls, per-agent analytics, and a roster browser. It works on a phone.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Training pipeline.&lt;/strong&gt; Datasets, configs, an eval harness, and model cards are all in the repo. I trained Scout-tiny from scratch as a proof of concept: a 5.49M-parameter transformer on 300 Q&amp;amp;A pairs, validation perplexity 5.17. Demo scale, honestly labeled as such. The real path is LoRA on a small open model, and the scaffolding for that is documented.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The honest parts
&lt;/h2&gt;

&lt;p&gt;It runs with zero API keys against an offline stub that labels its output as stub output. Clone it, run &lt;code&gt;python examples/demo.py&lt;/code&gt;, and watch the whole company work before spending anything.&lt;/p&gt;

&lt;p&gt;The safety model is pragmatic, not paranoid. File and shell tools are sandboxed to a workspace directory with timeouts and a denylist for destructive patterns. Agents draft emails; humans send them. Health and legal agents carry explicit disclaimers in their prompts.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/kagithamanoj/botropolis.git
&lt;span class="nb"&gt;cd &lt;/span&gt;botropolis
pip &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="s2"&gt;".[dev]"&lt;/span&gt;
python examples/demo.py
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or skip the clone and talk to the CEO directly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="kn"&gt;from&lt;/span&gt; &lt;span class="n"&gt;botropolis.core.orchestrator&lt;/span&gt; &lt;span class="kn"&gt;import&lt;/span&gt; &lt;span class="n"&gt;CEO&lt;/span&gt;

&lt;span class="n"&gt;report&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;CEO&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;handle&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="s"&gt;Research vector databases and compare pricing&lt;/span&gt;&lt;span class="sh"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nf"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;report&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;summary&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The org chart grows by pull request. If you have ever wanted an agent with a job title, come add a department.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Botropolis is built and maintained by Manoj Kumar Kagitha, a Senior Cloud Engineer working on production cloud infrastructure. Nine papers, seven books, and now one company of bots.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>python</category>
      <category>opensource</category>
      <category>agents</category>
    </item>
  </channel>
</rss>
