Skip to main content

Temporal Cloud IP addresses

By default, Temporal Cloud resources use dynamic IP addresses that may change at any time. These IP addresses may be any IPs within the IP ranges published by the relevant cloud provider.

If you need to limit outbound access from your client network, we recommend using AWS PrivateLink or GCP Private Services Connect. Alternatively, you can enable Stable IPs for your Namespace.

Do not allowlist default dynamic IP addresses

By default, Temporal Cloud IPs are not static and may change without notice.

Do not allowlist specific IP addresses you see Temporal Cloud services using at a point in time, as this will cause an outage when those IPs change. Your clients will not be able to connect to Temporal Cloud.

If you have to allowlist IP ranges without using Stable IPs, you must allowlist the entire cloud provider IP range:

Stable IP addresses​

Stable IPs is an optional Namespace setting that provides a fixed, published set of IP addresses for your Namespace endpoint. When enabled, Workers and Temporal Clients connecting to your Namespace through its Namespace endpoint will resolve to a predictable set of IP addresses that you can allowlist in your firewall.

When to use Stable IPs​

Use Stable IPs when your security requirements mandate IP-based allowlisting for egress traffic, and you cannot use AWS PrivateLink or GCP Private Services Connect.

Recommended options for secure connectivity (in order):

  1. AWS PrivateLink or GCP Private Services Connect - Keep traffic within your cloud provider's private network
  2. Stable IPs - Use published, stable IP ranges for firewall allowlisting
  3. Cloud provider IP ranges - Allowlist all AWS or GCP IP ranges (overly permissive)

Stable IPs provide enterprise-grade compliance for organizations that require IP-based security controls but cannot use private network connectivity options.

How Stable IPs work​

When Stable IPs are enabled on a Namespace:

  • The Namespace endpoint (<namespace>.<account>.tmprl.cloud) resolves to IP addresses from a published list of Stable IPs
    • The list is grouped by cloud region. The Namespace endpoint will resolve to an IP from the group for the Namespace's active region.
  • Workers and Temporal Clients connecting via the Namespace endpoint will connect to these stable IP addresses
  • Regional endpoints continue to work but resolve to dynamic IP addresses
  • For replicated Namespaces, the Stable IP corresponds to the Namespace's active region. During failover to a different region, DNS updates to point to a Stable IP in the new active region.

Important: Stable IPs apply only to Namespace traffic, sometimes called the "data plane." The Temporal Cloud management plane, observability endpoints, and Web UI do not have stable public IP addresses.

How to enable Stable IPs​

Stable IPs is a setting on a public Connectivity Rule. You enable it by creating (or updating) a public Connectivity Rule with Stable IPs enabled, then attaching that rule to the Namespaces that should resolve to Stable IPs.

You can manage Connectivity Rules through the Cloud Ops API, Terraform provider, or tcld CLI. There is no UI option at this time.

To enable Stable IPs:

  1. Create a public Connectivity Rule with Stable IPs enabled (for example, tcld connectivity-rule create --connectivity-type public --enable-stable-ips). Only one public Connectivity Rule exists per account, so if you already have one, update or recreate it with Stable IPs enabled.
  2. Attach the rule to your Namespace with tcld namespace set-connectivity-rules (or the equivalent Cloud Ops API or Terraform call).
  3. Retrieve the list of Stable IPs from the public API (see below).
  4. Configure your firewall to allowlist the Stable IP ranges for your Namespace's region.
  5. Ensure your Workers and Temporal Clients connect using the Namespace endpoint, not regional endpoints.

You can enable Stable IPs on new Namespaces at creation time or on existing Namespaces. The Cloud Ops API field is enable_stable_ips on the PublicConnectivityRule message and requires Cloud Ops API v0.15.0 or later.

DNS propagation: When enabling Stable IPs on an existing Namespace, Temporal updates DNS records to point the Namespace endpoint to Stable IPs. DNS propagation typically takes 5 to 15 minutes for AWS, but can take up to 60 minutes or longer if you have custom TTLs configured.

How to enable Stable IPs with curl​

If you cannot use tcld or Terraform, you can drive the Cloud Ops API directly. The following walkthrough creates a public Connectivity Rule with Stable IPs enabled and attaches it to a Namespace.

