Temporal Cloud Terraform provider

The Terraform Temporal provider is a plugin that allows Terraform to manage resources on Temporal Cloud. Terraform is a tool used to codify and provision infrastructure as code (IaC). With this provider, you can use Terraform to automate the management of Temporal Cloud Namespaces, resources for Temporal Cloud users, and more.

The Temporal Cloud Terraform provider is available in the Terraform Registry, where you can find detailed documentation on the supported resources and data sources.

The GitHub repository for the Terraform provider is terraform-provider-temporalcloud, where you can find the source code, contribution guidelines, and additional information.

note

Temporal supports the Cloud Namespace resource management, a user resource for managing Temporal Cloud users, and data sources for retrieving information about existing Namespaces and users, with the Temporal Cloud Terraform provider.

Prerequisites

You must have access to the following to use the Temporal Cloud Terraform provider:

• Terraform account
• Terraform CLI
• API Key: an API Key is required to use the Terraform provider.
  • Temporal tcld: This is an optional tool used to log in to your Temporal Cloud account and create an API Key.
• Issued certification authority
  • This is needed when Account Role permission set actions are used. For example, when managing a Namespace.

OpenTofu Registry

Our Terraform Provider is registered with OpenTofu, but that registration is not maintained or managed by Temporal Technologies.

Setup

Generate an API Key to authenticate your requests with your Temporal Cloud account. Then use an action to create a manage your Temporal Cloud Terraform resources.

Generate an API Key

You can generate an API Key through the Temporal Web UI or through the tcld apikey create command.

note

You can skip generating an API Key if you already possess a valid API Key.

Using the Temporal Web UI

1. Log into the Temporal Cloud Web UI.
2. Select your account name in the top right corner.
3. Select API Keys from the menu.
4. Choose Create API Key.
5. Enter a name for your API Key.
6. (optional) Provide a description.
7. Set a duration for the API Key.
8. Choose Generate API Key.

Using the tcld

1. Use tcld to log in and generate an API Key. This API Key is used to authenticate the Terraform provider run.

# authenticate your session
tcld login
# generate an API Key
tcld apikey create -n "terraform-test" --desc "Testing the API Key for the TF Provider" -d 90d

You will use this key when creating or destroying Namespaces with the Terraform provider.

2. Provide your working environment with the API Key generated in the previous step.

macOS

Export your environment variable for secure access to the API Keys.

# replace <yoursecretkey> with the "secretKey": output from tcld apikey create command
export TEMPORAL_CLOUD_API_KEY=<yoursecretkey>

Windows

Export your environment variable for secure access to the API Keys.

# replace <yoursecretkey> with the "secretKey": output from tcld apikey create command
set TEMPORAL_CLOUD_API_KEY=<yoursecretkey>

The TEMPORAL_CLOUD_API_KEY is used to authenticate the Terraform provider.

3. (optional) Generate your CA certificate

The CA certificate allows you to authenticate and interact with your Temporal Cloud Namespace. You can use an existing CA cert or create one using tcld. Once you have your CA certificate be sure to add the CA .pem file to your working directory.

mv ca.pem test-temporal-terraform

Manage Temporal Cloud Namespace with Terraform

Manage your Temporal Cloud Namespace with Terraform. You can create, update, and delete Namespaces with the Terraform provider.

You must have the Account Role permission set associated with your account to manage Namespaces.

Support, stability, and dependency info

Temporal Cloud’s Terraform provider does not support multi-region Namespaces.

How do I create a Namespace with Terraform?

1. Create a Terraform configuration file (terraform.tf) to define a Namespace.

terraform {
required_providers {
temporalcloud = {
source = "temporalio/temporalcloud"
}
}
}

provider "temporalcloud" {

}

resource "temporalcloud_namespace" "namespace" {
name               = "terraform"
regions            = ["aws-us-east-1"]
accepted_client_ca = base64encode(file("ca.pem"))
retention_days     = 14
}

In this example you are creating the Temporal Cloud Namespace name as terraform, specifying the AWS region aws-us-east-1, and specifying the path to the CA certificate.

2. Initailze the Terraform provider.

Run the following command to initialize the Terraform provider.

terraform init

3. Apply the Terraform configuration.

Once initialization occurs, apply the Terraform configuration to your Temporal Cloud account.

terraform apply

Follow the onscreen prompts.

Upon completion, you'll see a success message indicating your Namespace is created.

temporalcloud_namespace.terraform: Creation complete after 2m17s [id=<yournamespace>]

