What Is IaC? - Learning Module

Loading content...

0/273

Declarative vs Imperative

Two Ways to Express Intent

Consider two different ways to order food at a restaurant:

Imperative approach: "Walk to the kitchen. Take out a pan. Heat it to medium. Add two tablespoons of oil. Wait 30 seconds. Crack two eggs into the pan. Wait 3 minutes. Flip the eggs. Wait 1 minute. Slide onto a plate. Add salt."

Declarative approach: "I'd like two eggs, over easy, with a pinch of salt."

Both approaches can get you the same result, but they represent fundamentally different ways of expressing intent. The imperative approach describes how to achieve the outcome step by step. The declarative approach describes what outcome you want and trusts the executor (the chef) to figure out the steps.

This distinction lies at the heart of Infrastructure as Code. The approach you choose shapes everything: how you think about infrastructure, how your tools work, how errors are handled, and how changes are managed.

What You Will Learn

By the end of this page, you will deeply understand both the declarative and imperative paradigms, their implementation in real IaC tools, the technical trade-offs between them, and how to choose the right approach for different scenarios. You'll also explore hybrid approaches that combine both paradigms.

The Imperative Paradigm

Imperative infrastructure code specifies the exact sequence of steps required to achieve a desired state. You tell the system how to do something, not just what you want. The code reads like a recipe or a set of instructions.

Characteristics of Imperative IaC:

Imperative Approach Characteristics

•Step-by-Step Execution — Commands execute in sequence, each step building on the previous
•Explicit Control Flow — You control if/else branching, loops, and execution order
•Manual State Management — You must track what exists and handle create vs. update logic
•Procedural Logic — Code describes the process, not the end state
•Familiar Programming Model — Feels like traditional programming with variables and functions

imperative-infrastructure.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#!/bin/bash
# Imperative infrastructure provisioning example
 
# Step 1: Check if VPC exists
VPC_ID=$(aws ec2 describe-vpcs \
  --filters "Name=tag:Name,Values=my-vpc" \
  --query "Vpcs[0].VpcId" --output text)
 
if [ "$VPC_ID" = "None" ] || [ -z "$VPC_ID" ]; then
    # Step 2a: Create VPC if it doesn't exist
    echo "Creating VPC..."
    VPC_ID=$(aws ec2 create-vpc \
      --cidr-block 10.0.0.0/16 \
      --query "Vpc.VpcId" --output text)
    
    # Step 3: Tag the VPC
    aws ec2 create-tags \
      --resources $VPC_ID \
      --tags Key=Name,Value=my-vpc
    
    echo "Created VPC: $VPC_ID"
else
    echo "VPC already exists: $VPC_ID"
fi
 
# Step 4: Check if subnet exists
SUBNET_ID=$(aws ec2 describe-subnets \
  --filters "Name=vpc-id,Values=$VPC_ID" \
           "Name=tag:Name,Values=my-subnet" \
  --query "Subnets[0].SubnetId" --output text)
 
if [ "$SUBNET_ID" = "None" ] || [ -z "$SUBNET_ID" ]; then
    # Step 5a: Create subnet if it doesn't exist
    echo "Creating subnet..."
    SUBNET_ID=$(aws ec2 create-subnet \
      --vpc-id $VPC_ID \
      --cidr-block 10.0.1.0/24 \
      --query "Subnet.SubnetId" --output text)
    
    aws ec2 create-tags \
      --resources $SUBNET_ID \
      --tags Key=Name,Value=my-subnet
    
    echo "Created subnet: $SUBNET_ID"
else
    echo "Subnet already exists: $SUBNET_ID"
fi
 
# Continue for each resource...
# Note: This script must handle every edge case manually

The Challenges with Imperative IaC:

While imperative code can be powerful, it comes with significant challenges:

Imperative Approach Challenges

•Idempotency is Your Responsibility — You must manually check if resources exist before creating them. Running the script twice could create duplicates or errors.
•State Tracking is Manual — There's no built-in mechanism to know what you've created. You must query the cloud API each time.
•Updates are Complex — Changing a resource often requires different API calls than creating it. You need if/else logic for every scenario.
•Deletions are Dangerous — Removing resources requires explicit reverse logic. It's easy to leave orphaned resources or accidentally delete the wrong thing.
•Ordering Dependencies — You must manually ensure resources are created in the correct order (VPC before subnet, subnet before EC2, etc.).
•Error Recovery is Hard — If a script fails halfway through, you may have partial infrastructure. Rerunning could cause conflicts.

