Resource Lifecycle

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hashicorp/terraform/llms.txt

Use this file to discover all available pages before exploring further.

​

Lifecycle Overview

​

State Values Through Lifecycle

resource "aws_instance" "example" {
  ami           = "ami-123456"
  instance_type = "t2.micro"
  tags = {
    Name = "example-instance"
  }
}

{
  "ami": "ami-123456",
  "instance_type": "t2.micro",
  "id": "i-1234567890abcdef0",
  "tags": {"Name": "example-instance"},
  "public_ip": "52.1.2.3"
}

{
  "ami": "ami-123456",         // From config
  "instance_type": "t2.micro",  // From config  
  "id": "i-1234567890abcdef0",  // From prior state (computed)
  "tags": {"Name": "example-instance"},
  "public_ip": "52.1.2.3"      // From prior state (computed)
}

{
  "ami": "ami-123456",
  "instance_type": "t2.micro",
  "id": "<unknown>",           // Will be assigned
  "tags": {"Name": "example-instance"},
  "public_ip": "<unknown>"     // Will be assigned
}

{
  "ami": "ami-123456",
  "instance_type": "t2.micro",
  "id": "i-abcdef1234567890",
  "tags": {"Name": "example-instance"},
  "public_ip": "52.5.6.7"
}

​

Phase 1: Previous Run State

​

UpgradeResourceState

• Accept raw state data (any format)
• Identify schema version
• Transform to current schema
• Do not detect external changes
• Do not call external APIs

func (p *Provider) UpgradeResourceState(
    req UpgradeResourceStateRequest,
) UpgradeResourceStateResponse {
    // Decode old state
    var oldState OldResourceStateV2
    json.Unmarshal(req.RawState.JSON, &oldState)
    
    // Transform to current schema
    newState := ResourceState{
        ID:          oldState.ID,
        Name:        oldState.Name,
        NewField:    "default", // Add new field
        RenamedOld:  oldState.OldFieldName, // Rename
    }
    
    return UpgradeResourceStateResponse{
        UpgradedState: newState,
    }
}

​

ReadResource

// In state
{"json_config": "{\"a\": 1}"}

// From API  
{"json_config": "{\"a\":1}"}

// In state
{"instance_type": "t2.micro"}

// From API
{"instance_type": "t2.small"}

• Write-only attributes: Cannot detect drift (e.g., passwords)
• Resource deleted: Return null state
• Partial read failure: Return best-effort state + diagnostics

​

Phase 2: Planning

​

First PlanResourceChange (Planning Phase)

• prior_state: Current infrastructure state
• proposed_new_state: Terraform Core’s merge suggestion
• config: User configuration (may have unknown values)

1. Preserve non-null config values exactly
2. Use proposed_new_state as starting point
3. Mark unpredictable attributes as unknown
4. Return known values where possible
5. Indicate required replacements via requires_replace

func (p *Provider) PlanResourceChange(
    req PlanResourceChangeRequest,
) PlanResourceChangeResponse {
    planned := req.ProposedNewState.Copy()
    
    // Preserve config values
    for attr, val := range req.Config.Attributes {
        if !val.IsNull() {
            planned.Attributes[attr] = val
        }
    }
    
    // Mark computed values as unknown if dependencies changed
    if req.Config.AMI != req.PriorState.AMI {
        planned.PublicIP = cty.UnknownVal(cty.String)
        planned.ID = cty.UnknownVal(cty.String)
    }
    
    // Indicate if replacement needed
    var requiresReplace []cty.Path
    if req.Config.AMI != req.PriorState.AMI {
        requiresReplace = append(requiresReplace,
            cty.GetAttrPath("ami"))
    }
    
    return PlanResourceChangeResponse{
        PlannedState:     planned,
        RequiresReplace:  requiresReplace,
    }
}

• Non-null config values must appear unchanged in plan
• Null optional+computed attributes may be set to any value
• Planned known values cannot change in ApplyResourceChange

​

Second PlanResourceChange (Apply Phase)

• All config values are known (dependencies applied)
• Can refine previous unknowns to known values
• Can replace unknowns with better unknowns (refinements)
• Cannot change previously known values

• Known values from initial plan must be identical
• Unknown values can become known or stay unknown
• Unknown values can gain refinements

// Initial Planned State
{
  "url": "<unknown string>"
}

// Final Planned State (after config becomes known)
{
  "url": "<unknown string with prefix 'https://'>"
}

​

Phase 3: Applying

​

ApplyResourceChange

