From 38929f6bfdfec93aa146bbf1539c4da54b5e5a32 Mon Sep 17 00:00:00 2001 From: "skill-sync[bot]" Date: Fri, 7 Aug 2026 20:05:10 +0000 Subject: [PATCH 1/4] Finalize draft for 0005-nexus-caller-limits --- SKILL.md | 2 + references/ops/cloud-ops-api.md | 2 +- references/ops/nexus-caller-limits.md | 198 ++++++++++++++++++++++++++ references/triage/connectivity.md | 4 +- 4 files changed, 203 insertions(+), 3 deletions(-) create mode 100644 references/ops/nexus-caller-limits.md diff --git a/SKILL.md b/SKILL.md index 9b656c3..01d38eb 100644 --- a/SKILL.md +++ b/SKILL.md @@ -135,6 +135,7 @@ Find the row that matches the user's intent. The reference file contains the com | Set up PrivateLink / PSC, manage connectivity rules | Cloud connectivity | [cloud-connectivity.md](references/ops/cloud-connectivity.md) | | Self-hosted cluster health, describe, namespace CRUD | Self-hosted admin | [self-hosted-admin.md](references/ops/self-hosted-admin.md) | | Self-hosted search attributes, Nexus endpoints | Self-hosted admin | [self-hosted-admin.md](references/ops/self-hosted-admin.md) | +| Check or manage a Cloud Nexus Endpoint's caller-Namespace allowlist; understand or raise the 1,000-caller default | Nexus caller limits | [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) | | Find stuck/hung/unhealthy workflows via list queries | Workflow health | [workflow-health.md](references/ops/workflow-health.md) | | Task queue poller status, workflow counts | Workflow health | [workflow-health.md](references/ops/workflow-health.md) | | Cancel, terminate, or reset workflows | Workflow recovery | [workflow-stuck.md#recovery-commands](references/triage/workflow-stuck.md#recovery-commands) | @@ -268,6 +269,7 @@ If the layer above the fix is still failing, return to step 4 and continue walki - [cloud-notifications.md](references/ops/cloud-notifications.md) — Cloud notifications: certificate expiry (15/10/5 days), API key expiry (30/20/10 days), credit consumption/expiry alerts, plan changes, failover events, recipient roles, `noreply@temporal.io` sender. - [cloud-saml-scim.md](references/ops/cloud-saml-scim.md) — SAML SSO (Entra ID, Okta): entity identifier (`urn:auth0:prod-tmprl:ACCOUNT_ID-saml`), callback URL (`login.tmprl.cloud`), IdP configuration steps, support ticket workflow. SCIM: supported vendors, prerequisites (SAML first), 10-minute sync window, group-to-role mapping. - [self-hosted-admin.md](references/ops/self-hosted-admin.md) — Self-hosted control plane via `temporal operator`: cluster health/describe, namespace CRUD, search-attribute create/list/remove, Nexus endpoint CRUD. +- [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) — Cloud-only: the 1,000-caller-Namespace-per-Nexus-Endpoint Access-Policy default; inspecting the current allowlist; adding, removing, replacing entries via `temporal cloud nexus endpoint allowed-namespace` and `tcld nexus endpoint allowed-namespace`; seeding at create via `--allow-namespace`; raising the ceiling via support ticket. - [workflow-health.md](references/ops/workflow-health.md) — Data-plane health queries: `temporal workflow list` with List Filters, `temporal workflow describe`/`show`/`count`, `temporal task-queue describe` for poller status. - [cli-conventions.md](references/ops/cli-conventions.md) — Cross-command `temporal` CLI conventions: connection/identity (`TEMPORAL_*` env vars ↔ `--address`/`--namespace`/`--api-key`, `--identity`), output/formatting (`--output`, `--time-format`, payload shorthand), the `--query` ⇒ batch-job bridge (with `temporal batch describe/list/terminate`), and schedule time-spec forms. Ends with an operation→command index that routes each data-plane operation to its owner file. Delegates exhaustive flags to `temporal --help`. - [ops/recipes.md](references/ops/recipes.md) — End-to-end ops playbooks: set up new namespace, check APS, switch capacity mode, find hung workflows, rotate API key, audit access, rotate mTLS certs, check self-hosted health, view billing / generate billing report, configure audit log sink, provision resources with Terraform, set up SAML SSO. diff --git a/references/ops/cloud-ops-api.md b/references/ops/cloud-ops-api.md index 9fa520e..325a978 100644 --- a/references/ops/cloud-ops-api.md +++ b/references/ops/cloud-ops-api.md @@ -66,7 +66,7 @@ import ( ) ``` -Go samples: [github.com/temporalio/cloud-samples-go](https://github.com/temporalio/cloud-samples-go) +Go samples: [github.com/temporalio/cloud-samples-go](https://github.com/temporalio/cloud-samples-go) Cloud Ops API client setup: [client/api/client.go](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go) --- diff --git a/references/ops/nexus-caller-limits.md b/references/ops/nexus-caller-limits.md new file mode 100644 index 0000000..b4de0ff --- /dev/null +++ b/references/ops/nexus-caller-limits.md @@ -0,0 +1,198 @@ +# Nexus Caller-Namespace Limits (Temporal Cloud) + +Operator reference for the default 1,000-caller-Namespace ceiling on each Nexus Endpoint's Access Policy in Temporal Cloud: what the limit is, how to inspect the current allowlist, how to add/remove/set entries via `temporal cloud nexus` and `tcld nexus`, and how to raise the ceiling. + +Scope: **Temporal Cloud only.** Self-hosted deployments do not have a Cloud-managed Access Policy — self-hosted authorization goes through a custom Authorizer plugin instead. + +--- + +## The limit + +**A single Nexus Endpoint can have a maximum of 1,000 caller Namespaces in its Access Policy by default.** Request further increases beyond the initial 1,000 by opening a support ticket. + +The Access Policy is the allowlist of caller Namespaces permitted to use the Endpoint at runtime. When a caller Workflow executes a Nexus Operation, Temporal Cloud verifies the caller's Namespace is in the Endpoint's allowlist before routing the request to the handler. + +**No callers are allowed by default, even if in the same Namespace as the Endpoint target.** The allowlist is empty at Endpoint create time unless `--allow-namespace` is supplied. + +### Adjacent Nexus limits (cross-reference only) + +- **100 Nexus Endpoints per Account by default.** Also raised via support ticket. This is a distinct limit — don't conflate the two 1,000/100 figures. +- Other Nexus limits (rate limits, per-Workflow in-flight Operation ceilings, callback ceilings, handler-request timeout, ScheduleToClose maximum) are indexed at [`docs/cloud/nexus/limits.mdx`](https://docs.temporal.io/cloud/nexus/limits). This file does not re-own them. + +--- + +## Inspect the current allowlist + +Read-only. Safe to run without confirmation. + +**Temporal CLI (`temporal cloud nexus`):** + +```bash +temporal cloud nexus endpoint allowed-namespace list --name +``` + +Required flag: `--name`. + +**tcld:** + +```bash +tcld nexus endpoint allowed-namespace list --name +``` + +Required flag: `--name` (alias `-n`). + +To see the Endpoint's full configuration (target Namespace, target Task Queue, description, allowlist): + +```bash +temporal cloud nexus endpoint get --name +``` + +Requires either `--name` or `--id` (exactly one). + +--- + +## Manage the allowlist + +The subcommand group is `allowed-namespace` (with a `d`). The `--allow-namespace` singular form (no `d`) is only a flag on `endpoint create` for seeding the initial list. + +### Add caller Namespaces + +`temporal cloud nexus`: + +```bash +temporal cloud nexus endpoint allowed-namespace add \ + --name \ + --namespace \ + --namespace +``` + +Required flags: `--name` and `--namespace`. `--namespace` accepts a string[] and can be specified multiple times. Namespaces already on the list are silently ignored. + +tcld: + +```bash +tcld nexus endpoint allowed-namespace add \ + --name \ + --namespace \ + --namespace +``` + +Aliases: `--name` → `-n`, `--namespace` → `-ns`. + +### Remove caller Namespaces + +`temporal cloud nexus`: + +```bash +temporal cloud nexus endpoint allowed-namespace remove \ + --name \ + --namespace +``` + +Namespaces not currently allowed are silently ignored. + +tcld: + +```bash +tcld nexus endpoint allowed-namespace remove \ + --name \ + --namespace +``` + +### Replace the full allowlist + +Use `set` when you want to declare the exact list rather than diff-apply. This is the byte-precise form and replaces the previous allowlist entirely. + +`temporal cloud nexus`: + +```bash +temporal cloud nexus endpoint allowed-namespace set \ + --name \ + --namespace \ + --namespace +``` + +**Set replaces the full list of allowed namespaces**, dropping any entry not supplied in this call. Treat `set` as a destructive operation: run `allowed-namespace list` first to capture the current state, diff against your intended list, and confirm with the user before running. + +tcld: + +```bash +tcld nexus endpoint allowed-namespace set \ + --name \ + --namespace \ + --namespace +``` + +### Seed the allowlist at Endpoint create + +`--allow-namespace` (singular, no `d`) is a repeatable flag on `endpoint create` that seeds the initial allowlist. It is not a subcommand. + +`temporal cloud nexus`: + +```bash +temporal cloud nexus endpoint create \ + --name \ + --target-namespace \ + --target-task-queue \ + --allow-namespace \ + --allow-namespace +``` + +`--target-namespace` and `--target-task-queue` are required at create time. `--allow-namespace` is optional and repeatable. + +tcld (subcommand is `(EXPERIMENTAL)` in the auto-generated reference): + +```bash +tcld nexus endpoint create \ + --name \ + --target-namespace \ + --target-task-queue \ + --allow-namespace \ + --allow-namespace +``` + +Aliases: `--name` → `-n`, `--target-namespace` → `-tns`, `--target-task-queue` → `-ttq`, `--allow-namespace` → `-ans`. + +--- + +## Raise the 1,000 ceiling + +There is no CLI flag, config key, or Terraform variable that raises the cap. **Increases require opening a support ticket.** + +When the user is approaching or at the limit: + +1. Confirm current allowlist size with `allowed-namespace list --name `. +2. Identify whether the growth is expected (real fan-in of caller Namespaces) or accidental (stale entries). +3. If growth is expected, direct the user to file a support request via the Temporal Cloud support portal (see the Cloud support page in `docs/cloud/support`). + +Do not propose sharding-by-Endpoint or other workaround architectures — the documentation does not prescribe one, and the supported path is the support ticket. + +--- + +## When to hand this off + +- **User wants to *write* a Nexus caller Workflow or Service definition:** hand off to `skill-temporal-developer`. This file is for the operator surface only. +- **Nexus Operation is stuck / failing at runtime, not an allowlist-configuration issue:** see [`workflow-stuck.md#pending-nexus-operations`](../triage/workflow-stuck.md#pending-nexus-operations). +- **Provisioning Endpoints (including the allowlist) via Terraform:** see [`cloud-terraform.md#nexus-endpoint-management`](cloud-terraform.md#nexus-endpoint-management). The Terraform resource field is `allowed_caller_namespaces`. +- **Nexus Endpoint CRUD on self-hosted:** see [`self-hosted-admin.md#nexus-endpoint-commands`](self-hosted-admin.md#nexus-endpoint-commands). Self-hosted has no equivalent 1,000-caller cap because the Access Policy is a Cloud-only construct. + +--- + +## Common mistakes + +- **Confusing the 1,000-caller-Namespaces-per-Endpoint limit with the 100-Endpoints-per-Account limit.** They sit four lines apart in the same source and are easy to swap. +- **Treating `set` like `add`.** `set` replaces the full allowlist; entries you don't pass are removed. Read the current list first. +- **Using `allow-namespace` (singular, no `d`) as a subcommand name.** The subcommand group is `allowed-namespace`; the singular form is only a `--allow-namespace` flag on `endpoint create`. +- **Assuming same-Namespace callers are permitted by default.** They are not — no callers are allowed until explicitly added, even from the Endpoint's own target Namespace. +- **Attributing the 1,000 limit to self-hosted deployments.** The Access Policy is a Cloud construct. + +--- + +## Resources + +- [Temporal Cloud limits — Nexus caller Namespace limits](https://docs.temporal.io/cloud/limits#nexus-endpoint-access-policy-limits) +- [Nexus limits index](https://docs.temporal.io/cloud/nexus/limits) +- [Nexus Security — Runtime access controls](https://docs.temporal.io/nexus/security#runtime-access-controls) +- [Nexus Registry — Configure runtime access controls](https://docs.temporal.io/nexus/registry#configure-runtime-access-controls) +- [`temporal cloud nexus` CLI reference](https://docs.temporal.io/cloud/temporal-cli/cloud/nexus) +- [`tcld nexus` CLI reference](https://docs.temporal.io/cloud/tcld/nexus) diff --git a/references/triage/connectivity.md b/references/triage/connectivity.md index ff191d7..eed291e 100644 --- a/references/triage/connectivity.md +++ b/references/triage/connectivity.md @@ -65,7 +65,7 @@ Interpreting results: ## Endpoint formats -Using the wrong endpoint family is one of the most common causes of "cannot connect" reports. +Using the wrong endpoint family is one of the most common causes of "cannot connect" reports. | Purpose | Endpoint pattern | Port | Source | |---|---|---|---| @@ -134,7 +134,7 @@ nc -zvw10 vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com 7233 ## Quick diagnostic scripts -Run from the failing environment (the pod, container, or host where the problem reproduces). These scripts chain the layer-1/2 checks with a final `temporal` call to confirm the whole stack end-to-end. +Run from the failing environment (the pod, container, or host where the problem reproduces). These scripts chain the layer-1/2 checks with a final `temporal` call to confirm the whole stack end-to-end. ### mTLS variant From 1c7208936614b50ec9ee5bb97a96bd13a00273fc Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Mon, 10 Aug 2026 10:02:39 -0700 Subject: [PATCH 2/4] docs(nexus-caller-limits): keep tcld examples only Drop the paired `temporal cloud nexus` code blocks from the new nexus-caller-limits reference, folding the flag and behavior notes into the surviving tcld blocks. Also revert the whitespace-only edits to cloud-ops-api.md and connectivity.md, which were unrelated to this topic and removed a load-bearing line break. Co-Authored-By: Claude Opus 5 (1M context) --- SKILL.md | 2 +- references/ops/cloud-ops-api.md | 2 +- references/ops/nexus-caller-limits.md | 74 +++------------------------ references/triage/connectivity.md | 4 +- 4 files changed, 11 insertions(+), 71 deletions(-) diff --git a/SKILL.md b/SKILL.md index 01d38eb..01cd4f5 100644 --- a/SKILL.md +++ b/SKILL.md @@ -269,7 +269,7 @@ If the layer above the fix is still failing, return to step 4 and continue walki - [cloud-notifications.md](references/ops/cloud-notifications.md) — Cloud notifications: certificate expiry (15/10/5 days), API key expiry (30/20/10 days), credit consumption/expiry alerts, plan changes, failover events, recipient roles, `noreply@temporal.io` sender. - [cloud-saml-scim.md](references/ops/cloud-saml-scim.md) — SAML SSO (Entra ID, Okta): entity identifier (`urn:auth0:prod-tmprl:ACCOUNT_ID-saml`), callback URL (`login.tmprl.cloud`), IdP configuration steps, support ticket workflow. SCIM: supported vendors, prerequisites (SAML first), 10-minute sync window, group-to-role mapping. - [self-hosted-admin.md](references/ops/self-hosted-admin.md) — Self-hosted control plane via `temporal operator`: cluster health/describe, namespace CRUD, search-attribute create/list/remove, Nexus endpoint CRUD. -- [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) — Cloud-only: the 1,000-caller-Namespace-per-Nexus-Endpoint Access-Policy default; inspecting the current allowlist; adding, removing, replacing entries via `temporal cloud nexus endpoint allowed-namespace` and `tcld nexus endpoint allowed-namespace`; seeding at create via `--allow-namespace`; raising the ceiling via support ticket. +- [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) — Cloud-only: the 1,000-caller-Namespace-per-Nexus-Endpoint Access-Policy default; inspecting the current allowlist; adding, removing, replacing entries via `tcld nexus endpoint allowed-namespace`; seeding at create via `--allow-namespace`; raising the ceiling via support ticket. - [workflow-health.md](references/ops/workflow-health.md) — Data-plane health queries: `temporal workflow list` with List Filters, `temporal workflow describe`/`show`/`count`, `temporal task-queue describe` for poller status. - [cli-conventions.md](references/ops/cli-conventions.md) — Cross-command `temporal` CLI conventions: connection/identity (`TEMPORAL_*` env vars ↔ `--address`/`--namespace`/`--api-key`, `--identity`), output/formatting (`--output`, `--time-format`, payload shorthand), the `--query` ⇒ batch-job bridge (with `temporal batch describe/list/terminate`), and schedule time-spec forms. Ends with an operation→command index that routes each data-plane operation to its owner file. Delegates exhaustive flags to `temporal --help`. - [ops/recipes.md](references/ops/recipes.md) — End-to-end ops playbooks: set up new namespace, check APS, switch capacity mode, find hung workflows, rotate API key, audit access, rotate mTLS certs, check self-hosted health, view billing / generate billing report, configure audit log sink, provision resources with Terraform, set up SAML SSO. diff --git a/references/ops/cloud-ops-api.md b/references/ops/cloud-ops-api.md index 325a978..9fa520e 100644 --- a/references/ops/cloud-ops-api.md +++ b/references/ops/cloud-ops-api.md @@ -66,7 +66,7 @@ import ( ) ``` -Go samples: [github.com/temporalio/cloud-samples-go](https://github.com/temporalio/cloud-samples-go) +Go samples: [github.com/temporalio/cloud-samples-go](https://github.com/temporalio/cloud-samples-go) Cloud Ops API client setup: [client/api/client.go](https://github.com/temporalio/cloud-samples-go/blob/main/client/api/client.go) --- diff --git a/references/ops/nexus-caller-limits.md b/references/ops/nexus-caller-limits.md index b4de0ff..e071e5c 100644 --- a/references/ops/nexus-caller-limits.md +++ b/references/ops/nexus-caller-limits.md @@ -1,6 +1,6 @@ # Nexus Caller-Namespace Limits (Temporal Cloud) -Operator reference for the default 1,000-caller-Namespace ceiling on each Nexus Endpoint's Access Policy in Temporal Cloud: what the limit is, how to inspect the current allowlist, how to add/remove/set entries via `temporal cloud nexus` and `tcld nexus`, and how to raise the ceiling. +Operator reference for the default 1,000-caller-Namespace ceiling on each Nexus Endpoint's Access Policy in Temporal Cloud: what the limit is, how to inspect the current allowlist, how to add/remove/set entries via `tcld nexus`, and how to raise the ceiling. Scope: **Temporal Cloud only.** Self-hosted deployments do not have a Cloud-managed Access Policy — self-hosted authorization goes through a custom Authorizer plugin instead. @@ -25,16 +25,6 @@ The Access Policy is the allowlist of caller Namespaces permitted to use the End Read-only. Safe to run without confirmation. -**Temporal CLI (`temporal cloud nexus`):** - -```bash -temporal cloud nexus endpoint allowed-namespace list --name -``` - -Required flag: `--name`. - -**tcld:** - ```bash tcld nexus endpoint allowed-namespace list --name ``` @@ -44,11 +34,9 @@ Required flag: `--name` (alias `-n`). To see the Endpoint's full configuration (target Namespace, target Task Queue, description, allowlist): ```bash -temporal cloud nexus endpoint get --name +tcld nexus endpoint get --name ``` -Requires either `--name` or `--id` (exactly one). - --- ## Manage the allowlist @@ -57,19 +45,6 @@ The subcommand group is `allowed-namespace` (with a `d`). The `--allow-namespace ### Add caller Namespaces -`temporal cloud nexus`: - -```bash -temporal cloud nexus endpoint allowed-namespace add \ - --name \ - --namespace \ - --namespace -``` - -Required flags: `--name` and `--namespace`. `--namespace` accepts a string[] and can be specified multiple times. Namespaces already on the list are silently ignored. - -tcld: - ```bash tcld nexus endpoint allowed-namespace add \ --name \ @@ -77,36 +52,24 @@ tcld nexus endpoint allowed-namespace add \ --namespace ``` -Aliases: `--name` → `-n`, `--namespace` → `-ns`. +Required flags: `--name` and `--namespace`. `--namespace` is repeatable. Namespaces already on the list are silently ignored. Aliases: `--name` → `-n`, `--namespace` → `-ns`. ### Remove caller Namespaces -`temporal cloud nexus`: - ```bash -temporal cloud nexus endpoint allowed-namespace remove \ +tcld nexus endpoint allowed-namespace remove \ --name \ --namespace ``` Namespaces not currently allowed are silently ignored. -tcld: - -```bash -tcld nexus endpoint allowed-namespace remove \ - --name \ - --namespace -``` - ### Replace the full allowlist Use `set` when you want to declare the exact list rather than diff-apply. This is the byte-precise form and replaces the previous allowlist entirely. -`temporal cloud nexus`: - ```bash -temporal cloud nexus endpoint allowed-namespace set \ +tcld nexus endpoint allowed-namespace set \ --name \ --namespace \ --namespace @@ -114,33 +77,11 @@ temporal cloud nexus endpoint allowed-namespace set \ **Set replaces the full list of allowed namespaces**, dropping any entry not supplied in this call. Treat `set` as a destructive operation: run `allowed-namespace list` first to capture the current state, diff against your intended list, and confirm with the user before running. -tcld: - -```bash -tcld nexus endpoint allowed-namespace set \ - --name \ - --namespace \ - --namespace -``` - ### Seed the allowlist at Endpoint create `--allow-namespace` (singular, no `d`) is a repeatable flag on `endpoint create` that seeds the initial allowlist. It is not a subcommand. -`temporal cloud nexus`: - -```bash -temporal cloud nexus endpoint create \ - --name \ - --target-namespace \ - --target-task-queue \ - --allow-namespace \ - --allow-namespace -``` - -`--target-namespace` and `--target-task-queue` are required at create time. `--allow-namespace` is optional and repeatable. - -tcld (subcommand is `(EXPERIMENTAL)` in the auto-generated reference): +`tcld nexus endpoint create` is marked experimental. ```bash tcld nexus endpoint create \ @@ -151,7 +92,7 @@ tcld nexus endpoint create \ --allow-namespace ``` -Aliases: `--name` → `-n`, `--target-namespace` → `-tns`, `--target-task-queue` → `-ttq`, `--allow-namespace` → `-ans`. +`--target-namespace` and `--target-task-queue` are required at create time. `--allow-namespace` is optional and repeatable. Aliases: `--name` → `-n`, `--target-namespace` → `-tns`, `--target-task-queue` → `-ttq`, `--allow-namespace` → `-ans`. --- @@ -194,5 +135,4 @@ Do not propose sharding-by-Endpoint or other workaround architectures — the do - [Nexus limits index](https://docs.temporal.io/cloud/nexus/limits) - [Nexus Security — Runtime access controls](https://docs.temporal.io/nexus/security#runtime-access-controls) - [Nexus Registry — Configure runtime access controls](https://docs.temporal.io/nexus/registry#configure-runtime-access-controls) -- [`temporal cloud nexus` CLI reference](https://docs.temporal.io/cloud/temporal-cli/cloud/nexus) - [`tcld nexus` CLI reference](https://docs.temporal.io/cloud/tcld/nexus) diff --git a/references/triage/connectivity.md b/references/triage/connectivity.md index eed291e..ff191d7 100644 --- a/references/triage/connectivity.md +++ b/references/triage/connectivity.md @@ -65,7 +65,7 @@ Interpreting results: ## Endpoint formats -Using the wrong endpoint family is one of the most common causes of "cannot connect" reports. +Using the wrong endpoint family is one of the most common causes of "cannot connect" reports. | Purpose | Endpoint pattern | Port | Source | |---|---|---|---| @@ -134,7 +134,7 @@ nc -zvw10 vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com 7233 ## Quick diagnostic scripts -Run from the failing environment (the pod, container, or host where the problem reproduces). These scripts chain the layer-1/2 checks with a final `temporal` call to confirm the whole stack end-to-end. +Run from the failing environment (the pod, container, or host where the problem reproduces). These scripts chain the layer-1/2 checks with a final `temporal` call to confirm the whole stack end-to-end. ### mTLS variant From 347c4b245902dc420da5b8caeda8d1bd84667868 Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Tue, 11 Aug 2026 17:00:58 -0700 Subject: [PATCH 3/4] docs(cloud-namespace-admin): fold Nexus caller allowlist into the tcld reference Replace the standalone nexus-caller-limits.md with a section in cloud-namespace-admin.md, which already owns the Cloud tcld surface, and add both Nexus ceilings to that file's Limits list. Matches the house style used by accepted-client-ca and certificate-filters: subcommand table, shared flags, then the blast radius of the replace-everything verb. Also notes that `set` fights Terraform's allowed_caller_namespaces, and points Endpoint CRUD at the existing self-hosted-admin mapping. Co-Authored-By: Claude Opus 5 (1M context) --- SKILL.md | 5 +- references/ops/cloud-namespace-admin.md | 41 +++++++ references/ops/nexus-caller-limits.md | 138 ------------------------ 3 files changed, 43 insertions(+), 141 deletions(-) delete mode 100644 references/ops/nexus-caller-limits.md diff --git a/SKILL.md b/SKILL.md index 19e3022..06e524d 100644 --- a/SKILL.md +++ b/SKILL.md @@ -135,7 +135,7 @@ Find the row that matches the user's intent. The reference file contains the com | Set up PrivateLink / PSC, manage connectivity rules | Cloud connectivity | [cloud-connectivity.md](references/ops/cloud-connectivity.md) | | Self-hosted cluster health, describe, namespace CRUD | Self-hosted admin | [self-hosted-admin.md](references/ops/self-hosted-admin.md) | | Self-hosted search attributes, Nexus endpoints | Self-hosted admin | [self-hosted-admin.md](references/ops/self-hosted-admin.md) | -| Check or manage a Cloud Nexus Endpoint's caller-Namespace allowlist; understand or raise the 1,000-caller default | Nexus caller limits | [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) | +| Check or manage a Cloud Nexus Endpoint's caller-Namespace allowlist; the 1,000-caller default | Cloud namespace admin | [cloud-namespace-admin.md#tcld-nexus-endpoint-allowed-namespace](references/ops/cloud-namespace-admin.md#tcld-nexus-endpoint-allowed-namespace) | | Find stuck/hung/unhealthy workflows via list queries | Workflow health | [workflow-health.md](references/ops/workflow-health.md) | | Task queue poller status, workflow counts | Workflow health | [workflow-health.md](references/ops/workflow-health.md) | | Cancel, terminate, or reset workflows | Workflow recovery | [workflow-stuck.md#recovery-commands](references/triage/workflow-stuck.md#recovery-commands) | @@ -257,7 +257,7 @@ If the layer above the fix is still failing, return to step 4 and continue walki ### Operations -- [cloud-namespace-admin.md](references/ops/cloud-namespace-admin.md) — Cloud namespace lifecycle via `tcld`: create, get, list, delete, failover, add-region, retention, tags, codec-server, HA config, connectivity rules, search attributes, accepted-client-ca, certificate filters, export. +- [cloud-namespace-admin.md](references/ops/cloud-namespace-admin.md) — Cloud namespace lifecycle via `tcld`: create, get, list, delete, failover, add-region, retention, tags, codec-server, HA config, connectivity rules, search attributes, accepted-client-ca, certificate filters, export, and the `tcld nexus endpoint allowed-namespace` caller allowlist (1,000-caller Access Policy ceiling). - [cloud-capacity.md](references/ops/cloud-capacity.md) — Capacity modes (On-Demand / Provisioned), APS/RPS/OPS definitions, TRUs, `tcld namespace capacity update`, default limits, throttling, APS management best practices. - [cloud-iam.md](references/ops/cloud-iam.md) — API key lifecycle (`tcld apikey`), users (`tcld user`), user groups (`tcld user-group`), service accounts, account operations (`tcld account`), roles, namespace permissions. - [cloud-certs.md](references/ops/cloud-certs.md) — mTLS cert management: generating certs with `tcld generate-certificates`, uploading CAs, certificate filters, cert rotation, switching mTLS ↔ API keys. @@ -270,7 +270,6 @@ If the layer above the fix is still failing, return to step 4 and continue walki - [cloud-notifications.md](references/ops/cloud-notifications.md) — Cloud notifications: certificate expiry (15/10/5 days), API key expiry (30/20/10 days), credit consumption/expiry alerts, plan changes, failover events, recipient roles, `noreply@temporal.io` sender. - [cloud-saml-scim.md](references/ops/cloud-saml-scim.md) — SAML SSO (Entra ID, Okta): entity identifier (`urn:auth0:prod-tmprl:ACCOUNT_ID-saml`), callback URL (`login.tmprl.cloud`), IdP configuration steps, support ticket workflow. SCIM: supported vendors, prerequisites (SAML first), 10-minute sync window, group-to-role mapping. - [self-hosted-admin.md](references/ops/self-hosted-admin.md) — Self-hosted control plane via `temporal operator`: cluster health/describe, namespace CRUD, search-attribute create/list/remove, Nexus endpoint CRUD. -- [nexus-caller-limits.md](references/ops/nexus-caller-limits.md) — Cloud-only: the 1,000-caller-Namespace-per-Nexus-Endpoint Access-Policy default; inspecting the current allowlist; adding, removing, replacing entries via `tcld nexus endpoint allowed-namespace`; seeding at create via `--allow-namespace`; raising the ceiling via support ticket. - [workflow-health.md](references/ops/workflow-health.md) — Data-plane health queries: `temporal workflow list` with List Filters, `temporal workflow describe`/`show`/`count`, `temporal task-queue describe` for poller status. - [cli-conventions.md](references/ops/cli-conventions.md) — Cross-command `temporal` CLI conventions: connection/identity (`TEMPORAL_*` env vars ↔ `--address`/`--namespace`/`--api-key`, `--identity`), output/formatting (`--output`, `--time-format`, payload shorthand), the `--query` ⇒ batch-job bridge (with `temporal batch describe/list/terminate`), and schedule time-spec forms. Ends with an operation→command index that routes each data-plane operation to its owner file. Delegates exhaustive flags to `temporal --help`. - [ops/recipes.md](references/ops/recipes.md) — End-to-end ops playbooks: set up new namespace, check APS, switch capacity mode, find hung workflows, rotate API key, audit access, rotate mTLS certs, check self-hosted health, view billing / generate billing report, configure audit log sink, provision resources with Terraform, set up SAML SSO. diff --git a/references/ops/cloud-namespace-admin.md b/references/ops/cloud-namespace-admin.md index a0e10e1..fa953de 100644 --- a/references/ops/cloud-namespace-admin.md +++ b/references/ops/cloud-namespace-admin.md @@ -29,6 +29,8 @@ If `--namespace` is omitted, the environment variable `$TEMPORAL_CLOUD_NAMESPACE - Max tags per namespace: 10 - Tag key/value length: 1-63 characters - Soft limit of 1000 unique tag keys per account +- Max caller Namespaces per Nexus Endpoint Access Policy: 1,000 (support ticket to raise) +- Max Nexus Endpoints per account: 100 (support ticket to raise) --- @@ -559,6 +561,45 @@ state which one you mean when you propose it. --- +## tcld nexus endpoint allowed-namespace + +Manages a Nexus Endpoint's Access Policy — the allowlist of caller Namespaces +permitted to use the Endpoint at runtime. Cloud-only: self-hosted authorization +goes through a custom Authorizer plugin instead. For Endpoint CRUD itself, see +[self-hosted-admin.md § Nexus Endpoint Commands](self-hosted-admin.md#nexus-endpoint-commands), +which maps each `temporal operator nexus` verb to its `tcld nexus` equivalent. + +| Subcommand | Purpose | +|---|---| +| `list` | Show the current allowlist | +| `add` | Add caller Namespaces; entries already present are ignored | +| `remove` | Remove caller Namespaces; entries not present are ignored | +| `set` | Replace the entire allowlist | + +All subcommands take `--name` / `-n` (the Endpoint) and, except `list`, +`--namespace` / `-ns`, which is repeatable: + +```bash +tcld nexus endpoint allowed-namespace add \ + --name \ + --namespace \ + --namespace +``` + +**No callers are allowed by default**, not even from the Endpoint's own target +Namespace. The allowlist is empty at create time unless seeded with +`--allow-namespace` (singular, a repeatable flag on `tcld nexus endpoint create`, +not a subcommand). + +`set` replaces the full list, so any entry you don't pass is dropped — revoking +those callers at their next Nexus Operation. Run `list` first, diff against the +list you intend, and prefer `add` when the goal is to grant. Terraform manages the +same field as `allowed_caller_namespaces`, so a `set` against a +Terraform-provisioned Endpoint will be reverted on the next apply — see +[cloud-terraform.md](cloud-terraform.md). + +--- + ## Endpoint and authentication summary | Auth method | Endpoint type | Format | diff --git a/references/ops/nexus-caller-limits.md b/references/ops/nexus-caller-limits.md deleted file mode 100644 index e071e5c..0000000 --- a/references/ops/nexus-caller-limits.md +++ /dev/null @@ -1,138 +0,0 @@ -# Nexus Caller-Namespace Limits (Temporal Cloud) - -Operator reference for the default 1,000-caller-Namespace ceiling on each Nexus Endpoint's Access Policy in Temporal Cloud: what the limit is, how to inspect the current allowlist, how to add/remove/set entries via `tcld nexus`, and how to raise the ceiling. - -Scope: **Temporal Cloud only.** Self-hosted deployments do not have a Cloud-managed Access Policy — self-hosted authorization goes through a custom Authorizer plugin instead. - ---- - -## The limit - -**A single Nexus Endpoint can have a maximum of 1,000 caller Namespaces in its Access Policy by default.** Request further increases beyond the initial 1,000 by opening a support ticket. - -The Access Policy is the allowlist of caller Namespaces permitted to use the Endpoint at runtime. When a caller Workflow executes a Nexus Operation, Temporal Cloud verifies the caller's Namespace is in the Endpoint's allowlist before routing the request to the handler. - -**No callers are allowed by default, even if in the same Namespace as the Endpoint target.** The allowlist is empty at Endpoint create time unless `--allow-namespace` is supplied. - -### Adjacent Nexus limits (cross-reference only) - -- **100 Nexus Endpoints per Account by default.** Also raised via support ticket. This is a distinct limit — don't conflate the two 1,000/100 figures. -- Other Nexus limits (rate limits, per-Workflow in-flight Operation ceilings, callback ceilings, handler-request timeout, ScheduleToClose maximum) are indexed at [`docs/cloud/nexus/limits.mdx`](https://docs.temporal.io/cloud/nexus/limits). This file does not re-own them. - ---- - -## Inspect the current allowlist - -Read-only. Safe to run without confirmation. - -```bash -tcld nexus endpoint allowed-namespace list --name -``` - -Required flag: `--name` (alias `-n`). - -To see the Endpoint's full configuration (target Namespace, target Task Queue, description, allowlist): - -```bash -tcld nexus endpoint get --name -``` - ---- - -## Manage the allowlist - -The subcommand group is `allowed-namespace` (with a `d`). The `--allow-namespace` singular form (no `d`) is only a flag on `endpoint create` for seeding the initial list. - -### Add caller Namespaces - -```bash -tcld nexus endpoint allowed-namespace add \ - --name \ - --namespace \ - --namespace -``` - -Required flags: `--name` and `--namespace`. `--namespace` is repeatable. Namespaces already on the list are silently ignored. Aliases: `--name` → `-n`, `--namespace` → `-ns`. - -### Remove caller Namespaces - -```bash -tcld nexus endpoint allowed-namespace remove \ - --name \ - --namespace -``` - -Namespaces not currently allowed are silently ignored. - -### Replace the full allowlist - -Use `set` when you want to declare the exact list rather than diff-apply. This is the byte-precise form and replaces the previous allowlist entirely. - -```bash -tcld nexus endpoint allowed-namespace set \ - --name \ - --namespace \ - --namespace -``` - -**Set replaces the full list of allowed namespaces**, dropping any entry not supplied in this call. Treat `set` as a destructive operation: run `allowed-namespace list` first to capture the current state, diff against your intended list, and confirm with the user before running. - -### Seed the allowlist at Endpoint create - -`--allow-namespace` (singular, no `d`) is a repeatable flag on `endpoint create` that seeds the initial allowlist. It is not a subcommand. - -`tcld nexus endpoint create` is marked experimental. - -```bash -tcld nexus endpoint create \ - --name \ - --target-namespace \ - --target-task-queue \ - --allow-namespace \ - --allow-namespace -``` - -`--target-namespace` and `--target-task-queue` are required at create time. `--allow-namespace` is optional and repeatable. Aliases: `--name` → `-n`, `--target-namespace` → `-tns`, `--target-task-queue` → `-ttq`, `--allow-namespace` → `-ans`. - ---- - -## Raise the 1,000 ceiling - -There is no CLI flag, config key, or Terraform variable that raises the cap. **Increases require opening a support ticket.** - -When the user is approaching or at the limit: - -1. Confirm current allowlist size with `allowed-namespace list --name `. -2. Identify whether the growth is expected (real fan-in of caller Namespaces) or accidental (stale entries). -3. If growth is expected, direct the user to file a support request via the Temporal Cloud support portal (see the Cloud support page in `docs/cloud/support`). - -Do not propose sharding-by-Endpoint or other workaround architectures — the documentation does not prescribe one, and the supported path is the support ticket. - ---- - -## When to hand this off - -- **User wants to *write* a Nexus caller Workflow or Service definition:** hand off to `skill-temporal-developer`. This file is for the operator surface only. -- **Nexus Operation is stuck / failing at runtime, not an allowlist-configuration issue:** see [`workflow-stuck.md#pending-nexus-operations`](../triage/workflow-stuck.md#pending-nexus-operations). -- **Provisioning Endpoints (including the allowlist) via Terraform:** see [`cloud-terraform.md#nexus-endpoint-management`](cloud-terraform.md#nexus-endpoint-management). The Terraform resource field is `allowed_caller_namespaces`. -- **Nexus Endpoint CRUD on self-hosted:** see [`self-hosted-admin.md#nexus-endpoint-commands`](self-hosted-admin.md#nexus-endpoint-commands). Self-hosted has no equivalent 1,000-caller cap because the Access Policy is a Cloud-only construct. - ---- - -## Common mistakes - -- **Confusing the 1,000-caller-Namespaces-per-Endpoint limit with the 100-Endpoints-per-Account limit.** They sit four lines apart in the same source and are easy to swap. -- **Treating `set` like `add`.** `set` replaces the full allowlist; entries you don't pass are removed. Read the current list first. -- **Using `allow-namespace` (singular, no `d`) as a subcommand name.** The subcommand group is `allowed-namespace`; the singular form is only a `--allow-namespace` flag on `endpoint create`. -- **Assuming same-Namespace callers are permitted by default.** They are not — no callers are allowed until explicitly added, even from the Endpoint's own target Namespace. -- **Attributing the 1,000 limit to self-hosted deployments.** The Access Policy is a Cloud construct. - ---- - -## Resources - -- [Temporal Cloud limits — Nexus caller Namespace limits](https://docs.temporal.io/cloud/limits#nexus-endpoint-access-policy-limits) -- [Nexus limits index](https://docs.temporal.io/cloud/nexus/limits) -- [Nexus Security — Runtime access controls](https://docs.temporal.io/nexus/security#runtime-access-controls) -- [Nexus Registry — Configure runtime access controls](https://docs.temporal.io/nexus/registry#configure-runtime-access-controls) -- [`tcld nexus` CLI reference](https://docs.temporal.io/cloud/tcld/nexus) From 17696674c822162ebcc9e7bd2d9dc73c0ebed3ca Mon Sep 17 00:00:00 2001 From: starfleeth <128422269+starfleeth@users.noreply.github.com> Date: Tue, 11 Aug 2026 17:20:23 -0700 Subject: [PATCH 4/4] docs(cloud-namespace-admin): require explicit approval for allowed-namespace set Dropping an entry revokes a live caller, which puts `set` in the destructive tier. The fold had weakened the draft's confirm-with-the-user step into run-list-first advice. Co-Authored-By: Claude Opus 5 (1M context) --- references/ops/cloud-namespace-admin.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/references/ops/cloud-namespace-admin.md b/references/ops/cloud-namespace-admin.md index fa953de..ca546f2 100644 --- a/references/ops/cloud-namespace-admin.md +++ b/references/ops/cloud-namespace-admin.md @@ -592,8 +592,10 @@ Namespace. The allowlist is empty at create time unless seeded with not a subcommand). `set` replaces the full list, so any entry you don't pass is dropped — revoking -those callers at their next Nexus Operation. Run `list` first, diff against the -list you intend, and prefer `add` when the goal is to grant. Terraform manages the +those callers at their next Nexus Operation. Never run it on your own initiative. +Run `list` first, name the exact entries it would drop, and ask the user directly; +run it only once they have approved, and only against that Endpoint. Prefer `add` +when the goal is to grant. Terraform manages the same field as `allowed_caller_namespaces`, so a `set` against a Terraform-provisioned Endpoint will be reverted on the next apply — see [cloud-terraform.md](cloud-terraform.md).