The Real Cost of Imperative IaC

Teams that use purely imperative scripts for infrastructure often find that 60-80% of the code is error handling, state checking, and update logic—not actual infrastructure definition. The infrastructure intent gets buried in procedural complexity.

The Declarative Paradigm

Declarative infrastructure code describes the desired end state without specifying how to achieve it. You tell the system what you want, and the tool figures out the steps to get there.

Characteristics of Declarative IaC:

Declarative Approach Characteristics

•State Description — Code defines what should exist, not how to create it
•Automatic State Reconciliation — The tool compares desired state to actual state and determines necessary changes
•Built-in Idempotency — Running the same code multiple times always produces the same result
•Dependency Resolution — The tool automatically determines the correct order of operations
•Predictable Execution — You can preview changes before applying them

declarative-infrastructure.tf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# Declarative infrastructure provisioning example (Terraform)
 
# Declare what you want - the VPC
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
  
  tags = {
    Name = "my-vpc"
  }
}
 
# Declare what you want - the subnet
resource "aws_subnet" "main" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.0.1.0/24"
  
  tags = {
    Name = "my-subnet"
  }
}
 
# Declare what you want - the security group
resource "aws_security_group" "web" {
  name        = "web-sg"
  description = "Allow web traffic"
  vpc_id      = aws_vpc.main.id
  
  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
  
  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}
 
# Terraform will:
# 1. Automatically determine dependencies (subnet needs vpc first)
# 2. Compare to existing state and only make necessary changes
# 3. Handle create vs update vs delete automatically
# 4. Execute in the correct order

How Declarative Tools Work:

Declarative IaC tools follow a consistent workflow:

Parse — Read your configuration files and build a resource graph
State — Load the current state (from a state file or by querying the API)
Diff — Compare desired state to actual state
Plan — Generate a list of changes needed to reach desired state
Apply — Execute the changes in the correct dependency order
Update State — Record the new state for future comparisons

This workflow enables powerful capabilities that are impossible in purely imperative approaches.

The Power of the Plan

The 'plan' step is revolutionary for infrastructure safety. Before making any changes, you can see exactly what will be created, modified, or destroyed. This eliminates the fear of running infrastructure code—you always know what's going to happen.

Side-by-Side Comparison

Let's examine how the same infrastructure problem is expressed in both paradigms, highlighting the fundamental differences:

Imperative Approach

•What the code says: 'Execute these steps in this order'
•Running again: May fail, create duplicates, or have no effect—depends on code quality
•Changing CIDR: Requires update logic or destroy-and-recreate workflow
•Deleting resources: Must write explicit deletion script
•Understanding state: Query cloud API or maintain external tracking
•Rollback: Write reverse script or restore from backups

Declarative Approach

•What the code says: 'This is what should exist'
•Running again: Always safe—produces same result (idempotent)
•Changing CIDR: Change value in code; tool calculates required changes
•Deleting resources: Remove from code; tool detects and destroys
•Understanding state: Read the code or query the state file
•Rollback: Revert code in Git; apply previous version

Detailed Paradigm Comparison
Aspect	Imperative	Declarative
Mental Model	Recipe/Instructions	Blueprint/Specification
Primary Verb	Do this	Be this
State Management	Manual/External	Built-in
Dependency Ordering	Explicit in code	Automatic from references
Idempotency	Developer responsibility	Tool guarantee
Change Detection	Manual checks	Automatic diffing
Learning Curve	Familiar (scripting)	New paradigm (may be unfamiliar)
Flexibility	Maximum (full programming)	Constrained to tool's model
Predictability	Depends on code quality	High (deterministic)
Error Recovery	Complex (partial states)	Simpler (retry from state)

Neither is Absolutely Better

The declarative approach has become dominant in IaC because its properties (idempotency, state management, predictability) align well with infrastructure's needs. However, imperative approaches shine in scenarios requiring complex logic, one-time migrations, or operations that don't fit the declarative model.

State Management: The Critical Difference