1. Make actual infrastructure changes
2. Preserve all known values from planned_state
3. Replace unknown values with actual results
4. Return all-known state (no unknowns allowed)
5. Return error if actual result doesn’t match plan

func (p *Provider) ApplyResourceChange(
    req ApplyResourceChangeRequest,
) ApplyResourceChangeResponse {
    var newState ResourceState
    
    switch req.PlannedState.ID.IsNull() {
    case true:
        // Create new resource
        resp := api.CreateInstance(
            AMI:          req.PlannedState.AMI,
            InstanceType: req.PlannedState.InstanceType,
        )
        newState = ResourceState{
            ID:           resp.ID,          // Was unknown
            AMI:          req.PlannedState.AMI, // Known in plan
            InstanceType: req.PlannedState.InstanceType,
            PublicIP:     resp.PublicIP,    // Was unknown
        }
        
    case false:
        // Update existing resource
        api.UpdateInstance(
            ID:  req.PriorState.ID,
            AMI: req.PlannedState.AMI,
        )
        newState = req.PlannedState // Already fully known
    }
    
    return ApplyResourceChangeResponse{
        NewState: newState,
    }
}

• Return partial new state showing what was created
• Include diagnostics explaining failure
• Terraform saves partial state for recovery

​

Special Cases

​

Import Workflow

• Accept provider-defined ID string
• Query external system
• Return minimal state for ReadResource to complete
• May return partial state for write-only attributes

// Import stub (partial)
{
  "id": "i-abc123",
  "password": null  // Write-only, cannot retrieve
}

// After ReadResource  
{
  "id": "i-abc123",
  "ami": "ami-123456",
  "instance_type": "t2.micro",
  "password": null  // User must provide in config
}

​

Replace Triggered By

resource "aws_instance" "example" {
  ami = aws_ami.latest.id
  
  lifecycle {
    replace_triggered_by = [aws_ami.latest]
  }
}

1. Terraform marks aws_instance.example for replacement
2. PlanResourceChange receives indication of forced replacement
3. Provider plans destroy + create even if config unchanged

​

Create Before Destroy

resource "aws_instance" "example" {
  lifecycle {
    create_before_destroy = true
  }
}

1. Create new instance
2. Update dependencies to point to new instance
3. Destroy old instance

​

Validation Rules

​

ValidateResourceConfig

// Called multiple times with increasing config completeness
validate(config_with_unknowns)     // OK
validate(config_mostly_known)      // OK
validate(config_fully_known)       // Must pass

• Should tolerate unknown values
• Report errors for definitely-invalid configs
• May return warnings for potentially-invalid configs

​

PlanResourceChange

Rule: Non-null config values must be preserved

config.ami = "ami-123456"

planned_state.ami = "ami-123456"  ✓ Correct
planned_state.ami = "ami-789012"  ✗ Invalid
planned_state.ami = unknown       ✗ Invalid

Rule: Optional+computed null in config → provider decides

config.public_ip = null
prior_state.public_ip = "52.1.2.3"

planned_state.public_ip = "52.1.2.3"  ✓ Preserve
planned_state.public_ip = unknown      ✓ Will change
planned_state.public_ip = "52.5.6.7"   ✓ Provider knows

Rule: Second plan must not change known values

initial_plan.ami = "ami-123456"

final_plan.ami = "ami-123456"  ✓ Identical
final_plan.ami = "ami-789012"  ✗ Changed known value

initial_plan.public_ip = unknown
final_plan.public_ip = "52.1.2.3"     ✓ Refined unknown
final_plan.public_ip = unknown         ✓ Still unknown  

​

ApplyResourceChange

Rule: New state must match planned state for known values

planned_state.ami = "ami-123456"
new_state.ami = "ami-123456"  ✓ Matches
new_state.ami = "ami-789012"  ✗ Provider changed value!

planned_state.public_ip = unknown
new_state.public_ip = "52.1.2.3"  ✓ Resolved unknown
new_state.public_ip = unknown      ✗ Must be known now!

​

Nested Blocks

resource "aws_instance" "example" {
  ebs_block_device {  # Block (not attribute)
    device_name = "/dev/sda1"
  }
}

• Number of blocks fixed during planning
• Cannot add/remove blocks during apply
• Each block must have corresponding planned block

resource "compute_instance" "example" {
  network_interface {  # User-specified
    name = "eth0"
  }
  
  # Separate attribute for provider-created interfaces
  all_network_interfaces = [  # Computed attribute
    {name = "eth0"},           # From block
    {name = "eth1"}            # Auto-created by provider
  ]
}

​

Further Reading