From 438c0d09df29ec553bd1506c8a389bdc36dfbdd1 Mon Sep 17 00:00:00 2001 From: Brian MacDonald Date: Thu, 12 Dec 2024 15:20:47 -0500 Subject: [PATCH 1/2] breaking apart namespaces page --- .../namespaces/global-namespaces.mdx | 38 +++++++++++++++++++ .../{ => namespaces}/namespaces.mdx | 30 ++------------- sidebars.js | 13 ++++++- 3 files changed, 54 insertions(+), 27 deletions(-) create mode 100644 docs/encyclopedia/namespaces/global-namespaces.mdx rename docs/encyclopedia/{ => namespaces}/namespaces.mdx (81%) diff --git a/docs/encyclopedia/namespaces/global-namespaces.mdx b/docs/encyclopedia/namespaces/global-namespaces.mdx new file mode 100644 index 0000000000..d4a76cda9c --- /dev/null +++ b/docs/encyclopedia/namespaces/global-namespaces.mdx @@ -0,0 +1,38 @@ +--- +id: global-namespaces +title: What is a Global Namespace? +sidebar_label: Global Namespaces +description: This guide covers everything about Global Namespaces within the Temporal Platform. +slug: /global-namespaces +toc_max_heading_level: 4 +keywords: + - namespaces +tags: + - Concepts + - Namespaces +--- + +This page provides an overview of Global Namespace. + +## What is a Global Namespace? {#global-namespace} + +A Global Namespace is a [Namespace](/namespaces) that exists across Clusters when [Multi-Cluster Replication](/clusters#multi-cluster-replication) is set up. + +- [How to register a Global Namespace](/cli/operator#create) +- [How to change the active Cluster for a Global Namespace](/cli/operator#update) + +The Global Namespace feature enables Workflow Executions to progress through another Cluster in the event of a failover. + +A Global Namespace may be replicated to any number of Clusters, but is active in only one Cluster at any given time. + +For a failover to be successful, Worker Processes must be polling for Tasks for the Global Namespace on all Clusters. + +A Global Namespace has a failover version. +Because a failover can be triggered from any Cluster, the failover version prevents certain conflicts from occurring if a failover is mistakenly triggered simultaneously on two Clusters. + +Only the active Cluster dispatches [Tasks](/workers#task); however, certain conflicts are possible. +Unlike regular Namespaces, which provide at-most-once semantics for an Activity Execution, Global Namespaces can support only at-least-once semantics (see [Conflict resolution](/clusters#conflict-resolution)). +Worker Processes on the standby Clusters are idle until a failover occurs and their Cluster becomes active. + +Temporal Application API calls made to a non-active Cluster are rejected with a **NamespaceNotActiveError** which contains the name of the current active Cluster. +It is the responsibility of the Temporal Application to call the Cluster that is currently active. diff --git a/docs/encyclopedia/namespaces.mdx b/docs/encyclopedia/namespaces/namespaces.mdx similarity index 81% rename from docs/encyclopedia/namespaces.mdx rename to docs/encyclopedia/namespaces/namespaces.mdx index 03468b2b29..0343b086c9 100644 --- a/docs/encyclopedia/namespaces.mdx +++ b/docs/encyclopedia/namespaces/namespaces.mdx @@ -18,7 +18,7 @@ A Namespace is a unit of isolation within the Temporal Platform. A single Namespace is still multi-tenant. -### Usage +## Usage Namespaces are created on the Temporal Service, and provide a range of controls to achieve isolation on Workflow Executions. @@ -34,7 +34,7 @@ Namespaces are created on the Temporal Service, and provide a range of controls Workflow Executions may have the same Workflow Id if they are in different Namespaces. - **Namespace Configuration:** Various configuration options like the [Retention Period](/clusters#retention-period) and the [Archival](/clusters#archival) destination are configured per Namespace through a special CRUD API or through the [Temporal CLI](/cli). -### Registration +## Registration Registering a Namespace creates the Namespace on the Temporal Service. When you register your Namespace, you must also set the [Retention Period](/clusters#retention-period) for the Namespace. @@ -64,7 +64,7 @@ On self-hosted Temporal Service, you can register your Namespaces in the followi Note that registering a Namespace takes up to 15 seconds to complete. Ensure that you are waiting for this process to complete before making calls to the Namespace. -### Manage Namespaces +## Manage Namespaces Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces. @@ -99,7 +99,7 @@ On self-hosted Temporal Service, you can manage your registered Namespaces using - With the Temporal CLI: [`temporal operator namespace delete`](/cli/operator#delete). - Use the DeleteNamespace API to delete a registered Namespaces. All the running Workflow Executions on a deleted Namespace are also deleted. -### Setting +## Setting Set Namespaces in your SDK Client to isolate your Workflow Executions to the Namespace. If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the "default" Namespace. This means, you must have a default Namespace called "default" registered with your Temporal Service. See [Registration](#registration) for details. @@ -109,25 +109,3 @@ If you do not set a Namespace, all Workflow Executions started using the Client - [How to list Namespaces in a Temporal Service using the Temporal CLI](/cli/operator#list) - [How to view (describe) Namespace metadata and details using the Temporal CLI](/cli/operator#describe) -## What is a Global Namespace? {#global-namespace} - -A Global Namespace is a [Namespace](/namespaces) that exists across Clusters when [Multi-Cluster Replication](/clusters#multi-cluster-replication) is set up. - -- [How to register a Global Namespace](/cli/operator#create) -- [How to change the active Cluster for a Global Namespace](/cli/operator#update) - -The Global Namespace feature enables Workflow Executions to progress through another Cluster in the event of a failover. - -A Global Namespace may be replicated to any number of Clusters, but is active in only one Cluster at any given time. - -For a failover to be successful, Worker Processes must be polling for Tasks for the Global Namespace on all Clusters. - -A Global Namespace has a failover version. -Because a failover can be triggered from any Cluster, the failover version prevents certain conflicts from occurring if a failover is mistakenly triggered simultaneously on two Clusters. - -Only the active Cluster dispatches [Tasks](/workers#task); however, certain conflicts are possible. -Unlike regular Namespaces, which provide at-most-once semantics for an Activity Execution, Global Namespaces can support only at-least-once semantics (see [Conflict resolution](/clusters#conflict-resolution)). -Worker Processes on the standby Clusters are idle until a failover occurs and their Cluster becomes active. - -Temporal Application API calls made to a non-active Cluster are rejected with a **NamespaceNotActiveError** which contains the name of the current active Cluster. -It is the responsibility of the Temporal Application to call the Cluster that is currently active. diff --git a/sidebars.js b/sidebars.js index 34e4a3b650..bebdecdd19 100644 --- a/sidebars.js +++ b/sidebars.js @@ -520,7 +520,18 @@ module.exports = { "encyclopedia/child-workflows", "encyclopedia/visibility", "encyclopedia/clusters", - "encyclopedia/namespaces", + { + type: "category", + label: "Namespaces", + collapsed: true, + link: { + type: "doc", + id: "encyclopedia/namespaces/namespaces", + }, + items: [ + "encyclopedia/namespaces/global-namespaces", + ], + }, { type: "category", label: "Temporal Nexus", From 7d60f0f08540ec3b1f48d0b1cc1437d722ec45af Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Thu, 2 Jan 2025 14:37:37 -0800 Subject: [PATCH 2/2] updating anchors to global namespace pg --- docs/encyclopedia/activities.mdx | 2 +- docs/encyclopedia/clusters.mdx | 2 +- docs/encyclopedia/namespaces/global-namespaces.mdx | 4 ++-- docs/encyclopedia/namespaces/namespaces.mdx | 2 +- .../development-production-features/high-availability.mdx | 2 +- docs/glossary.md | 2 +- docs/production-deployment/self-hosted-guide/archival.mdx | 2 +- .../self-hosted-guide/multi-cluster-replication.mdx | 2 +- docs/tctl-v1/namespace.mdx | 4 ++-- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/encyclopedia/activities.mdx b/docs/encyclopedia/activities.mdx index e2f7007472..da7ba7d5d0 100644 --- a/docs/encyclopedia/activities.mdx +++ b/docs/encyclopedia/activities.mdx @@ -70,7 +70,7 @@ In the context of Temporal, Activities should be designed to be safely executed :::info -By design, completed Activities will not re-execute as part of a [Workflow Replay](/workflows#replays). However, Activities won’t record to the [Event History](/encyclopedia/retry-policies#event-history) until they return or produce an error. If an Activity fails to report to the server at all, it will be retried. Designing for idempotence, especially if you have a [Global Namespace](/namespaces#global-namespace), will improve reusability and reliability. +By design, completed Activities will not re-execute as part of a [Workflow Replay](/workflows#replays). However, Activities won’t record to the [Event History](/encyclopedia/retry-policies#event-history) until they return or produce an error. If an Activity fails to report to the server at all, it will be retried. Designing for idempotence, especially if you have a [Global Namespace](/global-namespace), will improve reusability and reliability. ::: diff --git a/docs/encyclopedia/clusters.mdx b/docs/encyclopedia/clusters.mdx index 2611bbfc76..a724a1a645 100644 --- a/docs/encyclopedia/clusters.mdx +++ b/docs/encyclopedia/clusters.mdx @@ -474,7 +474,7 @@ When necessary, for higher availability, Cluster operators can failover to any o Temporal's Multi-Cluster Replication feature is considered **experimental** and not subject to normal [versioning and support policy](/clusters). Temporal automatically forwards Start, Signal, and Query requests to the active Cluster. -This feature must be enabled through a Dynamic Config flag per [Global Namespace](/namespaces#global-namespace). +This feature must be enabled through a Dynamic Config flag per [Global Namespace](/global-namespace). When the feature is enabled, Tasks are sent to the Parent Task Queue partition that matches that Namespace, if it exists. diff --git a/docs/encyclopedia/namespaces/global-namespaces.mdx b/docs/encyclopedia/namespaces/global-namespaces.mdx index d4a76cda9c..4de5ec24c9 100644 --- a/docs/encyclopedia/namespaces/global-namespaces.mdx +++ b/docs/encyclopedia/namespaces/global-namespaces.mdx @@ -1,9 +1,9 @@ --- id: global-namespaces title: What is a Global Namespace? -sidebar_label: Global Namespaces +sidebar_label: Global Namespace description: This guide covers everything about Global Namespaces within the Temporal Platform. -slug: /global-namespaces +slug: /global-namespace toc_max_heading_level: 4 keywords: - namespaces diff --git a/docs/encyclopedia/namespaces/namespaces.mdx b/docs/encyclopedia/namespaces/namespaces.mdx index 0343b086c9..c686969c62 100644 --- a/docs/encyclopedia/namespaces/namespaces.mdx +++ b/docs/encyclopedia/namespaces/namespaces.mdx @@ -1,7 +1,7 @@ --- id: namespaces title: What is a Temporal Namespace? -sidebar_label: Namespaces +sidebar_label: Namespace description: This guide covers everything about Namespaces within the Temporal Platform, highlighting their role in Workflow isolation, setting up, registering, and managing Namespaces, and the concept and benefits of Global Namespaces. slug: /namespaces toc_max_heading_level: 4 diff --git a/docs/evaluate/development-production-features/high-availability.mdx b/docs/evaluate/development-production-features/high-availability.mdx index 4fedf85e6b..6c7f3763a4 100644 --- a/docs/evaluate/development-production-features/high-availability.mdx +++ b/docs/evaluate/development-production-features/high-availability.mdx @@ -27,7 +27,7 @@ Temporal offers high availability as a feature for both Temporal Cloud and self- - + diff --git a/docs/glossary.md b/docs/glossary.md index 9a7c5e75ba..1ac54fd075 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -234,7 +234,7 @@ Learn more about the General Availability release stage -#### [Global Namespace](/namespaces#global-namespace) +#### [Global Namespace](/global-namespace) A Global Namespace is a Namespace that duplicates data from an active [Temporal Service](#temporal-cluster) to a standby Service using the replication to keep both Namespaces in sync. Global Namespaces are designed to respond to service issues like network congestion. diff --git a/docs/production-deployment/self-hosted-guide/archival.mdx b/docs/production-deployment/self-hosted-guide/archival.mdx index 74cdb915fb..cbe9926231 100644 --- a/docs/production-deployment/self-hosted-guide/archival.mdx +++ b/docs/production-deployment/self-hosted-guide/archival.mdx @@ -125,7 +125,7 @@ The Archival URI cannot be changed after the Namespace is created. Each Namespace supports only a single Archival URI, but each Namespace can use a different URI. A Namespace can safely switch Archival between `enabled` and `disabled` states as long as Archival is enabled at the Temporal Service level. -Archival is supported in [Global Namespaces](/namespaces#global-namespace) (Namespaces that span multiple clusters). +Archival is supported in [Global Namespaces](/global-namespace) (Namespaces that span multiple clusters). When Archival is running in a Global Namespace, it first runs on the active cluster; later it runs on the standby cluster. Before archiving, a history check is done to see what has been previously archived. #### Test setup diff --git a/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx b/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx index ace982f186..f28883c570 100644 --- a/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx +++ b/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx @@ -21,7 +21,7 @@ When necessary, for higher availability, Cluster operators can failover to any o Temporal's Multi-Cluster Replication feature is considered **experimental** and not subject to normal [versioning and support policy](/clusters). Temporal automatically forwards Start, Signal, and Query requests to the active Cluster. -This feature must be enabled through a Dynamic Config flag per [Global Namespace](/namespaces#global-namespace). +This feature must be enabled through a Dynamic Config flag per [Global Namespace](/global-namespace). When the feature is enabled, Tasks are sent to the Parent Task Queue partition that matches that Namespace, if it exists. diff --git a/docs/tctl-v1/namespace.mdx b/docs/tctl-v1/namespace.mdx index 020da3f295..a8c4468edb 100644 --- a/docs/tctl-v1/namespace.mdx +++ b/docs/tctl-v1/namespace.mdx @@ -51,7 +51,7 @@ This modifier is required unless the global `--namespace` modifier is specified tctl namespace describe --namespace_id ``` -Example results for a [Global Namespace](/namespaces#global-namespace) +Example results for a [Global Namespace](/global-namespace) ```bash $ tctl --ns canary-namespace n desc @@ -130,7 +130,7 @@ tctl namespace register --description ### --global_namespace -Specifies whether a [Namespace](/namespaces) is a [Global Namespace](/namespaces#global-namespace). +Specifies whether a [Namespace](/namespaces) is a [Global Namespace](/global-namespace). When enabled, it controls the creation of replication tasks on updates allowing the state to be replicated across Clusters. This is a read-only setting and cannot be changed.