The most profound difference between imperative and declarative approaches is state management. This difference has cascading effects on everything else.

The State Problem:

Infrastructure exists in the cloud. To manage it effectively, your tools need to know:

What resources currently exist?
What are their current configurations?
What resources are managed by this code vs. created manually or by other systems?
What is the relationship between resources (dependencies)?

Declarative tools solve this with explicit state files that track all managed resources.

terraform.tfstate (simplified)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "version": 4,
  "terraform_version": "1.5.0",
  "resources": [
    {
      "type": "aws_vpc",
      "name": "main",
      "instances": [
        {
          "attributes": {
            "id": "vpc-12345abcde",
            "cidr_block": "10.0.0.0/16",
            "tags": {
              "Name": "my-vpc"
            }
          }
        }
      ]
    },
    {
      "type": "aws_subnet",
      "name": "main",
      "instances": [
        {
          "attributes": {
            "id": "subnet-67890fghij",
            "vpc_id": "vpc-12345abcde",
            "cidr_block": "10.0.1.0/24"
          }
        }
      ]
    }
  ]
}

How State Enables Powerful Operations:

State-Enabled Capabilities

•Drift Detection — Compare state file to reality and detect manual changes made outside IaC
•Dependency Graph — State tracks which resources reference others, enabling correct ordering
•Resource Identity — Link your code's resource names to actual cloud resource IDs
•Change Calculation — Know exactly what needs to change without querying every resource
•Safe Destruction — Know which resources are managed and can be safely deleted
•Refactoring Support — Rename or reorganize code while maintaining identity of existing resources

State is Critical Infrastructure

The state file becomes critical infrastructure itself. If you lose the state file, your tool loses track of what it manages. This is why production IaC uses remote state backends (S3, Azure Blob Storage, Terraform Cloud) with locking and versioning, not local files.

Real-World Tools and Their Paradigms

Different IaC tools embody these paradigms to varying degrees. Understanding where each tool falls helps you select the right tool for your needs.

IaC Tools and Their Paradigms
Tool	Primary Paradigm	Notes
Terraform	Declarative	HCL language describes desired state; plan/apply workflow
CloudFormation	Declarative	YAML/JSON templates; AWS manages state internally
Pulumi	Declarative (with imperative feel)	Uses general-purpose languages; manages state like Terraform
Azure Bicep	Declarative	DSL compiled to ARM templates; Azure manages state
Ansible	Primarily Imperative	Playbooks run tasks in order; idempotent modules mimic declarative behavior
Chef	Declarative (eventually consistent)	Recipes describe desired state; client periodically converges
Shell Scripts	Imperative	Full control; no built-in state management or idempotency
AWS CDK	Declarative (with imperative constructs)	TypeScript/Python compiles to CloudFormation; programmatic abstractions

The Pulumi Approach: Declarative Semantics with Imperative Syntax

