diff --git a/docs/cli/setup-cli.mdx b/docs/cli/setup-cli.mdx index 9ab736460a..f7e3af1291 100644 --- a/docs/cli/setup-cli.mdx +++ b/docs/cli/setup-cli.mdx @@ -97,7 +97,7 @@ extension using the following command: :::tip Support, stability, and dependency info -The Temporal Cloud extension is in [Pre-release](/evaluate/development-production-features/release-stages#pre-release). +The Temporal Cloud extension is in [Public Preview](/evaluate/development-production-features/release-stages#public-preview). APIs and configuration may change before the stable release. ::: diff --git a/docs/cloud/aws-export-s3.mdx b/docs/cloud/aws-export-s3.mdx index 059890e0d3..ac7883c780 100644 --- a/docs/cloud/aws-export-s3.mdx +++ b/docs/cloud/aws-export-s3.mdx @@ -20,6 +20,8 @@ tags: - Temporal Cloud --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import * as Components from '@site/src/components'; ## Prerequisites @@ -29,12 +31,12 @@ Before configuring the Export Sink, ensure you have the following: - An AWS S3 bucket. - The S3 bucket must reside in the same region as your Namespace. - (Optional) An IAM role that has write permission to the above S3 bucket. - - You can follow the automation in the UI to create the IAM role. Please pre-create the role if setting up Export via terraform/tcld. + - You can follow the automation in the UI to create the IAM role. Please pre-create the role if setting up Export via Terraform or the CLI. - (Optional) A KMS ARN associated with the S3 bucket. ## Configure Workflow History export -There are multiple ways to configure export: through the [Temporal Cloud UI](#using-temporal-cloud-ui), [`tcld`](#using-tcld), or [`terraform`](#using-terraform). +There are multiple ways to configure export: through the [Temporal Cloud UI](#using-temporal-cloud-ui), the [CLI](#using-the-cli), or [`terraform`](#using-terraform). ### Using Temporal Cloud UI @@ -96,7 +98,42 @@ You can manually configure a CloudFormation stack using the provided template. - Configure the CloudFormation template for your export sink. - Follow the steps in the [AWS documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-console-create-stack-template.html) by uploading the template to the CloudFormation console. -### Using `tcld` +### Using the CLI + + + + +Run the `temporal cloud namespace export s3 create` command and provide the following information: + +- `--namespace`: The Namespace to configure export for. +- `--sink-name`: The name of the export sink. +- `--role-arn`: The ARN of the AWS IAM role to use for the CloudFormation stack that has write permission to the S3 bucket. +- `--bucket-name`: The name of the AWS S3 bucket. +- `--region`: The AWS region the S3 bucket is in. + +For example: + +```command +temporal cloud namespace export s3 create \ + --namespace "your-namespace.your-account" \ + --sink-name "your-sink-name" \ + --role-arn "arn:aws:iam::123456789012:role/test-sink" \ + --bucket-name "your-aws-s3-bucket-name" \ + --region "us-east-1" +``` + +Retrieve the status of this command by running the `temporal cloud namespace export get` command. + +For example: + +```command +temporal cloud namespace export get \ + --namespace "your-namespace.your-account" \ + --sink-name "your-sink-name" +``` + + + Run the `tcld namespace export s3 create` command and provide the following information: @@ -119,6 +156,9 @@ For example: tcld namespace export s3 get --namespace "your-namespace.your-account" --sink-name "your-sink-name" ``` + + + The following is an example of the output: ```json diff --git a/docs/cloud/capacity-modes.mdx b/docs/cloud/capacity-modes.mdx index 0e905cc784..fc94d935b3 100644 --- a/docs/cloud/capacity-modes.mdx +++ b/docs/cloud/capacity-modes.mdx @@ -27,6 +27,9 @@ tags: - TRUs --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + Each Namespace in Temporal has a rate limit, which is measured in [Actions](/cloud/pricing#action) per second. Temporal offers two different modes for adjusting capacity: On-Demand Capacity or Provisioned Capacity. With On-Demand Capacity, Namespace capacity is increased automatically along with usage. @@ -116,7 +119,7 @@ Each Namespace has a rate limit, which is measured in Actions per second (APS). Your APS limit automatically adjusts based on a formula that compares your average usage over the last 7 days and your usage at the 90th percentile, or P90. Your throughput limit will never fall below the [default limit](/cloud/limits#actions-per-second) for your Namespace. Under On-Demand capacity you are only charged for the Actions you use. -To see your current limit, view it in the Temporal Cloud UI under the Namespace overview, retrieve it with the [CLI (`tcld`)](/cloud/tcld/namespace/#capacity) by running `tcld namespace capacity get`, or track the `temporal_cloud_v1_action_limit` metric described in [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits). +To see your current limit, view it in the Temporal Cloud UI under the Namespace overview, retrieve it with the CLI by running [`temporal cloud namespace capacity get`](/cli/command-reference/cloud/namespace#capacity-get) or [`tcld namespace capacity get`](/cloud/tcld/namespace/#capacity), or track the `temporal_cloud_v1_action_limit` metric described in [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits). For example, if your average APS over the last 7 days was 200 and your P90 was 500, your limit would be the greater of: * The [default limit](/cloud/limits#actions-per-second) @@ -210,8 +213,35 @@ See [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits ### Setting Capacity Modes from the CLI + + + +```command +temporal cloud namespace capacity update \ + --namespace \ + --capacity-mode \ + --capacity-value +``` + +Use this command to specify the Namespace name and configure the capacity settings: + +* `--capacity-mode` sets the billing mode for the Namespace. Use `on_demand` for automatic scaling or `provisioned` for a fixed capacity allocation. +* `--capacity-value` sets the throughput value in TRUs (Temporal Resource Units). + +Optional flags: + +* `--async-operation-id` specifies an identifier for tracking the asynchronous operation. If not specified, the CLI generates one automatically. +* `--resource-version` specifies the resource version (etag) to update from. If not set, the CLI uses the latest version. + + + + ```command -tcld namespace capacity update --namespace --capacity-mode --capacity-value [--request–id --resource-version ] +tcld namespace capacity update \ + --namespace \ + --capacity-mode \ + --capacity-value \ + [--request-id --resource-version ] ``` Use this command to specify the Namespace name and configure the capacity settings: @@ -226,6 +256,9 @@ Optional flags: If using API key authentication with the `--api-key` flag, you must add it directly after the tcld command and before capacity update. + + + ### Setting Capacity Modes from the API Call the `UpdateNamespace` API after Namespace creation and define the desired capacity state as part of the capacity spec. diff --git a/docs/cloud/connectivity/index.mdx b/docs/cloud/connectivity/index.mdx index f98fb1615c..b2bf40d73f 100644 --- a/docs/cloud/connectivity/index.mdx +++ b/docs/cloud/connectivity/index.mdx @@ -18,6 +18,8 @@ keywords: - term --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage, SdkTabs } from '@site/src/components'; ## Private network connectivity for namespaces @@ -101,7 +103,7 @@ A GCP Private Service Connect (PSC) private Connectivity Rule requires: - `region`: The region of the PSC connection, prefixed with `gcp-` (ex: `gcp-us-east1`). Must be the same region as the Namespace. Refer to the [Temporal Cloud region list](/cloud/regions) for supported regions. - `gcp-project-id`: The identifier of the GCP project where you created the PSC connection (ex: `my-example-project-123`). -Connectivity Rules can be created and managed with [tcld](/cloud/tcld/), [Terraform](https://github.com/temporalio/terraform-provider-temporalcloud/), or the [Cloud Ops API](/ops). There is no Temporal Cloud Web UI option for creating or managing Connectivity Rules at this time. +Connectivity Rules can be created and managed with the [Temporal Cloud CLI extension](/cli/cloud), [tcld](/cloud/tcld/), [Terraform](https://github.com/temporalio/terraform-provider-temporalcloud/), or the [Cloud Ops API](/ops). There is no Temporal Cloud Web UI option for creating or managing Connectivity Rules at this time. :::tip Connectivity Rules give Temporal visibility into your private connections @@ -119,32 +121,52 @@ There is only one public rule allowed per account, because it's generic and can ## Creating a connectivity rule -### Temporal Cloud CLI (tcld) +### Temporal Cloud CLI -Create private connectivity rule (AWS): + + + +Create a private connectivity rule (AWS): + +```bash +temporal cloud connectivity private create --connection-id "vpce-abcde" --region "aws-us-east-1" +``` + +Create a private connectivity rule (GCP): + +```bash +temporal cloud connectivity private create --connection-id "1234567890" --region "gcp-us-central1" --gcp-project-id "my-project-123" +``` + +Create a public connectivity rule. You only need to do this once for your account: + +```bash +temporal cloud connectivity public create +``` + + + + +Create a private connectivity rule (AWS): ```bash tcld connectivity-rule create --connectivity-type private --connection-id "vpce-abcde" --region "aws-us-east-1" ``` -Create private connectivity rule (GCP): +Create a private connectivity rule (GCP): ```bash tcld connectivity-rule create --connectivity-type private --connection-id "1234567890" --region "gcp-us-central1" --gcp-project-id "my-project-123" ``` -Create public connectivity rule (you only need to do this once ever in your account): +Create a public connectivity rule. You only need to do this once for your account: ```bash tcld connectivity-rule create --connectivity-type public ``` -To enable [Stable IPs](/cloud/connectivity/ip-addresses#stable-ip-addresses) on the public rule, use the Cloud Ops API or Terraform. See [How to enable Stable IPs](/cloud/connectivity/ip-addresses#how-to-enable-stable-ips). - The `cr` alias works the same way: -Private connectivity rule: - ```bash tcld cr create --connectivity-type private --connection-id "vpce-abcde" --region "aws-us-east-1" ``` @@ -153,6 +175,11 @@ tcld cr create --connectivity-type private --connection-id "vpce-abcde" --region tcld cr create --connectivity-type public ``` + + + +To enable [Stable IPs](/cloud/connectivity/ip-addresses#stable-ip-addresses) on the public rule, use the Cloud Ops API or Terraform. See [How to enable Stable IPs](/cloud/connectivity/ip-addresses#how-to-enable-stable-ips). + ### Terraform [Examples in the Terraform repo](https://github.com/temporalio/terraform-provider-temporalcloud/blob/main/examples/resources/temporalcloud_connectivity_rule/resource.tf) @@ -163,9 +190,35 @@ Be careful! When any connectivity rules are set on a namespace, that namespace i If you already have workers using a namespace, adding both a public rule and any private rules simultaneously can help you avoid unintended loss of access. You can then ensure all workers are using private connections, and then remove the public rule. -### Temporal Cloud CLI (tcld) +### Temporal Cloud CLI + + + -Setting the connectivity rules on a namespace: +Attach connectivity rules to a namespace: + +```bash +temporal cloud namespace connectivity attach --namespace "my-namespace.abc123" \ + --connectivity-rule-id "rule-id-1" --connectivity-rule-id "rule-id-2" +``` + +Rules attach and detach individually. To detach `rule-c` while leaving `rule-a` and `rule-b` in place, detach only `rule-c`: + +```bash +temporal cloud namespace connectivity detach --namespace "my-namespace.abc123" \ + --connectivity-rule-id "rule-c" +``` + +Detaching every rule makes the namespace public. List the attached rules first, then detach them: + +```bash +temporal cloud namespace connectivity list --namespace "my-namespace.abc123" +``` + + + + +Set the connectivity rules on a namespace: ```bash tcld namespace set-connectivity-rules --namespace "my-namespace.abc123" --connectivity-rule-ids "rule-id-1" --connectivity-rule-ids "rule-id-2" @@ -180,7 +233,7 @@ tcld n scrs -n "my-namespace.abc123" --ids "rule-id-1" --ids "rule-id-2" Connectivity rules are attached as a set, so if rules `rule-a`, `rule-b`, and `rule-c` were attached to a namespace and you wanted to detach `rule-c` only, you'd make one call attaching both `rule-a` and `rule-b`: ```bash -tcld namespace set-connectivity-rules --namespace "my-namespace.abc123 --ids rule-a --ids rule-b +tcld namespace set-connectivity-rules --namespace "my-namespace.abc123" --ids rule-a --ids rule-b ``` Remove all connectivity rules (this will make the namespace public): @@ -189,6 +242,9 @@ Remove all connectivity rules (this will make the namespace public): tcld namespace set-connectivity-rules --namespace "my-namespace.abc123" --remove-all ``` + + + ### Terraform [Example in the Terraform repo](https://github.com/temporalio/terraform-provider-temporalcloud/tree/main/examples/resources/temporalcloud_namespace/resource.tf#L113-L128) @@ -202,18 +258,44 @@ You have two ways to view the connectivity rules attached to a particular namesp Connectivity rules are included in the namespace details returned by the `namespace get` command. + + + +```bash +temporal cloud namespace get -n "my-namespace.abc123" +``` + + + + ```bash tcld namespace get -n "my-namespace.abc123" ``` + + + ### List connectivity rules by namespace -To see only the connectivity rules for a specific namespace (without other namespace details), use the `connectivity-rule list` command with a namespace argument. +To see only the connectivity rules for a specific namespace, without other namespace details, list the rules for that namespace. + + + + +```bash +temporal cloud namespace connectivity list -n "my-namespace.abc123" +``` + + + ```bash tcld connectivity-rule list -n "my-namespace.abc123" ``` + + + ## Update DNS or clients to use private connectivity We strongly recommend using private DNS instead of updating client server and TLS settings: diff --git a/docs/cloud/gcp-export-gcs.mdx b/docs/cloud/gcp-export-gcs.mdx index 5b1bda934e..b083bdb8e8 100644 --- a/docs/cloud/gcp-export-gcs.mdx +++ b/docs/cloud/gcp-export-gcs.mdx @@ -20,6 +20,8 @@ tags: - Temporal Cloud --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import * as Components from '@site/src/components'; ## Prerequisites {/* #prerequisites */} @@ -43,7 +45,7 @@ Before configuring the Export sink, complete the following steps in Google Cloud ## Configure Workflow History Export -There are multiple ways to configure export: through the [Temporal Cloud UI](#using-temporal-cloud-ui), [`tcld`](#using-tcld), or [`terraform`](#using-terraform). +There are multiple ways to configure export: through the [Temporal Cloud UI](#using-temporal-cloud-ui), the [CLI](#using-the-cli), or [`terraform`](#using-terraform). :::note Why does Temporal Cloud provision multiple service accounts for Export? @@ -89,7 +91,39 @@ Don't forget to click Create at the end of your setup to confirm your export. ::: -### Using tcld +### Using the CLI + + + + +1. [Install the Temporal Cloud extension](/cli/setup-cli#install-the-temporal-cloud-extension) for the Temporal CLI. +2. Run the `temporal cloud namespace export gcs create` command and provide the following information: + - `--namespace`: The Namespace to configure export for. + - `--sink-name`: The name of the export sink. + - `--service-account-email`: The service account that has access to the sink. + - `--bucket-name`: The name of the GCP GCS bucket. + - `--region`: The region the GCS bucket is in. + + For example: + + ```bash + temporal cloud namespace export gcs create \ + --namespace test.ns \ + --sink-name test-sink \ + --service-account-email test-sink@test-export-sink.iam.gserviceaccount.com \ + --bucket-name test-export-validation \ + --region us-central1 + ``` + +3. Check the status of this command by either viewing the Namespace Export status in the Temporal Cloud UI or by + retrieving the sink and looking for the state of "Active": + + ```bash + temporal cloud namespace export get --namespace test.ns --sink-name test-sink + ``` + + + To access export-related commands in tcld, please follow these steps: @@ -153,6 +187,9 @@ tcld n export gcs g -n test.ns --sink-name test-sink } ``` + + + ### Using `terraform` See the [Terraform export support](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs/resources/namespace_export_sink) for setup instructions. diff --git a/docs/cloud/get-started/api-keys.mdx b/docs/cloud/get-started/api-keys.mdx index 3f276d5032..5e29c79064 100644 --- a/docs/cloud/get-started/api-keys.mdx +++ b/docs/cloud/get-started/api-keys.mdx @@ -19,6 +19,8 @@ tags: - API --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; Temporal Cloud API keys offer industry-standard identity-based authentication for Temporal users and @@ -65,7 +67,7 @@ API keys with your Namespace topology, see [Managing Temporal Cloud access contr API keys are used for the following scenarios: - _**Cloud operations automation**_: API keys work with Temporal Cloud operational tools, including - [`tcld`](/cloud/tcld), [Cloud Ops APIs](/ops), and + the [Temporal Cloud CLI extension](/cli/cloud), [`tcld`](/cloud/tcld), [Cloud Ops APIs](/ops), and [the Terraform provider](/cloud/terraform-provider). Use them to manage your Temporal Cloud account, Namespaces, certificates, and user identities. - _**Namespace authentication**_: API keys serve as an authentication mechanism for executing and managing Workflows via @@ -75,7 +77,7 @@ API keys are used for the following scenarios: Use API keys to authenticate with: -- [The Temporal CLI](/cli) +- [The Temporal CLI](/cli), including the [Temporal Cloud extension](/cli/cloud) - [Temporal SDKs](/develop) - [`tcld`](/cloud/tcld/index.mdx) - [The Cloud Operations API](/cloud/operation-api.mdx) @@ -85,7 +87,7 @@ Use API keys to authenticate with: API keys support both users and Service Accounts. Here are the differences in their permissions: -- Any user can create, delete, and update their _own_ API key using the Cloud UI or `tcld`. +- Any user can create, delete, and update their _own_ API key using the Cloud UI or the CLI. - Only Global Administrators and Account Owners can create, delete, and update access to API keys for all types of Service Accounts. - Namespace Admins can create, delete, and update access to API keys for the Namespace-scoped Service Accounts they @@ -97,8 +99,8 @@ Check these setup details before using API keys: - The Global Administrator or Account Owner may need to [enable API keys access](#manage-api-keys) for your Temporal Account. -- Have access to the [Temporal Cloud UI](https://cloud.temporal.io/) or Temporal Cloud CLI - ([tcld](/cloud/tcld/)) to create an API key. +- Have access to the [Temporal Cloud UI](https://cloud.temporal.io/), the + [Temporal Cloud CLI extension](/cli/cloud), or [`tcld`](/cloud/tcld/) to create an API key. ## Global Administrator and Account Owner API key management {/* #manage-api-keys */} @@ -128,7 +130,7 @@ is created and configured. ## User API key management {/* #user-api-keys */} -Manage your personal API keys with the Temporal Cloud UI or `tcld`. These sections show you how to generate, manage, and +Manage your personal API keys with the Temporal Cloud UI or the CLI. These sections show you how to generate, manage, and remove API keys for a user. ### Generate an API key @@ -153,10 +155,24 @@ following information: Finish by selecting **Generate API Key**. -#### Generate API keys with tcld +#### Generate API keys with the CLI To generate an API key, log into your account and issue the following command: + + + +```command +temporal cloud login +temporal cloud apikey create-for-me \ + --display-name \ + --description "" \ + --expiry-duration +``` + + + + ```command tcld login tcld apikey create \ @@ -165,6 +181,9 @@ tcld apikey create \ --duration ``` + + + Duration specifies the time until the API key expires, for example: "30d", "4d12h", etc. ### Enable or Disable an API key @@ -180,16 +199,31 @@ Follow these steps: 1. Select the vertical ellipsis menu in the API key table row. 1. Choose **Enable** or **Disable**. -#### Manage API Key State with tcld +#### Manage API key state with the CLI To manage an API key, log into your account and use one of the following commands to enable or disable it: + + + +```command +temporal cloud login +temporal cloud apikey disable --key-id +temporal cloud apikey enable --key-id +``` + + + + ```command tcld login tcld apikey disable --id tcld apikey enable --id ``` + + + ### Delete an API key Deleting an API key stops it from authenticating with Temporal Cloud. @@ -210,15 +244,29 @@ Follow these steps to remove API keys: 1. Select the vertical ellipsis menu in the API key table row. 1. Choose **Delete**. -#### Delete API keys with tcld +#### Delete API keys with the CLI To delete an API key, log into your account and issue the following: + + + +```command +temporal cloud login +temporal cloud apikey delete --key-id +``` + + + + ```command tcld login tcld apikey delete --id ``` + + + ### Rotate an API key Temporal API keys automatically expire based on the specified expiration time. [Email notifications](/cloud/notifications#admin-notifications) will be sent from Temporal Cloud to Global Administrators, Account Owners, and the key owner at **30, 20, and 10 days before** an API key expires. Follow these steps to rotate API keys: @@ -262,11 +310,25 @@ provide the following information: Finish by selecting **Generate API Key**. -#### Generate API keys with tcld +#### Generate API keys with the CLI + +Create an API key for a Service Account by passing the Service Account ID: -To create an API key for a Service Account, use `tcld apikey create` with the `--service-account-id` flag: + + +```command +temporal cloud apikey create-for-service-account \ + --display-name \ + --description "" \ + --expiry-duration \ + --service-account-id ``` + + + + +```command tcld apikey create \ --name \ --description "" \ @@ -274,10 +336,13 @@ tcld apikey create \ --service-account-id ``` + + + ### Enable or Disable an API key Global Administrators and Account Owners can manage API key access for any user in their account using the Temporal -Cloud UI or `tcld`. +Cloud UI or the CLI. #### Manage keys with Temporal Cloud UI @@ -290,22 +355,37 @@ Follow these steps: action. There may be a delay after changing the status. Once successful, the updated API key status will be shown in the row. -#### Manage keys with tcld +#### Manage keys with the CLI + +Use the disable or enable command to change the state of an API key: -Use the `tcld apikey disable` or `tcld apikey enable` command to disable or enable an API key: + + +```command +temporal cloud login +temporal cloud apikey disable --key-id +temporal cloud apikey enable --key-id ``` + + + + +```command tcld login tcld apikey disable --id tcld apikey enable --id ``` + + + This command is the same for users and Service Accounts. ### Delete an API key for a Service Account Global Administrators and Account Owners can delete API keys for any user or Service Account in their account using the -Temporal Cloud UI or `tcld`. Deleting a key removes its ability to authenticate with Temporal Cloud. If you delete an +Temporal Cloud UI or the CLI. Deleting a key removes its ability to authenticate with Temporal Cloud. If you delete an API key used by a Worker to run a Workflow, that Worker will fail to connect to Temporal server unless you rotate the API key with a new one. @@ -318,16 +398,29 @@ Follow these steps: delay after deleting the API key. 1. Once successful, the updated API key status will be reflected in the row. -#### Delete a Service Account API key with tcld +#### Delete a Service Account API key with the CLI -Use the `tcld apikey delete` command to delete an API key. The process for deleting an API key is the same for a user or -Service Account. +Use the delete command to remove an API key. The process is the same for a user or Service Account. + + + +```command +temporal cloud login +temporal cloud apikey delete --key-id ``` + + + + +```command tcld login tcld apikey delete --id ``` + + + ### Rotate a Service Account API key Temporal API keys automatically expire based on the specified expiration time. [Email notifications](/cloud/notifications#admin-notifications) will be sent from Temporal Cloud to Global Administrators, Account Owners, and the key owner at **30, 20, and 10 days before** an API key expires. Follow these steps to rotate API keys: @@ -340,7 +433,7 @@ Temporal API keys automatically expire based on the specified expiration time. [ :::tip Service Accounts can rotate their own API keys irrespective of their configured permissions. To use this feature, have -your Service Account create a new API key using the [Cloud Ops APIs](/ops) or [`tcld`](/cloud/tcld) before the current +your Service Account create a new API key using the [Cloud Ops APIs](/ops) or the CLI before the current one expires. Service Accounts cannot delete their own API keys without the requisite permissions, which helps keep Workflow access secure. @@ -361,7 +454,7 @@ See [accessing Namespaces](/cloud/namespaces#access-namespaces) for more informa Authenticate with Temporal Cloud using API keys with the following clients: -- [Temporal CLI](/cli) +- [Temporal CLI](/cli), including the [Temporal Cloud extension](/cli/cloud) - [SDKs](/develop) - [Temporal Cloud CLI `tcld`](/cloud/tcld/index.mdx) - [The Cloud Operations API](/cloud/operation-api.mdx) @@ -410,9 +503,9 @@ To use your API key with a Temporal SDK, see the instructions in each SDK sectio [How to connect to Temporal Cloud using an API Key with the .NET SDK](/develop/dotnet/client/temporal-client#connect-to-temporal-cloud) -### tcld +### Temporal Cloud CLI -To use an API key with `tcld`, choose one of these methods: +To use an API key with the `temporal cloud` extension or `tcld`, choose one of these methods: - Use the `--api-key` flag. - Set the `TEMPORAL_API_KEY` environment variable in your shell. diff --git a/docs/cloud/get-started/namespaces.mdx b/docs/cloud/get-started/namespaces.mdx index 7838e7575e..d50725a152 100644 --- a/docs/cloud/get-started/namespaces.mdx +++ b/docs/cloud/get-started/namespaces.mdx @@ -19,6 +19,8 @@ tags: - Temporal Cloud --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage, EnlargeImage } from '@site/src/components'; :::info Temporal Cloud @@ -56,7 +58,7 @@ The Namespace Name alone is not sufficient to connect to or reference a Namespac For example: `accounting-production.123de` -The full Namespace ID is shown in the Namespace list in the Temporal Cloud UI and in the output of `tcld namespace list`. See [Cloud Namespace ID](#temporal-cloud-namespace-id) for details. +The full Namespace ID is shown in the Namespace list in the Temporal Cloud UI and in the output of the `namespace list` command. See [Cloud Namespace ID](#temporal-cloud-namespace-id) for details. ::: ## What is a Temporal Cloud Account ID? {/* #temporal-cloud-account-id */} @@ -65,8 +67,8 @@ A Temporal Cloud Account ID is a unique customer identifier assigned by Temporal of numbers and letters like `f45a2`, at least five characters long. This account identifier is part of every Namespace ID in your account and is retained while you use Temporal Cloud. -You can retrieve your Account ID from the [Temporal Cloud](https://cloud.temporal.io) Web UI or by using the `tcld` -utility at a command line interface (CLI). Follow these steps. +You can retrieve your Account ID from the [Temporal Cloud](https://cloud.temporal.io) Web UI or from the command line. +Follow these steps. @@ -86,6 +88,25 @@ utility at a command line interface (CLI). Follow these steps. + + 1. Use the Temporal Cloud extension to log into an account. + + ``` + temporal cloud login + ``` + + Complete the interactive login in the browser window that opens. + + 1. Return to the command line and list your Namespaces. + + ``` + temporal cloud namespace list + ``` + + Each Namespace uses an Account ID suffix, the same as in the Temporal Cloud Web UI Namespaces list. + + + 1. Use the `tcld` utility to log into an account. @@ -226,6 +247,12 @@ To create a Namespace in Temporal Cloud, gather the following information: + + +See the [`temporal cloud namespace create`](/cli/command-reference/cloud/namespace#create) command reference for details. + + + See the [`tcld` namespace create](/cloud/tcld/namespace/#create) command reference for details. @@ -341,19 +368,21 @@ To add a user to a Namespace, scroll to the bottom of the page and select **Add After you make changes, select **Save** in the top-right or bottom-left portion of the page. -{/* How to manage Namespaces in Temporal Cloud using tcld */} +{/* How to manage Namespaces in Temporal Cloud from the CLI */} -### Manage Namespaces in Temporal Cloud using tcld +### Manage Namespaces in Temporal Cloud from the CLI -To list Namespaces and get information about them, use the following [tcld](/cloud/tcld/) commands: +To list Namespaces and get information about them, use the following commands: -- [tcld namespace list](/cloud/tcld/namespace/#list) -- [tcld namespace get](/cloud/tcld/namespace/#get) +- [`temporal cloud namespace list`](/cli/command-reference/cloud/namespace#list) or [tcld namespace list](/cloud/tcld/namespace/#list) +- [`temporal cloud namespace get`](/cli/command-reference/cloud/namespace#get) or [tcld namespace get](/cloud/tcld/namespace/#get) -To manage certificates, use the [tcld namespace accepted-client-ca](/cloud/tcld/namespace/#accepted-client-ca) commands. +To manage certificates, use the [`temporal cloud namespace mtls cert-ca`](/cli/command-reference/cloud/namespace#mtls-cert-ca) +or [tcld namespace accepted-client-ca](/cloud/tcld/namespace/#accepted-client-ca) commands. For more information, see [How to manage certificates in Temporal Cloud](/cloud/certificates). -To manage certificate filters, use the [tcld namespace certificate-filters](/cloud/tcld/namespace/#certificate-filters) +To manage certificate filters, use the [`temporal cloud namespace mtls cert-filter`](/cli/command-reference/cloud/namespace#mtls-cert-filter) +or [tcld namespace certificate-filters](/cloud/tcld/namespace/#certificate-filters) commands. For more information, see [How to manage certificate filters in Temporal Cloud](/cloud/certificates#manage-certificate-filters). @@ -385,9 +414,10 @@ reflects the policy in effect when the Workflow Execution was closed. For further questions or concerns, contact [Support](/cloud/support#support-ticket). -### Delete a Namespace using tcld +### Delete a Namespace from the CLI -See the [tcld namespace delete](/cloud/tcld/namespace/#delete) command reference for details. +See the [`temporal cloud namespace delete`](/cli/command-reference/cloud/namespace#delete) or +[tcld namespace delete](/cloud/tcld/namespace/#delete) command reference for details. ### Namespace deletion protection {/* #delete-protection */} @@ -407,15 +437,30 @@ Follow these steps: title="Deletion Protection is enabled by toggling the switch" /> -To enable or disable this feature using [`tcld`](/cloud/tcld), use the following command. Set the value to `true` to +To enable or disable this feature from the CLI, use the following command. Set the value to `true` to enable or `false` to disable: + + + +``` +temporal cloud namespace lifecycle set \ + --namespace \ + --enable-delete-protection +``` + + + + ``` tcld namespace lifecycle set \ --namespace \ --enable-delete-protection ``` + + + ## How to tag a Namespace in Temporal Cloud {/* #tag-a-namespace */} Tags are key-value metadata pairs that can be attached to namespaces in Temporal Cloud to help operators organize, @@ -437,9 +482,10 @@ track, and manage namespaces more easily. - Only [**Account Admins** and **Account Owners**](/cloud/manage-access/roles-and-permissions#account-level-roles) can create and edit tags - All users with access to a namespace can view its tags -### tcld +### Temporal Cloud CLI -See the [tcld namespace tags](/cloud/tcld/namespace/#tags) command reference for details. +See the [`temporal cloud namespace tag`](/cli/command-reference/cloud/namespace#tag) or +[tcld namespace tags](/cloud/tcld/namespace/#tags) command reference for details. ### Terraform diff --git a/docs/cloud/get-started/user-invite.mdx b/docs/cloud/get-started/user-invite.mdx index 1b8a32abef..40889b9563 100644 --- a/docs/cloud/get-started/user-invite.mdx +++ b/docs/cloud/get-started/user-invite.mdx @@ -37,6 +37,35 @@ To invite users using the Temporal Cloud UI: + + +Use the [`temporal cloud user invite`](/cli/command-reference/cloud/user#invite) command. Specify the user's email, an +account-level role, and optionally one or more Namespace permissions. + +Available account roles: `owner` | `admin` | `developer` | `finance-admin` | `read` | `metrics-read`. + +Available Namespace permissions: `admin` | `write` | `read`. + +```command +temporal cloud user invite \ + --email \ + --account-role \ + --namespace-access = +``` + +Repeat `--namespace-access` to grant permissions on more than one Namespace. `--email` takes a single address, so invite +one user per command: + +```command +temporal cloud user invite \ + --email user1@example.com \ + --account-role developer \ + --namespace-access ns1=admin \ + --namespace-access ns2=write +``` + + + Use the [`tcld user invite`](/cloud/tcld/user/#invite) command. Specify the user's email, an account-level role, and diff --git a/docs/cloud/high-availability/enable.mdx b/docs/cloud/high-availability/enable.mdx index 263b22fbc4..7517ed21fb 100644 --- a/docs/cloud/high-availability/enable.mdx +++ b/docs/cloud/high-availability/enable.mdx @@ -22,7 +22,7 @@ Temporal Cloud's [Pricing](/cloud/pricing) page. ## Create a Namespace with High Availability features {/* #create */} -To create a new Namespace with High Availability features, you can use the Temporal Cloud UI or the tcld command line +To create a new Namespace with High Availability features, you can use the Temporal Cloud UI or the command line utility. @@ -39,6 +39,21 @@ utility. + + +At the command line, enter: + +``` +temporal cloud namespace create \ + --name \ + --region \ + --region +``` + +Specify the [region codes](/cloud/regions) as arguments to the two `--region` flags. + + + At the command line, enter: @@ -81,6 +96,23 @@ Temporal Cloud sends an email alert to all Namespace Admins once your Namespace + + +At the command line, enter: + +``` +temporal cloud namespace ha region add \ + --namespace . \ + --region +``` + +Specify the region name (for example, `us-east-1`) of the region where you want to create the replica as an argument to +the `--region` flag. See [Regions](/cloud/regions) for available region names. + +Temporal Cloud sends an email alert once your Namespace is ready for use. + + + At the command line, enter: @@ -241,6 +273,18 @@ With automatic failovers disabled, Temporal Cloud cannot fail your Namespace ove + + +To disable automatic failovers, run the following command in your terminal: + +``` +temporal cloud namespace ha update \ + --namespace . \ + --disable-auto-failover +``` + + + To disable automatic failovers, run the following command in your terminal: @@ -258,7 +302,7 @@ If using API key authentication with the `--api-key` flag, you must add it direc -To restore the default behavior, unselect the option in the Web UI or change `true` to `false` in the CLI command. +To restore the default behavior, unselect the option in the Web UI or pass `--disable-auto-failover=false` in the CLI command. :::note Automatic failovers are always enabled for Same-region Replication @@ -293,6 +337,20 @@ Follow these steps to remove a replica from a Namespace: + + +Run the following command to remove the replica: + +``` +temporal cloud namespace ha region delete \ + --namespace . \ + --region +``` + +See [Regions](/cloud/regions) for available region names. + + + Run the following command to remove the replica: diff --git a/docs/cloud/high-availability/failovers/manage.mdx b/docs/cloud/high-availability/failovers/manage.mdx index 2d832696cb..f49dc226db 100644 --- a/docs/cloud/high-availability/failovers/manage.mdx +++ b/docs/cloud/high-availability/failovers/manage.mdx @@ -22,7 +22,7 @@ import TabItem from '@theme/TabItem'; ## Trigger a failover {/* #trigger-failover */} -You can trigger a failover manually using the Temporal Cloud Web UI, the tcld CLI, or the Cloud Ops API. +You can trigger a failover manually using the Temporal Cloud Web UI, the CLI, or the Cloud Ops API. Manual failovers apply only to Multi-region and Multi-cloud Replication. A [Same-region Replication](/cloud/high-availability#same-region-replication) Namespace fails over automatically between @@ -45,6 +45,21 @@ significant replication lag has a higher likelihood of rolling back Workflow pro + + +To manually trigger a failover, run the following command in your terminal: + +``` +temporal cloud namespace ha failover \ + --namespace . \ + --region +``` + +The `` must be the name of a region (example: `us-east-1`) where the Namespace has a replica that is +ready to be failed over to (replica state is `Activated`). + + + To manually trigger a failover, run the following command in your terminal: @@ -123,7 +138,7 @@ containing an async operation that you can use to track the failover status. :::info Terraform not supported The [Temporal Cloud Terraform provider](https://registry.terraform.io/providers/temporalio/temporalcloud/latest) does -not support triggering failovers. You must use the Web UI, tcld CLI, or Cloud Ops API. +not support triggering failovers. You must use the Web UI, the CLI, or the Cloud Ops API. ::: diff --git a/docs/cloud/manage-access/service-accounts.mdx b/docs/cloud/manage-access/service-accounts.mdx index 30ea3be289..9a076d230b 100644 --- a/docs/cloud/manage-access/service-accounts.mdx +++ b/docs/cloud/manage-access/service-accounts.mdx @@ -44,6 +44,8 @@ Namespace Admins can now manage and create [Namespace-scoped Service Accounts](/ Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level-roles) can manage Service Accounts by creating, viewing, updating, deleting Service Accounts using the following tools: - Temporal Cloud UI +- Temporal CLI with the [Temporal Cloud extension](/cli/cloud) + - Use `temporal cloud service-account --help` for a list of all service-account commands - Temporal Cloud CLI (tcld) - Use `tcld service-account --help` for a list of all service-account commands @@ -52,14 +54,14 @@ Account Owner and Global Admin [roles](/cloud/manage-access/users#account-level- ### Prerequisites - A Cloud user account with Account Owner or Global Admin [role](/cloud/manage-access/users#account-level-roles) permissions -- Access to the Temporal Cloud UI or Temporal Cloud CLI (tcld) +- Access to the Temporal Cloud UI, the Temporal CLI with the [Temporal Cloud extension](/cli/cloud), or the Temporal Cloud CLI (tcld) - Enable access to API Keys for your Account - To manage Service Accounts using the Temporal Cloud CLI (tcld), upgrade to the latest version of tcld (v0.18.0 or higher) using `brew upgrade tcld`. - If using a version of tcld less than v0.31.0, enable Service Account commands with `tcld feature toggle-service-account`. ### Create a Service Account -Create a Service Account using the Temporal Cloud UI or tcld. +Create a Service Account using the Temporal Cloud UI or the CLI. While User identities are invited to Temporal Cloud, Service Accounts are created in Temporal Cloud. @@ -80,6 +82,21 @@ While User identities are invited to Temporal Cloud, Service Accounts are create - It is recommended to create an API Key for the Service Account right after you create the Service Account, though you can create/manage API Keys for Service Accounts at any time - See the API Key [documentation](/cloud/api-keys) for more information on creating and managing API Keys + + + +To create a Service Account, use the `temporal cloud service-account create` command: + +``` +temporal cloud service-account create --name "sa_test" --description "this is a test SA" --account-role read +``` + +This example creates a Service Account with the name `sa_test`, description `this is a test SA`, and a `read` Account Role. + +Creating a Service Account requires `--name` and `--account-role`. +You can also grant Namespace Permissions with the `--namespace-access` flag, in the format `namespace=permission`. Repeat the flag to grant access to more than one Namespace. +Creating a Service Account returns the Service Account ID, which you use to retrieve, update, or delete the Service Account. + @@ -100,7 +117,7 @@ Creating a Service Account returns the `ServiceAccountId` which is used to retri ### View Service Accounts -View a single or all Service Account(s) using the Temporal Cloud UI or tcld. +View a single or all Service Account(s) using the Temporal Cloud UI or the CLI. @@ -111,6 +128,15 @@ To locate a Service Account: 1. Go to [Settings → Identities](https://cloud.temporal.io/settings/identities) 2. Select the `Service Accounts` filter + + + +To view all Service Accounts in your account, use the `temporal cloud service-account list` command: + +``` +temporal cloud service-account list +``` + @@ -125,7 +151,7 @@ tcld service-account list ### Delete a Service Account -Delete a Service Account using the Temporal Cloud UI or tcld. When you delete a Service Account, all associated API keys are automatically deleted as well. +Delete a Service Account using the Temporal Cloud UI or the CLI. When you delete a Service Account, all associated API keys are automatically deleted as well. Therefore, you don't need to manually remove API keys after deleting a Service Account. @@ -137,6 +163,18 @@ Therefore, you don't need to manually remove API keys after deleting a Service A 4. Select `Delete` 5. Confirm the delete action when prompted + + + +To delete a Service Account, use the `temporal cloud service-account delete` command: + +``` +temporal cloud service-account delete --service-account-id "e9d87418221548" +``` + +Run the Service Account list command to confirm the Service Account has been removed from the account. +The Service Account is deleted when it is no longer visible in the output of the list command. + @@ -154,7 +192,7 @@ The Service Account is deleted when it is no longer visible in the output of the ### Update a Service Account {/* #update */} -Update a Service Account's description using the Temporal Cloud UI or tcld. +Update a Service Account's description using the Temporal Cloud UI or the CLI. @@ -168,6 +206,18 @@ Update a Service Account's description using the Temporal Cloud UI or tcld. 6. Click the `Save` button located in the bottom left of the screen - A status message is displayed at the bottom right corner of the screen + + + +The `temporal cloud service-account update` command changes the name, description, Account Role, and Namespace access of a Service Account: + +``` +temporal cloud service-account update --service-account-id "2f68507677904e09b9bcdbf93380bb95" \ + --description "new description" +``` + +Use `--account-role` to change the Account Role and `--namespace-access` to change Namespace access. For a Namespace-scoped Service Account, use `--namespace-permission` instead. + @@ -211,7 +261,7 @@ Global Admins and Account Owners can also create Namespace-scoped Service Accoun ### Create a Namespace-scoped Service Account -As with regular Service Accounts, Namespace-scoped Service Accounts can be created using Temporal Cloud UI or tcld. +As with regular Service Accounts, Namespace-scoped Service Accounts can be created using the Temporal Cloud UI or the CLI. #### Using the Cloud UI {/* #scoped-ui */} @@ -222,6 +272,15 @@ By clicking on the `Generate API Key` button, a Namespace-scoped Service Account The resulting Namespace-scoped Service Account will be named `-service-account` and will have an `Admin` Namespace permission by default. +#### Using the Temporal CLI + +To create a Namespace-scoped Service Account, use the `temporal cloud service-account create-namespace-scoped` command: + +``` +temporal cloud service-account create-namespace-scoped --name "test-scoped-sa" \ + --namespace "test-ns." --namespace-permission admin +``` + #### Using tcld To create a Namespace-scoped Service Account with tcld, use the `tcld service-account create-scoped` command: diff --git a/docs/cloud/manage-access/user-groups.mdx b/docs/cloud/manage-access/user-groups.mdx index 845e4df86c..2c9a5daeb9 100644 --- a/docs/cloud/manage-access/user-groups.mdx +++ b/docs/cloud/manage-access/user-groups.mdx @@ -68,6 +68,14 @@ User group names must be 3-64 characters long and can only contain lowercase let + +Use the command that matches how the group is backed: + +- [`temporal cloud user-group create-cloud-group`](/cli/command-reference/cloud/user-group#create-cloud-group) for a group managed in Temporal Cloud +- [`temporal cloud user-group create-google-group`](/cli/command-reference/cloud/user-group#create-google-group) for a group backed by a Google group +- [`temporal cloud user-group create-scim-group`](/cli/command-reference/cloud/user-group#create-scim-group) for a group backed by SCIM + + See the [`tcld` user-group create](/cloud/tcld/user-group/#create) command reference for details. @@ -108,6 +116,13 @@ To edit or remove namespace permissions from a group: + +Account-level roles and Namespace-level permissions are set separately: + +- [`temporal cloud user-group set-account-role`](/cli/command-reference/cloud/user-group#set-account-role) +- [`temporal cloud user-group set-namespace-permissions`](/cli/command-reference/cloud/user-group#set-namespace-permissions) + + See the [`tcld` user-group set-access](/cloud/tcld/user-group/#set-access) command reference for details. @@ -137,6 +152,12 @@ To remove a user from the group: + +See the [`temporal cloud user-group members add`](/cli/command-reference/cloud/user-group#members-add), +[`temporal cloud user-group members remove`](/cli/command-reference/cloud/user-group#members-remove), and +[`temporal cloud user-group members list`](/cli/command-reference/cloud/user-group#members-list) command reference for details. + + See the [`tcld` user-group add-users](/cloud/tcld/user-group/#add-users) and the [`tcld` user-group remove-users](/cloud/tcld/user-group/#remove-users) command reference for details. @@ -160,6 +181,10 @@ See the [Terraform provider documentation](https://registry.terraform.io/provide + +See the [`temporal cloud user-group delete`](/cli/command-reference/cloud/user-group#delete) command reference for details. + + See the [`tcld` user-group delete](/cloud/tcld/user-group/#delete) command reference for details. diff --git a/docs/cloud/manage-access/users.mdx b/docs/cloud/manage-access/users.mdx index a2475c2113..f82444ffbe 100644 --- a/docs/cloud/manage-access/users.mdx +++ b/docs/cloud/manage-access/users.mdx @@ -2,7 +2,7 @@ id: users title: Manage users sidebar_label: Manage users -description: Learn how to manage user invitations, account-level roles, and Namespace-level permissions in Temporal Cloud. Invite users, update roles, and delete users seamlessly using the Temporal Web UI, tcld, or the Cloud Ops API. +description: Invite users, set account-level roles and Namespace-level permissions, and remove users from a Temporal Cloud account with the Web UI, the CLI, or the Cloud Ops API. toc_max_heading_level: 4 keywords: - explanation @@ -19,6 +19,9 @@ tags: - Users --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + - [How to invite users to your Temporal Cloud account](#invite-users) - [What are the account-level roles?](#account-level-roles) - [What are the Namespace-level permissions?](#namespace-level-permissions) @@ -106,7 +109,7 @@ For a Namespace, a user can have one of the following permissions: ## How to update an account-level role in Temporal Cloud {/* #update-roles */} -With Global Admin or Account Owner privileges, you can update any user's account-level [role](#account-level-roles) using either the Web UI or the tcld CLI utility. +With Global Admin or Account Owner privileges, you can update any user's account-level [role](#account-level-roles) using either the Web UI or the CLI. The Account Owner role can only be granted by existing Account Owners. For security reasons, changes to the Account Owner role must be made through Temporal Support. @@ -122,15 +125,26 @@ To change or delete an Account Owner, you must submit a [support ticket](https:/ 1. On the **Edit User** page in **Account Level Role**, select the role. 1. Select **Save**. -{/* How to update an account-level role in Temporal Cloud using tcld */} +{/* How to update an account-level role in Temporal Cloud using the CLI */} + +### How to update an account-level role using the CLI + + + + +For details, see the [`temporal cloud user set-account-role`](/cli/command-reference/cloud/user#set-account-role) command. -### How to update an account-level role using tcld + + For details, see the [tcld user set-account-role](/cloud/tcld/user/#set-account-role) command. + + + ## How to update Namespace-level permissions in Temporal Cloud {/* #update-permissions */} -You can update Namespace-level [permissions](#namespace-level-permissions) by using either Web UI or tcld. +You can update Namespace-level [permissions](#namespace-level-permissions) by using either the Web UI or the CLI. {/* How to update Namespace-level permissions for a Namespace in Temporal Cloud using Web UI */} @@ -159,15 +173,26 @@ A user with the Account Owner or Global Admin account-level [role](#account-leve 1. On the **Edit User** page in **Namespace permissions**, change the permissions for one or more Namespaces. 1. Select **Save**. -{/* How to update an account-level role in Temporal Cloud using tcld */} +{/* How to update Namespace-level permissions in Temporal Cloud using the CLI */} + +### How to use the CLI to update Namespace-level permissions + + + -### How to use tcld to update Namespace-level permissions +For details, see the [`temporal cloud user set-namespace-permissions`](/cli/command-reference/cloud/user#set-namespace-permissions) command. + + + For details, see the [tcld user set-namespace-permissions](/cloud/tcld/user/#set-namespace-permissions) command. + + + ## How to delete a user from your Temporal Cloud account {/* #delete-users */} -You can delete a user from your Temporal Cloud Account by using either Web UI or tcld. +You can delete a user from your Temporal Cloud Account by using either the Web UI or the CLI. :::info @@ -188,12 +213,23 @@ You can delete a user in two other ways in Web UI: - User profile page: Select the down arrow next to **Edit User** and then select **Delete**. - **Edit User** page: Select **Delete User**. -{/* How to delete a user from your Temporal Cloud account using tcld */} +{/* How to delete a user from your Temporal Cloud account using the CLI */} + +### How to delete a user using the CLI -### How to delete a user using tcld + + + +For details, see the [`temporal cloud user delete`](/cli/command-reference/cloud/user#delete) command. + + + For details, see the [tcld user delete](/cloud/tcld/user/#delete) command. + + + ## Account-level roles and Namespace-level permissions {/* #account-level-roles-and-namespace-level-permissions */} Temporal account-level roles and Namespace-level permissions provide access to specific Temporal Workflow and Temporal Cloud operational APIs. diff --git a/docs/cloud/tcld/index.mdx b/docs/cloud/tcld/index.mdx index 8d0f8dccab..bf1b93f6a8 100644 --- a/docs/cloud/tcld/index.mdx +++ b/docs/cloud/tcld/index.mdx @@ -17,6 +17,14 @@ tags: The Temporal Cloud CLI (tcld) is a command-line tool that you can use to interact with Temporal Cloud. +:::tip + +The Temporal CLI also manages Temporal Cloud through its +[Temporal Cloud extension](/cli/cloud), which adds `temporal cloud` commands for Namespaces, users, API keys, and Nexus +Endpoints. See the [`temporal cloud` command reference](/cli/command-reference/cloud) for the equivalent commands. + +::: + - [How to install tcld](#install-tcld) ### tcld commands diff --git a/docs/cloud/terraform-provider.mdx b/docs/cloud/terraform-provider.mdx index a1f4ec9355..347e5e01bc 100644 --- a/docs/cloud/terraform-provider.mdx +++ b/docs/cloud/terraform-provider.mdx @@ -12,6 +12,8 @@ ssdi: - The Terraform Provider is in a Public Preview release status for Temporal Cloud. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; The Terraform Temporal Cloud provider allows you to use Terraform to manage resources for Temporal Cloud. The Terraform @@ -67,7 +69,7 @@ Follow these examples to use an environment variable to pass in your API Key to Export your environment variable for secure access to the API Keys. ```bash -# replace with the "secretKey": output from tcld apikey create command +# replace with the "secretKey": output from the apikey create command export TEMPORAL_CLOUD_API_KEY= ``` @@ -82,7 +84,7 @@ Do not confuse environment variables, set with your shell, with temporal env opt Export your environment variable for secure access to the API Keys. ```bash -# replace with the "secretKey": output from tcld apikey create command +# replace with the "secretKey": output from the apikey create command set TEMPORAL_CLOUD_API_KEY= ``` @@ -171,7 +173,7 @@ with API Key based authentication. **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. +You can validate the creation of the Namespace through the Temporal Web UI or through the CLI. **Using the Temporal Web UI** @@ -179,17 +181,30 @@ You can validate the creation of the Namespace through the Temporal Web UI or th 1. Navigate to the Namespaces page. 1. Search for the Namespace you created. -**Using the tcld CLI utility** +**Using the CLI** 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 +or through the `namespace get` command. Run the command and pass in your [Cloud Namespace Name](/cloud/namespaces#temporal-cloud-namespace-name) and [Cloud Account Id](/cloud/namespaces#temporal-cloud-account-id): + + + +```bash +temporal cloud namespace get -n "." +``` + + + + ```bash tcld namespace get -n "." ``` + + + **How do I update a Temporal Cloud Namespace?** Terraform automatically recognizes changes made within `.tf` files and applies those changes to Temporal. @@ -406,8 +421,7 @@ with API Key based authentication. **How do I validate the creation of the Nexus Endpoint?** -You can validate the creation of the Nexus Endpoint through the Temporal Web UI or through the `tcld nexus endpoint get` -command. +You can validate the creation of the Nexus Endpoint through the Temporal Web UI or through the CLI. **Using the Temporal Web UI** @@ -415,17 +429,30 @@ command. 1. Navigate to [the Nexus page](https://cloud.temporal.io/nexus). 1. Search for the Nexus Endpoint you created, using only the Nexus Endpoint Name (without an account suffix). -**Using the tcld CLI utility** +**Using the CLI** Validate the creation of your Nexus Endpoint through the Terraform provider. To validate see your Nexus Endpoint in the -Cloud UI or through the `tcld nexus endpoint get` command. +Cloud UI or through the `nexus endpoint get` command. Run the below command using your Nexus Endpoint Name. Do not use the account ID suffix with this endpoint name: + + + +```bash +temporal cloud nexus endpoint get --name "" +``` + + + + ```bash tcld nexus endpoint get -n "" ``` + + + **How do I update a Nexus Endpoint?** Terraform automatically recognizes changes made within `.tf` files and applies those changes to Temporal. @@ -465,7 +492,7 @@ For example, to change the allowed caller Namespaces on a Nexus Endpoint: ``` Upon completion, you will see a success message indicating your Nexus Endpoint has been updated. It may take several - seconds to update a Nexus Endpoint in the Control Plane which is visible from the Temporal UI or tcld CLI. + seconds to update a Nexus Endpoint in the Control Plane which is visible from the Temporal UI or the CLI. Propagation of Nexus Endpoint changes to the data plane may take longer, but usually complete in less than one minute. @@ -557,7 +584,7 @@ Cautions about Temporal User management: - Follow Terraform best practices for resource management. Manage a specific user in one and only one .tf file. There's a risk that you may overwrite a user's permissions if you don't. - To Import a user, you'll need the User's ID which is currently not available in the Temporal Cloud UI. You can fetch - current User ID by running the `tcld user list` command. + current User ID by running the `temporal cloud user list` or `tcld user list` command. ::: @@ -692,7 +719,7 @@ using the `terraform import` command. resource "temporalcloud_user" "user" { } ``` -1. Run the `terraform import` command and pass in the User ID. Your User ID is available using the Temporal Cloud CLI `tcld u l` command. +1. Run the `terraform import` command and pass in the User ID. Your User ID is available by running `temporal cloud user list` or `tcld u l`. ```bash terraform import temporalcloud_user.user 72360058153949edb2f1d47019c1e85f diff --git a/docs/develop/dotnet/nexus/feature-guide.mdx b/docs/develop/dotnet/nexus/feature-guide.mdx index 9aa9adc028..c8220c1db1 100644 --- a/docs/develop/dotnet/nexus/feature-guide.mdx +++ b/docs/develop/dotnet/nexus/feature-guide.mdx @@ -14,6 +14,8 @@ tags: - .NET SDK --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; Use [Temporal Nexus](/evaluate/nexus) to connect Temporal Applications within and across Namespaces using a Nexus Endpoint, a Nexus Service contract, and Nexus Operations. @@ -519,11 +521,12 @@ See the [Nexus cancellation sample](https://github.com/temporalio/samples-dotnet ## Make Nexus calls across Namespaces in Temporal Cloud {/* #nexus-calls-across-namespaces-temporal-cloud */} This section assumes you are already familiar with how to connect a Worker to Temporal Cloud. -The `tcld` CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. +The Temporal Cloud CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. -### Install the latest `tcld` CLI and generate certificates +### Install `tcld` and generate certificates -To install the latest version of the `tcld` CLI, run the following command (on MacOS): +Certificate generation is only available in `tcld`. To install the latest version of `tcld`, run the following command +(on macOS): ``` brew install temporalio/brew/tcld @@ -542,6 +545,27 @@ These certificates will be valid for one year. Before deploying to Temporal Cloud, ensure that the appropriate Namespaces are created for both the caller and handler. If you already have these Namespaces, you don't need to do this. + + + +``` +temporal cloud login + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + + + ``` tcld login @@ -557,6 +581,8 @@ tcld namespace create \ --ca-certificate-file 'path/to/your/ca.pem' \ --retention-days 1 ``` + + Alternatively, you can create Namespaces through the UI: [https://cloud.temporal.io/Namespaces](https://cloud.temporal.io/Namespaces). @@ -564,6 +590,20 @@ Alternatively, you can create Namespaces through the UI: [https://cloud.temporal To create a Nexus Endpoint you must have a Developer account role or higher, and have NamespaceAdmin permission on the `--target-namespace`. + + + +``` +temporal cloud nexus endpoint create \ + --name nexus-simple-endpoint \ + --target-task-queue nexus-simple-handler-sample \ + --target-namespace \ + --allow-namespace \ + --description-file endpoint_description.md +``` + + + ``` tcld nexus endpoint create \ --name nexus-simple-endpoint \ @@ -572,6 +612,8 @@ tcld nexus endpoint create \ --allow-namespace \ --description-file endpoint_description.md ``` + + The `--allow-namespace` is used to build an Endpoint allowlist of caller Namespaces that can use the Nexus Endpoint, as described in Runtime Access Control. diff --git a/docs/develop/go/nexus/feature-guide.mdx b/docs/develop/go/nexus/feature-guide.mdx index fedf028ca6..28ad1a576c 100644 --- a/docs/develop/go/nexus/feature-guide.mdx +++ b/docs/develop/go/nexus/feature-guide.mdx @@ -16,6 +16,8 @@ tags: - Nexus --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; Use [Temporal Nexus](/evaluate/nexus) to connect Temporal Applications within and across Namespaces using a Nexus Endpoint, a Nexus Service contract, and Nexus Operations. @@ -575,11 +577,12 @@ See the [Nexus cancelation sample](https://github.com/temporalio/samples-go/tree ## Make Nexus calls across Namespaces in Temporal Cloud {/* #nexus-calls-across-namespaces-temporal-cloud */} This section assumes you are already familiar with [how to connect a Worker to Temporal Cloud](/develop/go/client/temporal-client#connect-to-temporal-cloud). -The same [source code](https://github.com/temporalio/samples-go/tree/main/nexus) is used in this section, but the `tcld` CLI will be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. +The same [source code](https://github.com/temporalio/samples-go/tree/main/nexus) is used in this section, but the Temporal Cloud CLI will be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. -### Install the latest `tcld` CLI and generate certificates +### Install `tcld` and generate certificates -To install the latest version of the `tcld` CLI, run the following command (on MacOS): +Certificate generation is only available in `tcld`. To install the latest version of `tcld`, run the following command +(on macOS): ``` brew install temporalio/brew/tcld @@ -598,6 +601,27 @@ These certificates will be valid for one year. Before deploying to Temporal Cloud, ensure that the appropriate Namespaces are created for both the caller and handler. If you already have these Namespaces, you don't need to do this. + + + +``` +temporal cloud login + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + + + ``` tcld login @@ -615,6 +639,8 @@ tcld namespace create \ --ca-certificate-file 'path/to/your/ca.pem' \ --retention-days 1 ``` + + Alternatively, you can create Namespaces through the UI: [https://cloud.temporal.io/Namespaces](https://cloud.temporal.io/Namespaces). @@ -622,6 +648,19 @@ Alternatively, you can create Namespaces through the UI: [https://cloud.temporal To create a Nexus Endpoint you must have a Developer account role or higher, and have NamespaceAdmin permission on the `--target-namespace`. + + + +``` +temporal cloud nexus endpoint create \ + --name \ + --target-task-queue my-handler-task-queue \ + --target-namespace \ + --description-file description.md +``` + + + ``` tcld nexus endpoint create \ --name \ @@ -629,6 +668,8 @@ tcld nexus endpoint create \ --target-namespace \ --description-file description.md ``` + + Alternatively, you can create a Nexus Endpoint through the UI: [https://cloud.temporal.io/nexus](https://cloud.temporal.io/nexus). diff --git a/docs/develop/java/nexus/feature-guide.mdx b/docs/develop/java/nexus/feature-guide.mdx index c86d643ccf..6f56afb121 100644 --- a/docs/develop/java/nexus/feature-guide.mdx +++ b/docs/develop/java/nexus/feature-guide.mdx @@ -15,6 +15,8 @@ tags: - Java SDK --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; Use [Temporal Nexus](/evaluate/nexus) to connect Temporal Applications within and across Namespaces using a Nexus @@ -679,13 +681,14 @@ for reference. This section assumes you are already familiar with [how connect a Worker to Temporal Cloud](/develop/java/client/temporal-client#start-workflow-execution). The same -[source code](https://github.com/temporalio/samples-go/tree/main/nexus) is used in this section, but the `tcld` CLI will -be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the +[source code](https://github.com/temporalio/samples-go/tree/main/nexus) is used in this section, but the Temporal Cloud +CLI will be used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. -### Install the latest `tcld` CLI and generate certificates +### Install `tcld` and generate certificates -To install the latest version of the `tcld` CLI, run the following command (on MacOS): +Certificate generation is only available in `tcld`. To install the latest version of `tcld`, run the following command +(on macOS): ``` brew install temporalio/brew/tcld @@ -704,6 +707,27 @@ These certificates will be valid for one year. Before deploying to Temporal Cloud, ensure that the appropriate Namespaces are created for both the caller and handler. If you already have these Namespaces, you don't need to do this. + + + +``` +temporal cloud login + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + + + ``` tcld login @@ -721,6 +745,8 @@ tcld namespace create \ --ca-certificate-file 'path/to/your/ca.pem' \ --retention-days 1 ``` + + Alternatively, you can create Namespaces through the UI: [https://cloud.temporal.io/Namespaces](https://cloud.temporal.io/Namespaces). @@ -730,6 +756,20 @@ Alternatively, you can create Namespaces through the UI: To create a Nexus Endpoint you must have a Developer account role or higher, and have NamespaceAdmin permission on the `--target-namespace`. + + + +``` +temporal cloud nexus endpoint create \ + --name \ + --target-task-queue my-handler-task-queue \ + --target-namespace \ + --allow-namespace \ + --description-file ./core/src/main/java/io/temporal/samples/nexus/service/description.md +``` + + + ``` tcld nexus endpoint create \ --name \ @@ -738,6 +778,8 @@ tcld nexus endpoint create \ --allow-namespace \ --description-file ./core/src/main/java/io/temporal/samples/nexus/service/description.md ``` + + The `--allow-namespace` is used to build an Endpoint allowlist of caller Namespaces that can use the Nexus Endpoint, as described in Runtime Access Control. diff --git a/docs/develop/python/nexus/feature-guide.mdx b/docs/develop/python/nexus/feature-guide.mdx index 0d540179da..807e6f26cf 100644 --- a/docs/develop/python/nexus/feature-guide.mdx +++ b/docs/develop/python/nexus/feature-guide.mdx @@ -15,6 +15,8 @@ tags: - Python SDK --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from '@site/src/components'; Use [Temporal Nexus](/evaluate/nexus) to connect Temporal Applications within and across Namespaces using a Nexus Endpoint, a Nexus Service contract, and Nexus Operations. @@ -361,11 +363,12 @@ See the [Nexus cancellation sample](https://github.com/temporalio/samples-python ## Make Nexus calls across Namespaces in Temporal Cloud {/* #nexus-calls-across-namespaces-temporal-cloud */} This section assumes you are already familiar with how to connect a Worker to Temporal Cloud. -The `tcld` CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. +The Temporal Cloud CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. -### Install the latest `tcld` CLI and generate certificates +### Install `tcld` and generate certificates -To install the latest version of the `tcld` CLI, run the following command (on macOS): +Certificate generation is only available in `tcld`. To install the latest version of `tcld`, run the following command +(on macOS): ``` brew install temporalio/brew/tcld @@ -384,6 +387,27 @@ These certificates will be valid for one year. Before deploying to Temporal Cloud, ensure that the appropriate Namespaces are created for both the caller and handler. If you already have these Namespaces, you don't need to do this. + + + +``` +temporal cloud login + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + + + ``` tcld login @@ -401,6 +425,8 @@ tcld namespace create \ --ca-certificate-file 'path/to/your/ca.pem' \ --retention-days 1 ``` + + Alternatively, you can create Namespaces through the UI: [https://cloud.temporal.io/Namespaces](https://cloud.temporal.io/Namespaces). @@ -408,6 +434,20 @@ Alternatively, you can create Namespaces through the UI: [https://cloud.temporal To create a Nexus Endpoint you must have a Developer account role or higher, and have NamespaceAdmin permission on the `--target-namespace`. + + + +``` +temporal cloud nexus endpoint create \ + --name \ + --target-task-queue my-handler-task-queue \ + --target-namespace \ + --allow-namespace \ + --description-file hello_nexus/endpoint_description.md +``` + + + ``` tcld nexus endpoint create \ --name \ @@ -416,6 +456,8 @@ tcld nexus endpoint create \ --allow-namespace \ --description-file hello_nexus/endpoint_description.md ``` + + The `--allow-namespace` is used to build an Endpoint allowlist of caller Namespaces that can use the Nexus Endpoint, as described in Runtime Access Control. diff --git a/docs/develop/typescript/nexus/feature-guide.mdx b/docs/develop/typescript/nexus/feature-guide.mdx index 1a31c47382..baf0307960 100644 --- a/docs/develop/typescript/nexus/feature-guide.mdx +++ b/docs/develop/typescript/nexus/feature-guide.mdx @@ -14,6 +14,8 @@ tags: - TypeScript SDK --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import { CaptionedImage } from "@site/src/components"; Use [Temporal Nexus](/evaluate/nexus) to connect Temporal Applications within and across Namespaces using a Nexus Endpoint, a Nexus Service contract, and Nexus Operations. @@ -367,11 +369,12 @@ To ensure cancellations are delivered, wait for all pending operations to finish ## Make Nexus calls across Namespaces in Temporal Cloud {/* #nexus-calls-across-namespaces-temporal-cloud */} This section assumes you are already familiar with how to connect a Worker to Temporal Cloud. -The `tcld` CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. +The Temporal Cloud CLI is used to create Namespaces and the Nexus Endpoint, and mTLS client certificates will be used to securely connect the caller and handler Workers to their respective Temporal Cloud Namespaces. -### Install the latest `tcld` CLI and generate certificates +### Install `tcld` and generate certificates -To install the latest version of the `tcld` CLI, run the following command (on macOS): +Certificate generation is only available in `tcld`. To install the latest version of `tcld`, run the following command +(on macOS): ``` brew install temporalio/brew/tcld @@ -390,6 +393,27 @@ These certificates will be valid for one year. Before deploying to Temporal Cloud, ensure that the appropriate Namespaces are created for both the caller and handler. If you already have these Namespaces, you don't need to do this. + + + +``` +temporal cloud login + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 + +temporal cloud namespace create \ + --name \ + --region aws-us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + + + ``` tcld login @@ -407,6 +431,8 @@ tcld namespace create \ --ca-certificate-file 'path/to/your/ca.pem' \ --retention-days 1 ``` + + Alternatively, you can create Namespaces through the UI: [https://cloud.temporal.io/namespaces](https://cloud.temporal.io/namespaces). @@ -414,6 +440,20 @@ Alternatively, you can create Namespaces through the UI: [https://cloud.temporal To create a Nexus Endpoint you must have a Developer account role or higher, and have NamespaceAdmin permission on the `--target-namespace`. + + + +``` +temporal cloud nexus endpoint create \ + --name \ + --target-task-queue my-handler-task-queue \ + --target-namespace \ + --allow-namespace \ + --description-file description.md +``` + + + ``` tcld nexus endpoint create \ --name \ @@ -422,6 +462,8 @@ tcld nexus endpoint create \ --allow-namespace \ --description-file description.md ``` + + The `--allow-namespace` is used to build an Endpoint allowlist of caller Namespaces that can use the Nexus Endpoint, as described in Runtime Access Control. diff --git a/docs/troubleshooting/last-connection-error.mdx b/docs/troubleshooting/last-connection-error.mdx index 59e8973055..112fd12c34 100644 --- a/docs/troubleshooting/last-connection-error.mdx +++ b/docs/troubleshooting/last-connection-error.mdx @@ -12,6 +12,9 @@ tags: - Namespaces --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + The message `Failed reaching server: last connection error` can often result from an expired TLS certificate or during the Server startup process, in which the Client requests reach the Server before the roles are fully initialized. This troubleshooting guide shows you how to do the following: @@ -31,12 +34,28 @@ Choose one of the following methods to verify the expiration date of the TLS cer List the expiration date with the following command: + + + +```command +temporal cloud namespace mtls cert-ca list \ + --namespace . +``` + +Read the expiration date from the certificate details in the output. + + + + ```command tcld namespace accepted-client-ca list \ --namespace . | \ jq -r '.[0].notAfter' ``` + + + If the returned date is in the past, the certificate has expired. **Existing certificate management infrastructure** diff --git a/src/constants/featureReleaseTypes.js b/src/constants/featureReleaseTypes.js index 3c0e0e6b9b..e26d9ceac1 100644 --- a/src/constants/featureReleaseTypes.js +++ b/src/constants/featureReleaseTypes.js @@ -1,7 +1,7 @@ // ⚠️ LLM MARKDOWN PIPELINE: also consumed by scripts/mdx-to-md.mjs for // ReleaseNoteHeader label resolution. Keep in sync when adding feature mappings. export const FEATURE_RELEASE_TYPES = { - cloudCli: "prerelease", + cloudCli: "publicPreview", standaloneActivity: "publicPreview", standaloneNexusOperation: "prerelease", workflowStreams: "publicPreview",