Configure provider sets

You can create sets of reusable provider block configurations and apply them to multiple no-code workspaces. When you apply the set, it inserts the provider block into the configuration, letting HCP Terraform organization administrators enforce best practices. Provider sets also let you deploy standard Terraform modules as no-code modules.

Overview

Before you create a provider set, it is important to understand how they interact with no-code workspaces, what happens when you change their configuration, and how HCP Terraform decides which to use when you apply multiple provider sets to the same no-code workspace.

Provider set behavior

Changing or deleting a provider set can cause unintended changes in your configuration. For example, if you configure which region a provider should deploy resources to, then later change that region in a provider set, every dependent no-code workspace may destroy every resource in the old region and recreate them in the new region.

Also, if you delete a provider set and your configuration does not contain a provider block to fall back on, HCP Terraform may not be able to complete any operation on the workspace, including destroy operations.

Provider configuration priority

HCP Terraform prioritizes and overwrites conflicting provider configuration in workspaces according to the following priority:

1. Organization-scoped provider set with Set as high priority configuration enabled
2. Project-scoped provider set with Set as high priority configuration enabled
3. Workspace-scoped provider set with Set as high priority configuration enabled
4. Non-priority workspace-scoped provider set
5. Non-priority project-scoped provider set
6. Non-priority organization-scoped provider set
7. Workspace Terraform configuration

For example, if the workspace defines a provider block and you apply a provider set for that same provider to the project the workspace is in, HCP Terraform prioritizes the provider set over the provider block in the Terraform configuration.

When an organization-scoped provider set configures a required provider for an existing no-code workspace, the provider set's configuration takes precedence over that workspace's configuration.

Note that you can only scope a provider set to a workspace when you use the API or the tfe provider. Refer to the Provider sets API reference documentation for more details.

Requirements

Provider sets require access to no-code modules, which are available in HCP Terraform Standard and Premium editions.

You must have Manage all projects and Manage all workspaces permissions to create and manage provider sets. Refer to Permissions for additional information.

If you self-host your HCP Terraform agents, provider sets require agent version v1.28.12 or later.

Create a provider set

Complete the following steps to create a new provider set:

1. Open your organization's Settings page.
2. Click Provider sets in the left navigation panel.
3. Click Create provider set.
4. Enter a Name for the provider set.
5. Optionally, enter a Description for the provider set.
6. Click Next.

The next screen lets you choose how you want to scope the provider set.

1. Choose Apply to all projects to enforce the provider in every no-code workspace in the organization, or choose Apply to specific projects and choose the projects from the Assign to projects dropdown.
2. Optionally, enable Set as high priority configuration to give this provider set priority over other provider sets. Refer to Provider configuration priority for more information.
3. Click Next.

The next screen lets you write your provider set configuration.

1. In the Input provider source field, enter the fully-qualified provider source address. For example, to use the AWS provider from the Terraform registry, enter registry.terraform.io/hashicorp/aws.

2. Enter your provider configuration in the HCL code block.

   The HCL code block expects a fully configured provider block. The following example creates a provider set to configure the AWS provider to set the region and assumed IAM role:

   provider "aws" {
       region = "us-east-2"
       assume_role {
           role_arn     = "arn:aws:iam::123456789012:role/ROLE_NAME"
           session_name = "SESSION_NAME"
           external_id  = "EXTERNAL_ID"
       }
   }
   

3. Click Create.

Update a provider set

Complete the following steps to update a provider set:

1. Open your organization's Settings page.
2. Click Provider sets in the left navigation panel.
3. Click the name of the provider set that you want to update.
4. Click the Actions dropdown, then click Edit.
5. Update the provider set with your desired changes.
6. Click Save.
7. Enter confirm in the Confirm edit textbox, then click Confirm to save your changes.

Delete a provider set

Complete the following steps to delete a provider set:

1. Open your organization's Settings page.
2. Click Provider sets in the left navigation panel.
3. Click the checkbox next to the provider sets you want to delete.
4. Click Delete.
5. Enter delete in the Confirm deletion textbox, then click Delete to delete the provider set.

Parameterize provider sets

You can write provider sets that require the no-code workspaces to define certain variables. The following example requires no-code workspaces to define a my_region variable:

provider "aws" {
    region = var.my_region
}

Refer to the variable precedence documentation for information on the order of variable priority.