Pulumi represents an interesting hybrid. It uses general-purpose programming languages (TypeScript, Python, Go, C#) which feel imperative—you write functions, loops, and conditionals. But the semantics are declarative—the code describes desired state, and Pulumi calculates changes.

This gives you:

The safety and predictability of declarative IaC
The expressiveness and tooling of real programming languages
The abstraction capabilities of functions, classes, and modules

pulumi-example.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws"; 
 
// This looks imperative but behaves declaratively
// Pulumi tracks what this code declares, not what it executes
 
const vpc = new aws.ec2.Vpc("main", {
    cidrBlock: "10.0.0.0/16",
    tags: { Name: "my-vpc" },
});
 
// You can use loops - still declarative
const subnets: aws.ec2.Subnet[] = [];
for (let i = 0; i < 3; i++) {
    subnets.push(new aws.ec2.Subnet(`subnet-${i}`, {
        vpcId: vpc.id,
        cidrBlock: `10.0.${i}.0/24`,
        availabilityZone: `us-east-1${String.fromCharCode(97 + i)}`,
    }));
}
 
// You can use conditionals
const config = new pulumi.Config();
if (config.getBoolean("enableNat")) {
    const natGw = new aws.ec2.NatGateway("nat", {
        subnetId: subnets[0].id,
        // ... other config
    });
}
 
// Exports work like Terraform outputs
export const vpcId = vpc.id;
export const subnetIds = subnets.map(s => s.id);

Choosing Based on Team Skills

If your team is strong in TypeScript/Python but unfamiliar with HCL, Pulumi might enable faster adoption. If your team values the explicit constraint of HCL's declarative-only syntax, Terraform enforces cleaner practices. There's no universally correct choice.

When to Use Each Approach

While declarative IaC has become the default for most infrastructure management, imperative approaches remain valuable in specific scenarios. Understanding when to apply each helps you make better tooling decisions.

Use Declarative When

•Managing long-lived infrastructure — VPCs, databases, Kubernetes clusters that exist for months/years
•Team collaboration — Multiple engineers working on shared infrastructure
•Compliance requirements — Need audit trails and predictable changes
•Standard cloud resources — Compute, networking, storage, databases
•Multiple environments — Dev/staging/prod that should match
•GitOps workflows — Automated deployment from version control

Use Imperative When

•One-time migrations — Moving data between systems, one-time cleanup tasks
•Complex conditionals — Logic that doesn't map well to declarative models
•API calls beyond IaC scope — Configuring SaaS applications, custom integrations
•Emergency operations — Quick manual interventions during incidents
•Bootstrapping — Initial setup that creates prerequisites for declarative IaC
•Unsupported resources — Things your declarative tool doesn't support yet

A Common Pattern: Declarative Core with Imperative Extensions

Mature IaC practices often combine both:

Core infrastructure (90%+) is managed declaratively with Terraform/CloudFormation
Provisioners and local-exec handle imperative tasks that must run during provisioning
Separate scripts handle one-time migrations and operations
CI/CD pipelines orchestrate the declarative tools imperatively

This hybrid approach captures the benefits of both paradigms.

Minimize Imperative Within Declarative

Terraform's 'local-exec' provisioner and similar escape hatches should be used sparingly. Every imperative section is a place where idempotency, state management, and predictability degrade. If you find yourself using many provisioners, consider whether a different tool might be better suited for that task.

Common Misconceptions

Several misconceptions cloud the declarative vs. imperative discussion. Let's address them directly:

Misconceptions Debunked

•'Declarative means you can't use logic' — Wrong. Declarative tools support conditionals, loops, and functions. They just apply logic to determine what to declare, not how to create it.
•'Imperative is always faster to write' — Initially, yes. Long-term, no. Imperative scripts accumulate complexity handling edge cases that declarative tools handle automatically.
•'Declarative tools can do everything' — They can't. Some operations (data migrations, API calls to arbitrary services) require imperative approaches.
•'You must choose one paradigm exclusively' — Best practices combine both, using each where appropriate.
•'Declarative is harder to learn' — The paradigm shift takes time, but reduced complexity makes ongoing work easier.
•'Ansible is purely imperative' — Ansible's modules are designed to be idempotent, giving declarative-like behavior even though playbooks are executed imperatively.

The Learning Investment

Engineers coming from scripting backgrounds often initially resist declarative IaC. The lack of explicit control feels uncomfortable. But once the paradigm shift happens, most engineers never want to go back. The peace of mind from automatic state management and idempotency is transformative.

Summary: Declarative vs Imperative

We've explored both paradigms in depth. Let's consolidate the key insights:

Key Takeaways

•Imperative describes how; declarative describes what — The fundamental distinction shaping all other differences.
•Declarative provides automatic idempotency — The tool guarantees running code multiple times produces the same result.
•State management is the critical differentiator — Declarative tools track state, enabling drift detection, change planning, and safe operations.
•Declarative dominates for ongoing infrastructure — Long-lived resources benefit from declarative management.
•Imperative excels for one-time operations — Migrations, complex logic, and edge cases may require imperative approaches.
•Best practices combine both paradigms — Use declarative as the foundation; use imperative for what doesn't fit.

What's Next:

Now that we understand the paradigms for writing infrastructure code, we'll explore how to manage that code over time. Version Control for Infrastructure examines how Git workflows, branching strategies, and code review transform infrastructure management—enabling collaboration, audit trails, and safe changes.

Page Complete

You now understand both the declarative and imperative paradigms for Infrastructure as Code, their technical implementations, trade-offs, and appropriate use cases. This knowledge will help you select the right tools and write infrastructure code that leverages each paradigm's strengths.