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 inprovider "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 failsinitif a package doesn't match a recorded hash. - It records providers only, not modules.
- Upgrades are explicit:
terraform init -upgradepicks the newest version allowed by constraints and rewrites the file. Do it in its own MR. - Multi-platform hashes: if you
initon Linux, the file may only have thelinux_amd64h1:hash, and a Mac user'sinitfails verification. Pre-populate:
bash
terraform providers lock -platform=linux_amd64 -platform=linux_arm64 -platform=darwin_arm64 -platform=windows_amd64
terraform init -lockfile=readonlyin 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¶
- Read the changelog and, for majors, the upgrade guide (AzureRM 3.x → 4.x changed defaults, removed arguments like
skip_provider_registration, and madesubscription_idrequired). - Fix deprecation warnings while still on the old major. They tell you exactly what will break.
- Upgrade shared modules first, release them, then roll consumers forward (shared modules).
terraform init -upgrade, plan every environment, look for unexpected replacements.- 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.