Scale operations with HCP Terraform self-service workflows

Managing teams and resources at scale requires navigating conflicting priorities: deployment teams want to move quickly, while platform operators want to enforce best practices and security standards. HCP Terraform's self-service workflows allow teams to quickly deploy common infrastructure within access-scoped projects.

In this tutorial, you will build a landing zone by creating a project, a team, and a variable set with your cloud credentials. Then, you will use no-code modules to enable self-service workflows. After that, you will follow the lifecycle of a module by upgrading the no-code module in your private registry, deprecating a module version, and then revoking it to prevent users from deploying it in the future. Finally, you will use team notifications to issue change requests and the HCP Terraform explorer to review your organization's usage.

Prerequisites

This tutorial assumes that you are familiar with the Terraform and HCP Terraform workflows. If you are new to Terraform, complete the Get Started collection first. If you are new to HCP Terraform, complete the HCP Terraform Get Started tutorials first.

To complete this tutorial, you need an HCP Terraform account.

You will use an interactive lab environment in your web browser to create your HCP Terraform organization.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Start interactive lab

Click the Start interactive lab to open the lab.

Create organization

The interactive lab requires your HCP Terraform user token to create a temporary HCP Terraform Premium organization.

To create a user token, navigate to your Account Settings(opens in new tab), then click Tokens in the left navigation panel.

Click Create an API token, set the description to Self-service API and expiration to 1 day.

Copy the generated user token and keep it somewhere safe. HCP Terraform will not show this value again.

In the interactive lab, run the terraform login command. When Terraform prompts you to confirm that you want to proceed, respond with yes. Terraform then asks for your user token. Provide the token created in the previous step and press Enter.

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
    /root/.terraform.d/credentials.tfrc.json

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

  Enter a value: yes


---------------------------------------------------------------------------------

Open the following URL to access the tokens page for app.terraform.io:
    https://app.terraform.io/app/settings/tokens?source=terraform-login


---------------------------------------------------------------------------------

Generate a token using your browser, and copy-paste it into this prompt.

Terraform will store the token in plain text in the following file
for use by subsequent commands:
    /root/.terraform.d/credentials.tfrc.json

Token for app.terraform.io:
  Enter a value: 


Retrieved token for user USERNAME

Click Check in the bottom-right corner. The interactive lab validates the token that you used to log in to HCP Terraform, then creates a new temporary HCP Terraform Premium organization. The next screen of the interactive lab shows a link to your temporary organization on the right side of the screen. You are the owner of this new organization and it has a preconfigured VCS provider. This VCS provider connects your HCP Terraform organization to a GitHub organization that contains an example Terraform no-code module.

Create landing zone

It can be useful for platform teams to create spaces for other teams to deploy their Terraform configuration on their own. These spaces, referred to as "landing zones," help properly scope access and separate the responsibilities of the platform team, such as managing cloud credentials and critical shared infrastructure, from the responsibilities of development teams.

In the interactive lab, click the Code Editor tab and open the create-landing-zone/main.tf file. This Terraform configuration creates a landing zone for a development team by creating the following resources in HCP Terraform:

• A new project in which to create workspaces and deploy infrastructure resources.
• A new team with administrator access to the project.
• A variable set with scoped AWS credentials to a temporary HashiCorp-owned AWS account.
• A no-code module named s3-terraform to enable deploying resources without writing Terraform configuration.

Click the Terminal tab and run terraform init to initialize the configuration:

$ terraform init

Next, apply the configuration. Respond with yes when Terraform prompts you to confirm the apply operation.

$ terraform apply

## …

Plan: 9 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + project_url = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

## …

Apply complete! Resources: 9 added, 0 changed, 0 destroyed.

Outputs:

project_url = "https://app.terraform.io/app/hashiconf-2025-x9qz5t0tunmv/projects/prj-9k7TsyHasgzq7aT3"

Once Terraform completes the operation, click the link on the right side of the interactive environment to open your HCP Terraform organization in your web browser and explore the resources you just created.

Click Projects in the left navigation panel, then click your terramino-zone project.

You can configure projects and workspaces in HCP Terraform to automatically run destroy operations after a period of inactivity. This helps platform teams clean up temporary infrastructure resources, such as in development and testing environments. The Terraform configuration you ran configured the project to automatically destroy the infrastructure in every workspace in the project after one hour of inactivity.

Next, click Settings, then click Variable sets. Variable sets in HCP Terraform let you create variable values and reuse them in multiple workspaces and projects. If you apply a variable set to a project, every workspace in that project has access to the variables.

Notice that the Terraform configuration also created a variable set named terramino-zone-aws and assigned it to this project. This variable set contains the credentials for a temporary AWS account for you to use in this lab.