All requests require two headers:

  • Authorization: Bearer $TEMPORAL_CLOUD_API_KEY
  • temporal-cloud-api-version: v0.16.0 (or any version ≥ v0.15.0)

Base URL: https://saas-api.tmprl.cloud

Set up environment variables:

export TEMPORAL_CLOUD_API_KEY='<paste-api-key>'
export NS='<namespace>.<account>'   # The Cloud-side Namespace identifier, e.g. "myns.a1b2c3"
H_AUTH="Authorization: Bearer $TEMPORAL_CLOUD_API_KEY"
H_VER="temporal-cloud-api-version: v0.16.0"

Step 1. Read the current Namespace spec and resource version.

UpdateNamespace replaces the entire spec and requires the latest resource_version. Fetch them first:

curl -sS "https://saas-api.tmprl.cloud/cloud/namespaces/$NS" \
  -H "$H_AUTH" -H "$H_VER" | tee /tmp/ns.json | \
  jq '{resource_version: .namespace.resourceVersion, connectivity_rule_ids: .namespace.spec.connectivityRuleIds}'

RV=$(jq -r '.namespace.resourceVersion' /tmp/ns.json)

Step 2. Create a public Connectivity Rule with Stable IPs enabled.

curl -sS -X POST "https://saas-api.tmprl.cloud/cloud/connectivity-rules" \
  -H "$H_AUTH" -H "$H_VER" -H "Content-Type: application/json" \
  -d '{
        "spec": {
          "publicRule": { "enableStableIps": true }
        }
      }' | tee /tmp/cr.json

CR_ID=$(jq -r '.connectivityRuleId' /tmp/cr.json)
OP_ID=$(jq -r '.asyncOperation.id // .asyncOperation.operationId' /tmp/cr.json)

Field names follow proto3 JSON camelCase: enable_stable_ips becomes enableStableIps.

Step 3. Wait for the create operation to reach a terminal state.

curl -sS "https://saas-api.tmprl.cloud/cloud/operations/$OP_ID" \
  -H "$H_AUTH" -H "$H_VER" | jq '.asyncOperation.state'

Re-run until state is FULFILLED (the rule is now ACTIVE). Any *_FAILED state means you should stop and inspect the operation.

Step 4. Attach the rule to the Namespace.

UpdateNamespace posts the whole NamespaceSpec back. Mutate the spec from Step 1 by appending $CR_ID to connectivityRuleIds:

jq --arg id "$CR_ID" --arg rv "$RV" --arg ns "$NS" '
  {
    namespace: $ns,
    resourceVersion: $rv,
    spec: (.namespace.spec
           | .connectivityRuleIds = ((.connectivityRuleIds // []) + [$id]))
  }' /tmp/ns.json > /tmp/update.json

curl -sS -X POST "https://saas-api.tmprl.cloud/cloud/namespaces/$NS" \
  -H "$H_AUTH" -H "$H_VER" -H "Content-Type: application/json" \
  -d @/tmp/update.json | tee /tmp/update-resp.json

Poll the returned asyncOperation the same way as Step 3.

Gotchas:

  • The namespace in the URL is the Cloud-side Namespace identifier (for example, myns.a1b2c3), not the SDK gRPC hostname (myns.a1b2c3.tmprl.cloud). Strip the trailing .tmprl.cloud.
  • Do not omit fields from spec in Step 4. Proto3 update is full-replace — any field left out will be cleared. Building the body from the GET response avoids surprises.
  • A Namespace can have at most one public Connectivity Rule attached, and only one public rule exists per account. If connectivityRuleIds already references a public rule without Stable IPs, replace that entry instead of appending — you cannot create a second public rule.
  • Stable IPs requires temporal-cloud-api-version of v0.15.0 or later.

How to enable Stable IPs with gRPC​

If you prefer to call the Cloud Ops API directly over gRPC (for example, with grpcurl or a generated client), the same flow uses the CloudService gRPC API. Proto definitions live in temporal/api/cloud/cloudservice/v1/service.proto and temporal/api/cloud/connectivityrule/v1/message.proto.

  • Endpoint: saas-api.tmprl.cloud:443 (TLS required)
  • Fully qualified service: temporal.api.cloud.cloudservice.v1.CloudService
  • Required metadata on every call:
    • authorization: Bearer $TEMPORAL_CLOUD_API_KEY
    • temporal-cloud-api-version: v0.16.0 (or any version ≥ v0.15.0)

The examples below use grpcurl. They assume you have a local checkout of temporalio/api-cloud at ./api-cloud and a proto/ directory containing the standard google/api/annotations.proto and friends.

Set up environment variables:

export TEMPORAL_CLOUD_API_KEY='<paste-api-key>'
export NS='<namespace>.<account>'   # The Cloud-side Namespace identifier, e.g. "myns.a1b2c3"
GRPC_HEADERS=(-H "authorization: Bearer $TEMPORAL_CLOUD_API_KEY" -H "temporal-cloud-api-version: v0.16.0")
PROTO_FLAGS=(-import-path ./api-cloud -import-path ./proto -proto temporal/api/cloud/cloudservice/v1/service.proto)

Step 1. Read the current Namespace spec and resource version.

grpcurl "${PROTO_FLAGS[@]}" "${GRPC_HEADERS[@]}" \
  -d "{\"namespace\": \"$NS\"}" \
  saas-api.tmprl.cloud:443 \
  temporal.api.cloud.cloudservice.v1.CloudService/GetNamespace | tee /tmp/ns.json

RV=$(jq -r '.namespace.resourceVersion' /tmp/ns.json)

Step 2. Create a public Connectivity Rule with Stable IPs enabled.

grpcurl "${PROTO_FLAGS[@]}" "${GRPC_HEADERS[@]}" \
  -d '{
        "spec": {
          "public_rule": { "enable_stable_ips": true }
        }
      }' \
  saas-api.tmprl.cloud:443 \
  temporal.api.cloud.cloudservice.v1.CloudService/CreateConnectivityRule | tee /tmp/cr.json

CR_ID=$(jq -r '.connectivityRuleId' /tmp/cr.json)
OP_ID=$(jq -r '.asyncOperation.id' /tmp/cr.json)

Field names in gRPC JSON requests can use either snake_case (proto field names) or camelCase — grpcurl accepts both. Responses come back in camelCase.

Step 3. Wait for the create operation to reach a terminal state.

grpcurl "${PROTO_FLAGS[@]}" "${GRPC_HEADERS[@]}" \
  -d "{\"async_operation_id\": \"$OP_ID\"}" \
  saas-api.tmprl.cloud:443 \
  temporal.api.cloud.cloudservice.v1.CloudService/GetAsyncOperation | jq '.asyncOperation.state'

Re-run until state is FULFILLED (the rule is now ACTIVE). Any *_FAILED state means you should stop and inspect the operation.

Step 4. Attach the rule to the Namespace.

UpdateNamespace posts the whole NamespaceSpec back. Mutate the spec from Step 1 by appending $CR_ID to connectivity_rule_ids:

jq --arg id "$CR_ID" --arg rv "$RV" --arg ns "$NS" '
  {
    namespace: $ns,
    resource_version: $rv,
    spec: (.namespace.spec
           | .connectivity_rule_ids = ((.connectivityRuleIds // []) + [$id]))
  }' /tmp/ns.json > /tmp/update.json

grpcurl "${PROTO_FLAGS[@]}" "${GRPC_HEADERS[@]}" \
  -d @ \
  saas-api.tmprl.cloud:443 \
  temporal.api.cloud.cloudservice.v1.CloudService/UpdateNamespace < /tmp/update.json | tee /tmp/update-resp.json

Poll the returned asyncOperation the same way as Step 3.

Gotchas:

  • The namespace field is the Cloud-side Namespace identifier (for example, myns.a1b2c3), not the SDK gRPC hostname (myns.a1b2c3.tmprl.cloud). Strip the trailing .tmprl.cloud.
  • Do not omit fields from spec in Step 4. Proto3 update is full-replace — any field left out will be cleared. Building the body from the GetNamespace response avoids surprises.
  • A Namespace can have at most one public Connectivity Rule attached, and only one public rule exists per account. If connectivity_rule_ids already references a public rule without Stable IPs, replace that entry instead of appending — you cannot create a second public rule.
  • Stable IPs requires temporal-cloud-api-version of v0.15.0 or later.
  • Authentication uses Cloud API keys; mTLS client certificates are not accepted on saas-api.tmprl.cloud. The metadata key is authorization (lowercase), per the gRPC convention.

How to view Stable IP ranges​

Retrieve the list of Stable IP ranges from the public API:

GET https://saas-api.tmprl.cloud/stable-ip-ranges

This API is publicly accessible without authentication and returns a JSON response grouped by cloud provider and region:

{
  "all_stable_ip_ranges": [
    "34.195.80.228/32",
    "34.195.80.10/30",
    "44.235.214.171/32"
  ],
  "clouds": {
    "aws": {
      "regions": {
        "us-east-1": {
          "stable_ip_ranges": [
            "34.195.80.228/32",
            "34.195.80.10/30"
          ]
        },
        "us-west-2": {
          "stable_ip_ranges": [
            "44.235.214.171/32"
          ]
        }
      }
    },
    "gcp": {
      "regions": {
        ...
      }
    }
  }
}

You can also load this URL in a browser to view the list.

IP format: IP addresses are provided in IPv4 or IPv6 format with CIDR notation. At launch, Temporal uses predominantly /32 ranges (single IP addresses). Each region typically contains approximately 6 IP addresses.

How to connect using Stable IPs​

To connect to a Namespace with Stable IPs enabled:

  1. Use the Namespace endpoint: Configure Workers and Temporal Clients to use the Namespace endpoint format: <namespace>.<account>.tmprl.cloud:7233
  2. Do not use Regional endpoints: Regional endpoints (<region>.<cloud>.api.temporal.io) will route to the Namespace but resolve to dynamic IP addresses
  3. Do not use PrivateLink: PrivateLink endpoints do not resolve to Stable IPs. To use Stable IPs, connect over public endpoints.

Authentication: Stable IPs work with both mTLS certificate-based authentication and API key authentication.

Network routing: If your Workers run on the same cloud provider as your Namespace (for example, both on AWS), traffic stays on the cloud provider's backbone network and does not traverse the public internet, even when using public Stable IPs. AWS, GCP, and Azure all guarantee that traffic between locations on their networks never leaves their backbone.

How to migrate to Stable IPs​

When you enable Stable IPs on an existing Namespace:

Workers using Namespace endpoints:

  • Existing connections continue uninterrupted
  • DNS updates to point the Namespace endpoint to Stable IPs
  • Existing connections remain connected to their current dynamic IP
  • New connections automatically use Stable IPs after DNS propagates
  • No Worker restart required

Workers using Regional endpoints:

  • Existing connections continue uninterrupted
  • To use Stable IPs, update Worker configuration to use the Namespace endpoint and restart Workers

Workers using PrivateLink:

  • Existing connections continue uninterrupted through PrivateLink
  • To use Stable IPs, update Worker configuration to use the Namespace endpoint and restart Workers
  • Note: You cannot use both PrivateLink and Stable IPs simultaneously

Connectivity Rules: Stable IPs is set as the enable_stable_ips flag on a public Connectivity Rule. Every Namespace that should resolve to Stable IPs must have that public Connectivity Rule attached. Namespaces without the rule attached continue to resolve to dynamic IPs.

If your Namespace is currently reached over AWS PrivateLink and protected by a private Connectivity Rule, the safe migration path is to add the public path while the private path is still working, verify, and then remove the private path. This applies whether your Namespace is single-region or replicated.

Prerequisites:

  • Note your existing private (PrivateLink) Connectivity Rule ID — you'll keep it attached during the overlap window.
  • Check whether your account already has a public Connectivity Rule. Only one is allowed per account; if one exists without Stable IPs enabled, you'll need to delete and recreate it (see Permissions and limits).
  • Confirm that the VPCs and security groups that host your Workers and Temporal Clients allow egress to the Stable IP ranges on port 443. If your egress is currently locked down to the PrivateLink VPC endpoint, you must expand it first.

Steps:

  1. Allowlist Stable IPs in your firewall first. Fetch the IP ranges for your Namespace's region from https://saas-api.tmprl.cloud/stable-ip-ranges and add them to your egress allowlist before changing anything else. If you skip this, the cutover will black-hole traffic.

  2. Create (or update) the account's public Connectivity Rule with Stable IPs enabled.

    tcld connectivity-rule create --connectivity-type public --enable-stable-ips

    If you already have a public Connectivity Rule without Stable IPs, delete and recreate it — there is no in-place update flag, and creating a second public rule returns an error. Wait for the rule to reach ACTIVE before continuing.

  3. Attach both rules to the Namespace simultaneously. Connectivity Rules attach as a set (full replace), so include the existing private rule ID and the new public rule ID in one call:

    tcld namespace set-connectivity-rules \
      --namespace "<namespace>.<account>" \
      --connectivity-rule-ids "<private-rule-id>" \
      --connectivity-rule-ids "<public-rule-id>"

    Workers continue to use PrivateLink at this point, because your private DNS still resolves the Namespace endpoint to the VPC endpoint. The public path is now allowed on Temporal's side but not yet used.

  4. Switch client DNS resolution from PrivateLink to public. This is the actual cutover. Remove the private DNS override — Route 53 private hosted zone, /etc/hosts, or VPC DNS resolver rules — so that <namespace>.<account>.tmprl.cloud resolves through public DNS to a Stable IP. Restart Workers to drop existing PrivateLink connections and force re-resolution.

  5. Verify traffic is flowing over Stable IPs. On a Worker host, run dig <namespace>.<account>.tmprl.cloud and confirm the answer is a Stable IP from the /stable-ip-ranges list, not your VPC endpoint IP. Confirm Workers are polling and there are no RESOURCE_EXHAUSTED or connection errors in their logs.

  6. Detach the private Connectivity Rule. Once you are confident all traffic is on the public path, remove the private rule by re-attaching only the public rule:

    tcld namespace set-connectivity-rules \
      --namespace "<namespace>.<account>" \
      --connectivity-rule-ids "<public-rule-id>"

  7. (Optional) Tear down the PrivateLink VPC endpoint in AWS to stop incurring PrivateLink hourly and data-processing charges. Do not do this until step 6 has been stable for at least a few hours.

Gotchas:

  • Do not remove the private Connectivity Rule before step 4. If you detach the private rule while Workers are still resolving the Namespace endpoint to the PrivateLink VPC endpoint, Temporal Cloud will block those connections at the edge.
  • A single connection uses one network path or the other. Workers connect over either PrivateLink or Stable IPs based on DNS resolution at connect time. There is no in-place switch without dropping the connection — that's why step 4 includes a Worker restart.
  • Same-region traffic still stays on the AWS backbone over Stable IPs (since both your Worker and the Namespace are in AWS), so you do not lose the "does not traverse the public internet" property by moving off PrivateLink.
  • TLS and SNI do not change. You are still hitting the Namespace endpoint (<namespace>.<account>.tmprl.cloud); only the IP it resolves to changes. mTLS and API key authentication continue to work unchanged.

Changes to Stable IP ranges​

Temporal aims to keep Stable IP ranges consistent. Each Stable IP address is expected to remain active for at least 12 months.

When Stable IPs are added:

  1. New IP ranges appear in the API response before traffic is routed to them
  2. Update your firewall to include the new ranges
  3. Temporal announces the activation date in the Temporal Cloud changelog
  4. Traffic begins routing to new IP ranges on the announced date

If a Stable IP must be removed (rare):

  1. The IP range is marked as deprecated and removed from the API response
  2. Traffic continues to route through the deprecated IP for a 3-month deprecation period
  3. Temporal announces the deprecation and removal date in the changelog and documentation
  4. After the deprecation period, traffic stops routing to the deprecated IP

Temporal will never route traffic to IP addresses that are not listed in the API response.

Regional availability​

Stable IPs are rolling out by cloud provider and region:

  • AWS: Starting with us-west-2, expanding to all regions
  • GCP: Rolling out to regions following AWS
  • New regions: All new Temporal Cloud regions include Stable IPs at launch

Contact Temporal support if you need Stable IPs in a region that does not yet have them. Temporal may be able to prioritize enabling Stable IPs in your region.

Pricing​

Temporal Cloud does not charge additional fees for using Stable IPs.

How to disable Stable IPs​

You can disable Stable IPs on a Namespace using the Cloud Ops API, Terraform, or CLI. Temporal performs a DNS update to point the Namespace endpoint back to dynamic IP addresses.

Existing Worker connections are not interrupted. New Worker connections will no longer resolve to Stable IPs after DNS propagates.