medium riskcluster affecting~15 min

Runbook: Add a New Provider to the Configuration

1 · Prerequisites

Confirm every item is in place before any state change.

A Terraform configuration with a remote backend
A locked provider version
The credentials for the new provider

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· The new provider is available in the registry
· The credentials for the new provider are accessible
· The configuration is in Git
· A maintenance window is open (if production)

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Add the provider to required_providers
2Run terraform init to download the new provider
3Configure the provider
4Run terraform plan to verify the change
5Apply the change
6Document the addition

4 · Verification

Confirm the procedure actually fixed the problem.

✓The new provider is in the lockfile
✓The plan matches the expectation
✓The new resources are created
✓The addition is documented

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶If the add fails, remove the provider from required_providers
↶Run terraform init to remove the lockfile entry
↶Document the failed addition

6 · Escalation

When the runbook isn't enough, contact:

· If the new provider requires additional permissions, escalate to the security team
· If the credentials are invalid, escalate to the platform team

Purpose

This runbook walks through adding a new provider to an existing Terraform configuration. The procedure is the addition of a new dependency without disrupting existing resources.

When to use this runbook

Use this runbook when:

A new provider is required to manage a new resource type.
The configuration is being extended to support a new platform.
The team is adopting a new tool (e.g. moving from one cloud to another).

Procedure

Step 1: Add the provider to required_providers

Edit versions.tf:

terraform {
  required_version = ">= 1.9.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    # New provider
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

Step 2: Run terraform init

terraform init

The init downloads the new provider. The lockfile is updated.

Step 3: Configure the provider

Edit the configuration:

provider "azurerm" {
  features {}
  subscription_id = var.azurerm_subscription_id
}

Step 4: Add the new resources

# Add the new resources
vim main.tf

Step 5: Run terraform plan

terraform plan -out=new.tfplan

The plan should show the new resources.

Step 6: Review the plan

Review the plan:

The new resources are correct.
The existing resources are unchanged.
The plan summary matches the expectation.

Step 7: Apply the change

terraform apply new.tfplan

The change is applied.

Step 8: Verify the addition

terraform state list

The new resources are in the state.

Step 9: Document the addition

The addition is documented:

The new provider version.
The credentials used.
The new resources created.
The verification result.

Verification

The runbook is successful if:

The new provider is in the lockfile.
The plan matches the expectation.
The new resources are created.
The addition is documented.

Rollback

If the procedure fails:

Remove the provider from required_providers.
Run terraform init to remove the lockfile entry.
Run terraform plan to verify the plan is empty.
Document the failed addition.

Escalation

Escalate to:

Security team if the new provider requires additional permissions.
Platform team if the credentials are invalid.
Engineering manager if the addition fails repeatedly.

References

Required providers