Andrew Mercer
on this page

A provider is a separate binary (a gRPC plugin) that knows how to talk to one API: Azure Resource Manager, AWS, Kubernetes, GitLab, libvirt. Terraform core builds the graph and the plan; providers do the CRUD.

Page Covers
This page Declaring, pinning, installing, configuring
libvirt (KVM) Worked example: multiple KVM VMs with cloud-init

Declaring providers

terraform {
  required_version = "~> 1.16"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"     # <hostname>/<namespace>/<type>; hostname defaults to registry.terraform.io
      version = "~> 4.40"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.5"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.7"
    }
  }
}
  • The local name (the map key, azurerm) is what you use in provider "azurerm" {} blocks and resource type prefixes.
  • The source address identifies the provider globally. OpenTofu resolves the same addresses against registry.opentofu.org, which mirrors most providers.
  • Every module declares the providers it uses, with a version range. Only the root module pins tightly (via the lock file) and configures them.

Version constraints

Constraint Allows
"4.42.0" / "= 4.42.0" Exactly that
"~> 4.42.0" 4.42.x
"~> 4.42" 4.42 through 4.x (not 5.0)
">= 4.0, < 5.0" Same idea, explicit; good for modules
"!= 4.43.1" Exclude a known-bad release

The dependency lock file

terraform init writes .terraform.lock.hcl:

provider "registry.terraform.io/hashicorp/azurerm" {
  version     = "4.42.0"
  constraints = "~> 4.40"
  hashes = [
    "h1:...",   # hash of the unpacked package for one platform
    "zh:...",   # hashes of each platform's zip, from the signed SHA256SUMS
  ]
}
  • Commit it. It's what makes every init (yours, CI's, a colleague's) install the same provider build, and it fails init if a package doesn't match a recorded hash.
  • It records providers only, not modules.
  • Upgrades are explicit: terraform init -upgrade picks the newest version allowed by constraints and rewrites the file. Do it in its own MR.
  • Multi-platform hashes: if you init on Linux, the file may only have the linux_amd64 h1: hash, and a Mac user's init fails verification. Pre-populate:

bash terraform providers lock -platform=linux_amd64 -platform=linux_arm64 -platform=darwin_arm64 -platform=windows_amd64

  • terraform init -lockfile=readonly in CI fails instead of silently updating the file.

Installation

Plugin cache

Every root module downloads its own copy of every provider into .terraform/providers. AzureRM is hundreds of MB. Share a cache:

# ~/.terraformrc
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

or export TF_PLUGIN_CACHE_DIR=~/.terraform.d/plugin-cache. In CI, point it inside the project directory and cache it between jobs. Terragrunt has its own provider cache server (--provider-cache) for run --all.

Mirrors and air-gapped installs

# Build a filesystem mirror for the platforms you need
terraform providers mirror -platform=linux_amd64 /srv/terraform-mirror
# CLI config: use the mirror, never the internet, for these providers
provider_installation {
  filesystem_mirror {
    path    = "/srv/terraform-mirror"
    include = ["registry.terraform.io/hashicorp/*", "registry.terraform.io/azure/*"]
  }
  direct {
    exclude = ["registry.terraform.io/hashicorp/*", "registry.terraform.io/azure/*"]
  }
}

A network_mirror (Artifactory, Nexus, a static HTTPS site) works the same way for teams. Restricting sources is also a supply-chain control.

Dev overrides (developing a provider)

# ~/.terraformrc
provider_installation {
  dev_overrides {
    "registry.terraform.io/acme/internal" = "/home/andrew/go/bin"
  }
  direct {}
}

Terraform uses the local binary and prints a warning on every command. init isn't needed for overridden providers.

Configuring providers

provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy    = false
      recover_soft_deleted_key_vaults = true
    }
    resource_group {
      prevent_deletion_if_contains_resources = true
    }
  }

  subscription_id                 = var.subscription_id    # required since azurerm 4.0
  resource_provider_registrations = "none"                 # replaces the removed skip_provider_registration
  storage_use_azuread             = true                   # data-plane storage calls via Entra ID
}