Return to your organization overview page, click Settings, then click Teams in the left navigation panel. The Terraform configuration created an example team named terramino-zone-team for you, and made you a member of it. Teams let administrators scope which projects and workspaces users have access to, and their permissions within those projects and workspaces. In this tutorial, the terramino-zone-team team has administrator access to the terramino-zone project.

Click the team name, then click Notifications. Team notifications in HCP Terraform alert team members when certain events occur, such as a new change request. This team has one team notification configured to send an email to every team member any time a workspace event occurs.

Deploy no-code module

No-code modules enable a self-service workflow that lets users provision approved collections of resources without writing Terraform configuration. By writing no-code modules, platform teams can define standardized collections of infrastructure resources that comply with organization standards and teams can deploy easily. Each time a user deploys a no-code module, HCP Terraform creates a new workspace. By default, HCP Terraform automatically runs a plan operation and approves the apply operation.

Review the no-code module published to your private registry. Return to your organization overview page, click Registry in the left navigation page, then click the s3-terramino module. The private registry the repository linked to this module, as well as the inputs, outputs, and dependencies.

Open the Github repository to review the module configuration. This module deploys an S3 bucket and uploads the HTML, Javascript, and CSS to host a static website. Once deployed, the module outputs the URL to the website.

In HCP Terraform, click the Provision workspace button to deploy the module. Since this module does not need the user to set any variable values, HCP Terraform reports that there are no variables found. Click Next: Workspace settings.

Name the workspace terramino, and in the Project drop-down, choose the terramino-zone project that you created earlier. Click Create workspace to deploy the no-code module.

HCP Terraform automatically queues a plan operation, then automatically applies the plan once it completes. Once HCP Terraform completes the apply operation, it displays the URL to the deployed static site. Open this URL in a new tab in your browser.

Update module

Modules evolve as you implement changes, fix bugs, and patch security issues. For an individual version of a module, the steps you take throughout this lifecycle can include:

1. Publishing a new version of the module and making it available to users.
2. Deprecating the old version of the module. This does not prevent users from deploying this module, but it does communicate to users that you will soon no longer support this version of the module.
3. Notifying teams that support for the old version of the module will soon end and they must upgrade to the new version.
4. Updating workspaces deployed from the old version of the module to the new version.
5. Revoking the old version of the module to prevent users from deploying new workspaces from this module.

In this example, you will update the modules and workspaces in your organization to use a newer version of the AWS Terraform provider.

HCP Terraform automatically creates a new version of a module every time you create a new tag in the linked GitHub repository. In this example, a second tag named v2.0.0 already exists in the linked repository.

Next, change the default version of the s3-terramino no-code module.

Navigate back to the the s3-terramino in the Registry in HCP Terraform, then click Configure Settings. Click Edit version and variable options, choose the 2.0.0 version under the Module version drop-down then click Save. Return to the module overview page and notice that HCP Terraform pulled in the README of this new version, which lists the following changes in the new module version:

• Upgrade to v6 of the AWS provider
• Added the title variable to set game screen title
• Added health checks and input validation

When you update the version of a no-code module, it does not automatically update the workspaces deployed from that module. This prevents unintended changes to deployed infrastructure, and instead gives teams a chance to test changes before deploying to production. Updating the no-code module version doesn't prevent users from deploying older versions of a module.

You can mark a module as "deprecated" to signal to the user that a module will soon no longer be supported. To do this, click the Change drop-down next the version, under the name of the module. Choose 1.0.0 to view the previous version of the module, click the Manage Module for Organization, and choose Deprecate module version 1.0.0.

HCP Terraform gives you the option to show a message to users explaining why the module is deprecated, and to provide a link for more information. In the Reason for deprecation field, enter v2.0 released with updated features, then click Deprecate. Notice that this version of the module now has a banner at the top of the overview with the deprecation notice and reasoning.

Each no-code workspace created from the old version of the module displays a notification that a new version of the module is available on the workspace overview page, and gives the workspace owner the option to upgrade to the new version. Navigate to your terramino workspace to see this notification, but do not update the workspace yet.

Communicate changes

After you've deprecated and decide to no longer support the module, it's important to help transition users to a supported version.

You can find workspaces that meet specific criteria, such as which version of a module or Terraform provider they use, and send team notifications to users from the HCP Terraform explorer. You can access the explorer from your organization overview page by clicking Explorer in the left navigation panel.

Next create a new query to find all workspaces that do not use v6 of the AWS Terraform provider. Click New query, then click Workspaces. Click the arrow next to Modify conditions and set the following values:

1. In the first drop-down, choose Providers.
2. In the second drop-down, choose does not contain.
3. In the third drop-down, enter the value of hashicorp/aws:6

This query will search for any workspace that uses any version of the AWS provider that is not version 6. Click Run Query and notice that HCP Terraform lists your terramino workspace since it uses v5 of the AWS provider.