How do I validate the creation of the Namespace?

You can validate the creation of the Namespace through the Temporal Web UI or through the tcld namespace get command.

Using the Temporal Web UI

1. Log into the Temporal Cloud Web UI.
2. Navigate to the Namespaces page.
3. Search for the Namespace you created.

Using the tcld

Validate the creation of your Namespace through the Terraform provider. To validate see your Namespace in the Cloud UI or through the tcld namespace get command. Run the tcld namespace get command and pass in your Cloud Namespace Name and Cloud Account Id:

tcld namespace get -n "<yournamespace>.<youraccountid>"

How do I update a Temporal Cloud Namespace?

Terraform automatically recognizes changes made within .tf files and applies those changes to Temporal.

For example, change the retention period setting in the Terraform file previously and watch Terraform apply the change without any additional steps.

1. Set the retention period to 30 days.

terraform {
required_providers {
temporalcloud = {
source = "temporalio/temporalcloud"
version = ">= 0.0.6"
}
}
}

provider "temporalcloud" {

}

resource "temporalcloud_namespace" "namespace" {
name               = "terraform"
regions            = ["aws-us-east-1"]
accepted_client_ca = base64encode(file("ca.pem"))
retention_days     = 30
}

2. Apply your configuration. When prompted, answer yes to continue:

terraform apply

Upon completion, you will see a success message indicating your Namespace has been updated. It may take several minutes to update a Namespace.

temporalcloud_namespace.namespace: Modifications complete after 10s [id=terraform.a1bb2]

How do I delete a Temporal Cloud Namespace?

To delete the Namespace, run the following command:

terraform destroy

Manage Temporal Cloud Users with Terraform

Manage Temporal Cloud Users with the same process you use to manage Namespaces with Terraform. The following examples create, update, and delete Temporal Cloud Users by using the terraform apply command on the Terraform configuration file.

How do I create a Temporal Cloud User with Terraform?

1. Add a Terraform User resources configuration to your Terraform file.

terraform {
required_providers {
temporalcloud = {
source = "temporalio/temporalcloud"
version = ">= 0.0.6"
}
}
}

provider "temporalcloud" {

}

resource "temporalcloud_namespace" "namespace" {
name               = "terraform"
regions            = ["aws-us-east-1"]
accepted_client_ca = base64encode(file("ca.pem"))
retention_days     = 14
}

resource "temporalcloud_user" "global_admin" {
email          = <admin email>
account_access = "Admin"
}

resource "temporalcloud_user" "namespace_admin" {
email          = <developer email>
account_access = "Developer"
namespace_accesses = [
{
namespace_id = temporalcloud_namespace.namespace.id
permission = "Write"
}
]
}

Replace the email and domain values with your Temporal Cloud User email and domain.

2. Apply your configuration. When prompted, answer yes to continue:

terraform apply

Upon completion, you will see a success message indicating your User has been created.

temporalcloud_user.namespace_admin: Creation complete after 1s [id=12a34bc5678910d38d9e8390636e7412]
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

How do I update a Temporal Cloud User with Terraform?

To update a User with Terraform, follow the same steps used to create a User.

How do I delete a Temporal Cloud User with Terraform?

To delete a User with Terraform, remove the Terraform User resources configuration from your Terraform file and run the terraform apply command.

1. Remove the Terraform User resources configuration from your Terraform file.

terraform {
required_providers {
temporalcloud = {
source = "temporalio/temporalcloud"
version = ">= 0.0.6"
}
}
}

provider "temporalcloud" {

}

resource "temporalcloud_namespace" "namespace" {
name               = "terraform"
regions            = ["aws-us-east-1"]
accepted_client_ca = base64encode(file("ca.pem"))
retention_days     = 14
}

resource "temporalcloud_user" "global_admin" {
email          = <some email>
account_access = "Admin"
}

resource "temporalcloud_user" "global_admin" {
email          = <admin email>
account_access = "Admin"
}
# resource "temporalcloud_user" "namespace_admin" {
#   email          = <developer email>
#   account_access = "Developer"
#   namespace_accesses = [
#     {
#       namespace_id = temporalcloud_namespace.namespace.id
#       permission = "Write"
#     }
#   ]
# }

2. Run the terraform apply command. When prompted, answer yes to continue:

terraform apply

Upon completion, you will see a success message indicating your User has been deleted.

temporalcloud_user.namespace_admin: Destruction complete after 2s
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.