Using Terraform Cloud and Enterprise
1. Configuring Terraform Cloud Backend
| Option | Values | Description |
|---|---|---|
| backend | "remote" |
Specifies the remote backend for Terraform Cloud/Enterprise |
| hostname | app.terraform.io |
The hostname of the Terraform Cloud instance (default is Terraform Cloud) |
| organization | "myorg" |
The name of the Terraform Cloud organization |
| workspaces | { name = "myworkspace" } |
Workspace configuration to use with the remote backend |
Example: Remote Backend Configuration
terraform {
backend "remote" {
hostname = "app.terraform.io"
organization = "myorg"
workspaces {
name = "myworkspace"
}
}
}
Note: The remote backend requires a Terraform Cloud or Enterprise license.
2. Creating Organizations and Workspaces
| Field | Description | Example |
|---|---|---|
| organization.name | Name of the organization | "mycompany" |
| workspace.name | Name of the workspace | "production" |
| workspace.vcs_repo | Version control system repository settings | |
Example: Creating a Workspace via API
{
"data": {
"type": "workspaces",
"attributes": {
"name": "production",
"auto-destroy": false
}
}
}
Note: Workspaces in Terraform Cloud are isolated environments for managing infrastructure.
Key Concepts
- Organizations group workspaces and users.
- Workspaces isolate state and configuration.
- Each workspace can have its own
terraform.tfvars.
3. Connecting VCS Repositories
| Repository Type | Connection Method | Requirements | Notes |
|---|---|---|---|
| GitHub | GitHub App |
App installed on organization/repo, appropriate permissions | Recommended for most use cases; supports webhooks and branch-based workflows |
| GitLab | GitLab Integration |
Integration token with project access | Supports GitLab CI/CD integration and branch triggers |
| Bitbucket | Bitbucket Cloud |
App installed with repo read/write permissions | Supports branch and tag triggers, pull request integration |
| Azure DevOps | Azure DevOps Integration |
Service connection with repo access | Supports branch and pull request triggers, integration with Azure pipelines |
Example: GitHub App Setup
terraform {
required_providers {
github = {
source = "integrations/github"
}
}
}
resource "github_app" "terraform_cloud" {
name = "Terraform Cloud App"
description = "App for Terraform Cloud VCS integration"
homepage_url = "https://example.com"
callback_url = "https://app.terraform.io/auth/callback"
webhook_url = "https://app.terraform.io/webhooks"
webhook_secret = "secret-key"
organization = "myorg"
}
Note: Ensure the VCS provider app has appropriate permissions to read and write to repositories, including branch protection rules if applicable.
4. Configuring Remote Execution
| Setting | Description | Value/Example |
|---|---|---|
| remote.state.enabled | Enables remote state storage and execution | true |
| remote.state.organization | Name of the Terraform Cloud organization | mycompany |
| remote.state.workspaces.name | Name of the workspace in Terraform Cloud | prod-env |
| remote.exec.enabled | Enables remote execution of Terraform operations | true |
| remote.exec.agent | Specifies the agent to use for remote execution | terraform-agent |
Example: Remote Execution Configuration
terraform {
required_version = "1.9.0"
backend "remote" {
hostname = "app.terraform.io"
organization = "mycompany"
workspaces {
name = "prod-env"
}
}
}
# Enable remote execution
provider "local" {
# This will be executed remotely in Terraform Cloud
}
Note: Remote execution requires Terraform Cloud or Enterprise license.
Warning: Ensure that the remote workspace has appropriate permissions and policies configured.
5. Setting Up Sentinel Policies
Sentinel is a policy-as-code framework integrated with Terraform Cloud and Enterprise that allows you to enforce governance rules on your infrastructure.
| Policy Type | Description | Usage |
|---|---|---|
| Hard-Mandatory | Enforces a rule that must pass or the operation is blocked. | Prevents deployment if policy conditions are not met. |
| Soft-Mandatory | Logs policy violations but does not block the operation. | Allows deployment but flags issues for review. |
| Advisory | Provides advisory messages without blocking. | Used for best practices or recommendations. |
Example: Hard-Mandatory Policy
# Example Sentinel policy enforcing a tag requirement
import "tfplan" as tfplan
main = rule {
tfplan.resource_changes.all {
# Check that all resources have a "owner" tag
all {
resource.tags.owner exists
}
}
}
Note: Policies are evaluated during plan and apply phases in Terraform Cloud.
Setting Up Sentinel Policies
- Create a new policy in the Terraform Cloud dashboard under
Policy Sets. - Define policy rules using the Sentinel language.
- Assign the policy to a workspace or organization-wide policy set.
- Configure policy enforcement level (hard-mandatory, soft-mandatory, or advisory).
6. Using Private Module Registry
| Field | Description | Example |
|---|---|---|
| source | Module source path in the private registry | registry.terraform.io/myorg/mymodule/latest |
| version | Version constraint for the module | >= 1.0.0 |
Example: Using a Private Module
module "vpc" {
source = "registry.terraform.io/myorg/vpc/latest"
version = ">= 1.0.0"
cidr_block = "10.0.0.0/16"
}
Note: Private modules must be published to the registry before they can be used.
Warning: Ensure proper access control and permissions for private module registry.
| Registry Type | Description | Access |
|---|---|---|
| Private | Modules accessible only to authorized users in the organization | Organization members with appropriate permissions |
| Public | Modules accessible to anyone with the module name and version | Anyone with access to Terraform Cloud or Enterprise |
7. Managing Teams and Permissions
| Resource | Description | Notes |
|---|---|---|
| terraform_cloud_team | Manages a team within Terraform Cloud | Teams are used to organize users and assign permissions |
| terraform_cloud_team_member | Manages a user's membership in a team | Assigns users to teams for permission management |
| terraform_cloud_team_token | Manages a team's API token | Used for automated access to Terraform Cloud |
| terraform_cloud_workspace | Manages a workspace within Terraform Cloud | Workspaces isolate configurations and state |
| terraform_cloud_workspace_variable | Manages a variable within a workspace | Variables can be sensitive or non-sensitive |
Example: Creating a Team and Assigning Members
resource "terraform_cloud_team" "admin_team" {
name = "admin"
description = "Administrative team with full access"
}
resource "terraform_cloud_team_member" "admin_user" {
team_id = terraform_cloud_team.admin_team.id
username = "admin_user"
}Example: Setting Up a Workspace with Variables
resource "terraform_cloud_workspace" "example" {
name = "example-workspace"
organization = "myorg"
}
resource "terraform_cloud_workspace_variable" "env_var" {
key = "ENVIRONMENT"
value = "production"
workspace_id = terraform_cloud_workspace.example.id
sensitive = false
}
Note: Team permissions in Terraform Cloud are managed through the
terraform_cloud_team resource and its associated permissions. Each team can be assigned to workspaces with specific roles (e.g., admin, write, read).
Warning: Ensure that sensitive variables are marked as
sensitive = true to prevent them from appearing in logs or outputs.
Key Concepts
- Teams are used to group users and assign permissions.
- Workspaces are isolated environments for managing infrastructure.
- Variables can be set at the workspace or organization level.
- Tokens provide programmatic access to Terraform Cloud.
8. Configuring Notifications
| Notification Type | Event Triggers | Configuration | Notes |
|---|---|---|---|
run:completed, run:failed, run:approved |
email_addresses array |
Supports multiple email addresses | |
| Slack | run:completed, run:failed, run:approved |
webhook_url, channel |
Requires Slack webhook URL |
| Microsoft Teams | run:completed, run:failed, run:approved |
webhook_url, channel |
Requires Teams webhook URL |
| Webhook | run:completed, run:failed, run:approved |
url, headers |
Custom payload support |
Example: Slack Notification Configuration
{
"name": "slack-notifications",
"destination": {
"type": "slack",
"webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"channel": "#terraform-notifications"
},
"triggers": [
"run:completed",
"run:failed"
]
}Example: Webhook Notification Configuration
{
"name": "webhook-notifications",
"destination": {
"type": "webhook",
"url": "https://example.com/webhook",
"headers": {
"Authorization": "Bearer secret-token"
}
},
"triggers": [
"run:completed"
]
}
Note: Notification configurations can be managed via Terraform Cloud UI or API. Ensure webhook URLs are secure and accessible.
9. Using Cost Estimation
Cost estimation in Terraform allows you to predict the monthly cost of your infrastructure before applying changes.
| Field | Description | Example |
|---|---|---|
| enabled | Enables cost estimation for the workspace | true |
| currency | Currency used for cost estimation (default: USD) | USD |
Example: Enabling Cost Estimation
resource "terraform_cloud_workspace" "example" {
name = "example-workspace"
cost_estimation_enabled = true
}
Note: Cost estimation is available in Terraform Cloud and Terraform Enterprise only.
Warning: Cost estimates are approximate and may not reflect actual charges.
| Provider | Support Status | Notes |
|---|---|---|
aws |
Good | Full cost estimation support |
azure |
Good | Full cost estimation support |
gcp |
Good | Full cost estimation support |
10. Setting Up Run Triggers
Run triggers in Terraform Cloud and Enterprise allow you to automate runs in one workspace based on events in another workspace or in a version control system.
| Trigger Type | Description | Configuration | Notes |
|---|---|---|---|
| workspace | Triggers a run in the target workspace when a run completes in the source workspace. | trigger.workspace.id |
Requires the target workspace to be in the same organization. |
| vcs | Triggers a run in the target workspace when a VCS event occurs (e.g., push to a branch). | trigger.vcs.branch, trigger.vcs.event |
Supports branch, tag, and pull request events. |
Example: Setting up a Workspace Trigger
resource "terraform_cloud_workspace" "main" {
name = "main-workspace"
organization = "myorg"
}
resource "terraform_cloud_workspace" "triggered" {
name = "triggered-workspace"
organization = "myorg"
}
resource "terraform_cloud_run_trigger" "main_to_triggered" {
workspace_id = terraform_cloud_workspace.main.id
target_workspace_id = terraform_cloud_workspace.triggered.id
trigger_type = "workspace"
}
Note: Run triggers are only available in Terraform Cloud and Enterprise plans.