Declare providers

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

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

Providers in Stack 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 attributes to providers using a config block.
• You define provider alias names in the header of its block.
• Providers in Stack configurations support the for_each meta argument.

After defining your providers, you must use the Terraform Stacks CLI 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 .tfstack.hcl file. The following example file named providers.tfstack.hcl defines an AWS provider.

# providers.tfstack.hcl

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

# Setting "this" as the alias name
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 a required_providers to ensure the Terraform Stacks CLI knows which provider version to download. For more details on Stack-specific provider syntax, refer to the Stack configuration file reference.

You must authenticate that provider to ensure the provider can create your infrastructure. Refer to Authenticate a Stack for details and examples.

After you define your providers, you can pass them 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.

# components.tfstack.hcl

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

After configuring your provider, you can use the Terraform Stacks CLI to generate a 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.

# providers.tfstack.hcl

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


provider "aws" "configurations" {
# This provider configuration iterates through and creates a configuration
# for each region.
    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 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 could the for_each block to define configuration in with multiple AWS providers.

# components.tfstack.hcl

component "s3" {
    for_each = var.regions

    source = "./s3"

    inputs = {
        region = each.value
    }

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

The components in this example use the for_each meta-argument to deploy their Terraform module in the region for the current deployment.

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 Stacks CLI to generate a .terraform.lock.hcl lock file. The tfstacks providers lock command creates and updates your .terraform.lock.hcl file.

$ tfstacks providers lock

The tfstacks providers lock command uses the required_providers block from your configuration to download the listed providers and compute the provider lock hashes. The tfstacks providers lock command only checks the required_providers block, so you must list all of the providers you use in that block to ensure that the tfstacks CLI can find them.

If you update your Stack’s providers, you must rerun the tfstacks providers lock command to update your Stack’s providers lock file. For more details, refer to Terraform Stacks CLI.

Next steps

After declaring your providers, you can either finish defining the rest of your Stack configuration or move on to define your Stack’s deployment configuration.