Declare providers

Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs.

Like traditional Terraform configurations, Terraform component configurations declare which providers they require at the top level so that Terraform can install and use them.

Providers in component configurations differ from normal Terraform configurations in the following ways:

• Modules sourced by component blocks cannot declare their own providers. Instead, each component block accepts a top-level map of providers.
• You must pass arguments to providers using a config block.
• You define provider alias names for a provider in the header of its block.
• Providers in component configurations support the for_each meta-argument.

After defining your providers, you can use the Terraform Stacks to install the providers and create a provider lock file before you can use deploy your Stack.

Use a provider in a Stack

Define your Stack’s provider blocks in a top-level .tfcomponent.hcl file. The following example defines an AWS provider, specifies the aws provider version to use, configures the provider, and gives that provider configuration the alias name this:

required_providers {
    aws = {
        source  = "hashicorp/aws"
        version = "~> 5.7.0"
    }
}

provider "aws" "this" {
    config {
        region = var.region

        assume_role_with_web_identity {
            role_arn           = var.role_arn
            web_identity_token = var.identity_token
        }

        default_tags {
            tags = var.default_tags
        }
    }
}

When you define a provider, you must also add that provider to the required_providers block to ensure that Terraform knows which provider version to download.

For more details on the required_providers block in Stacks, refer to the required_providers block reference. For more details on the provider block in Stacks, refer to the provider block reference.

When you define a cloud provider, you often must authenticate that provider to ensure it can create infrastructure. Refer to Authenticate a Stack for details and examples.

After you define and configure your providers, you can pass that configuration to your Stack’s component blocks. A component block accepts a mapping of provider names to the provider(s) on which your component’s module relies.

After defining your Stack’s providers, pass each component block the provider(s) it requires. In the following example, the s3 component block is configured to use the aws provider and the aws.this provider configuration you defined earlier:

component "s3" {
    source = "./s3"
    inputs = {
        aws_region = var.aws_region
    }
    providers = {
        aws = provider.aws.this
    }
}

After configuring your provider, you can use the Terraform CLI to generate a provider lock file:

$ terraform stacks init

If you update a provider version and want to apply those changes to your Stack locally, re-run the terraform stacks init -upgrade command to update the provider lock file.

Dynamic provider configurations

Unlike traditional Terraform providers, Stack providers also support the for_each meta-argument. The for_each meta-argument lets you dynamically create provider configurations based on your inputs, which is beneficial for multi-region deployments.

In the following example, the aws provider uses the for_each meta-argument to create a separate provider configuration for each region:

required_providers {
    aws = {
        source  = "hashicorp/aws"
        version = "~> 5.7.0"
    }
}

provider "aws" "configurations" {
    for_each = var.regions

    config {
        region = each.value

        assume_role_with_web_identity {
            role_arn           = var.role_arn
            web_identity_token = var.identity_token
        }
    }
}

This setup example lets your Stack’s deployments use a separate AWS provider configuration for each region you defined in a regions variable.

In your component configuration, you can also use the for_each block to define configuration in with multiple AWS providers. In the following example, the s3 component block iterates through the var.regions variable and creates a component for each region, each with a unique AWS configuration for that region:

component "s3" {
    for_each = var.regions

    source = "./s3"

    inputs = {
        region = each.value
    }

    providers = {
        aws    = provider.aws.configurations[each.value]
        random = provider.random.this
    }
}

Provider support for Stack features

For most providers, the version you use does not affect your Stack’s functionality. However, only certain providers and versions support deferred changes. For example, you must use version 2.32.0 or higher of the Kubernetes provider to take advantage of deferred changes.

Check your provider in the Terraform registry for more information on versions that support various Stack features.

Provider lock file

A Stack cannot run without a lock file for its providers. After defining your providers, use the Terraform CLI to generate a .terraform.lock.hcl lock file. The terraform stacks init command creates and updates your .terraform.lock.hcl file:

$ terraform stacks init

The terraform stacks init command uses the required_providers block from your configuration to download the listed providers and compute the provider lock hashes. If you update your Stack’s providers, run the terraform stacks init -upgrade command to update your Stack’s lock file locally. For more details, refer to the terraform stacks commands.

Next steps

After declaring your providers, you can either finish defining the rest of your component configuration or define how Terraform deploys your Stack.