From here, you can create a change request to communicate with users that they need to take specific actions. In this tutorial, you also configured a team notification for the terramino-zone-team team that sends email notifications any time their workspace receives a change request. If your query returns multiple workspaces, you can choose to send the same change request to all of the workspaces, or to a subset of them.

Select the checkbox next to your terramino workspace, then click Create change request. Leave the Subject with the default value, and enter the following in the Message field:

Please upgrade to the latest version of the `s3-terramino` module within **30 days**.

Click Create change request to apply the change request to the workspace and send a team notification.

Next, navigate to the terramino workspace and notice that the Change requests item in the left navigation panel now has a "1" next to it. Click on Change requests to view the new change request.

As the workspace owner, this change request communicates to you that you must update your workspaces. Return to the workspace overview page and click the View update button in the top banner. HCP Terraform prompts you to provide a value for the new title variable. Enter the value "Hello, HashiConf!".

Next, click Save configuration & start plan to start the update. HCP Terraform automatically starts a new plan and displays the resources that it will change. Since you configured your workspace to automatically apply plans, HCP Terraform then applies the configuration and updates your deployed website.

Once your deployment finishes, return to the Terramino and refresh to page to see your new title at the top of the screen.

Now that you have addressed the change request, you can mark it as completed. Return to your terramino workspace in HCP Terraform and click Change requests in the left navigation panel. Click the three dots in the Actions column next to the change request and choose Archive.

The new version of this module added a check block to the configuration. Health assessments in HCP Terraform execute the check blocks in your configuration to ensure that your deployed infrastructure continues to meet specified requirements. The new version of this module has the following check block that uses the http data source to send a request to your running application and ensures that it returns a 200 status code:

check "site_200" {
  data "http" "site_endpoint" {
    url = "http://${aws_s3_bucket_website_configuration.s3_bucket.website_endpoint}"
  }

  assert {
    condition = data.http.site_endpoint.status_code == 200
    error_message = "http://${aws_s3_bucket_website_configuration.s3_bucket.website_endpoint} returned an unhealthy status code"
  }
}

The module also added a validation block to the new title variable to ensure that the value is between 1 and 25 characters:

variable "title" {
  description = "Title of the website to show"
  type = string
  validation {
    condition = length(var.title) > 0 && length(var.title) <= 25
    error_message = "Title must be between 1-25 characters."
  }
}

To view the status of the health assessments in your workspace, click Health in the left navigation pane, then click Continuous Validation. Notice that HCP Terraform lists both the check.site_200 and var.title health assessments have the Passed status.

Revoke the module

Deprecated modules only communicate to users that you will soon stop supporting a version of a module, but do not prevent any new deployments from that module. When you are ready to remove a module version from use, you can revoke it. Revoked module versions prevent users from creating new workspaces with that specific version of the module. Users who already have workspaces deployed from that module version can still perform new Terraform operations without upgrading, but will continue to have a notification in their workspace that a new version is available.

Navigate to your organization overview, click Registry in the left navigation panel, then choose the s3-terramino module.

Next, click Version 2.0.0 at the top of the screen and choose Version 1.0.0 from the drop-down to navigate to your deprecated version of the module. Click Manage Module for Organization, then choose Revoke module version 1.0.0 from the drop-down.

HCP Terraform shows a similar form as when you deprecated the module, letting you give a reason why you revoked the module and provide a link to documentation for more information. Leave these fields blank, then click Revoke to revoke the module.

Notice that HCP Terraform no longer displays the Provision workspace button.

Destroy infrastructure

Before finishing this tutorial, destroy the infrastructure you deployed.

Navigate to your terramino workspace, click Settings, then click Destruction and Deletion. Notice that this page lists when HCP Terraform will automatically run a destroy operation if you do not perform any Terraform operations in this workspace.

Click Queue destroy plan to manually queue a destroy operation. When HCP Terraform prompts for confirmation, enter the workspace name of terramino and click Queue destroy plan.

When HCP Terraform completes the destroy operation, click Settings, then click Destruction and Deletion. Click Delete from HCP Terraform to delete the workspace. When HCP Terraform prompts for confirmation, type delete in the text box, then click Delete.

Next steps

In this tutorial, you learned how no-code modules, the module lifecycle, and team notifications help development teams move quickly, and help platform teams enforce organization standards. You created a landing zone to deploy infrastructure and create a workspace from a no-code module. Then, you deprecated a module and used the explorer to find workspaces that were using the deprecated version of the module to send a change request. You then updated the workspace, then revoked the old version of the module.

To learn more, refer to the following resources:

• Follow the Detect infrastructure drift and enforce policies tutorial to learn how to use HCP Terraform features to enforce your organization standards.
• Learn how to Create and use no-code modules.
• Read the Manage module versions documentation to learn more about module deprecation and revocation.
• Learn more about the explorer for workspace visibility.