Credentials

Never put credentials in provider blocks. Every major provider reads them from the environment, in a documented precedence. For AzureRM:

Method Env vars Use
Azure CLI (none, uses az login) Local development
OIDC / workload identity federation ARM_USE_OIDC=true, ARM_CLIENT_ID, ARM_TENANT_ID, ARM_OIDC_TOKEN CI
Managed identity ARM_USE_MSI=true (+ ARM_CLIENT_ID for user-assigned) Self-hosted runners/agents in Azure
Client secret ARM_CLIENT_SECRET Avoid
Client certificate ARM_CLIENT_CERTIFICATE_PATH Legacy

AWS: the standard credential chain (AWS_PROFILE, SSO, web identity, instance roles). Google: Application Default Credentials. Kubernetes: kubeconfig or exec plugins.

Aliases and multiple configurations

Covered in meta-arguments and advanced.

AzureRM vs AzAPI

hashicorp/azurerm Azure/azapi
Model Hand-written resources per service Thin layer over ARM REST: any resource type + API version
New Azure features When someone implements them Day one (any API version)
Schema validation Rich, per resource From the ARM API schema; HCL objects as body
Plan diffs Curated Raw properties
Use for Almost everything Preview features, properties azurerm lacks, ARM-only resources
resource "azapi_update_resource" "app_feature" {
  type        = "Microsoft.Web/sites@2024-04-01"
  resource_id = azurerm_linux_web_app.this.id
  body = {
    properties = {
      someNewProperty = true
    }
  }
}

azapi_update_resource patches properties on a resource azurerm manages, which is often the cleanest way to use a feature before azurerm supports it. Remove it once azurerm catches up.

Providers worth knowing

Provider For
hashicorp/azurerm, Azure/azapi, hashicorp/azuread Azure resources, ARM gaps, Entra ID objects
hashicorp/aws, hashicorp/google AWS, GCP
hashicorp/kubernetes, hashicorp/helm Cluster objects and Helm releases (separate state from the cluster)
gitlabhq/gitlab, integrations/github Projects, groups, CI variables, branch protection as code
hashicorp/random Random names, passwords (prefer the ephemeral variant for secrets), pets
hashicorp/time time_sleep for eventual consistency, time_rotating for rotation
hashicorp/tls Keys and certificates (private keys end up in state)
hashicorp/http Read a URL (plan-time execution; see security)
hashicorp/local Write files (inventories for Ansible, kubeconfigs)
hashicorp/external Run a program and read JSON (last resort; plan-time code execution)
hashicorp/cloudinit Multi-part cloud-init documents
dmacvicar/libvirt KVM/QEMU (walkthrough)
bpg/proxmox, Telmate/proxmox Proxmox VE
hashicorp/dns, cloudflare/cloudflare DNS records

null_resource (hashicorp/null) is superseded by the built-in terraform_data. The hashicorp/template provider is archived; use templatefile().

Upgrading providers

  1. Read the changelog and, for majors, the upgrade guide (AzureRM 3.x → 4.x changed defaults, removed arguments like skip_provider_registration, and made subscription_id required).
  2. Fix deprecation warnings while still on the old major. They tell you exactly what will break.
  3. Upgrade shared modules first, release them, then roll consumers forward (shared modules).
  4. terraform init -upgrade, plan every environment, look for unexpected replacements.
  5. Commit the updated lock file.

Writing your own provider

Use the Terraform Plugin Framework (Go). It's the current SDK; the older SDKv2 is maintenance-only. A provider is worth writing when you have an internal API (a CMDB, an IPAM, your own platform's API) that teams currently drive with scripts. Start from the terraform-provider-scaffolding-framework template, test with dev_overrides, and publish to your private registry. OpenTofu loads the same providers.

in this section
* terraform for libvirt (kvm virtual machines)