diff --git a/docs/best-practices/managing-namespace.mdx b/docs/best-practices/managing-namespace.mdx index 0b033d377e..d9d86319e3 100644 --- a/docs/best-practices/managing-namespace.mdx +++ b/docs/best-practices/managing-namespace.mdx @@ -1,8 +1,8 @@ --- id: managing-namespace -title: Managing a Namespace -sidebar_label: Managing a Namespace -description: Best practices for managing Temporal Namespaces including configuration, retention, and optimization strategies. +title: Namespace Best Practices +sidebar_label: Namespace Best Practices +description: Best practices for organizing and managing Temporal Namespaces, including naming conventions, organizational patterns, and production safeguards. toc_max_heading_level: 4 keywords: - namespace management @@ -14,121 +14,150 @@ tags: - Namespaces --- -A [Namespace](https://docs.temporal.io/namespaces) is a unit of isolation within the Temporal platform. It ensures that workflow executions, task queues, and resources are logically separated, preventing any conflicts and enabling safe multi-tenant usage. +:::info Applies to both open source and Temporal Cloud +This page covers namespace best practices that apply to **both** open source Temporal and Temporal Cloud. +Platform-specific guidance is clearly labeled throughout. -Namespaces are created on the Temporal Service, and one Namespace will not impact another on the same Temporal Service. However, a single Namespace can be multi-tenant, and they act solely as a logical separation. +For reference documentation, see: +- [Namespace concepts](/namespaces) +- [Managing Namespaces (open source)](/self-hosted-guide/namespaces) +- [Namespaces (Temporal Cloud)](/cloud/namespaces) +::: -If you are running Temporal on your own, you might be familiar with services within a cluster, such as the front-end, backend, matching service, and more. In Temporal Cloud all of these services are managed by us, so you don’t have to worry about managing them at all! +A [Namespace](/namespaces) is a unit of isolation within the Temporal Platform. +It ensures that Workflow Executions, Task Queues, and resources are logically separated, preventing conflicts and enabling safe multi-tenant usage. -## How to Register a Namespace +## Naming Conventions -[Registering a Namespace](https://docs.temporal.io/namespaces#registration) creates the Namespace on the Temporal Service. You’re also required to set the retention period when creating the Namespace. +### Use lowercase and hyphens -On Temporal Cloud, use the Temporal Cloud UI or `tcld` commands to create and manage Namespaces. If no other Namespace is specified, the Temporal Service uses the Namespace `default` for all Temporal SDKs and the Temporal CLI. +Use lowercase letters and hyphens (`-`) as separators in Namespace names. -Temporal Cloud enforces limits on Namespace count and workflow execution size. You are allowed up to **10 Namespaces by default**. Exceeding this limit requires a support ticket. +- **Temporal Cloud**: Namespace names are case-insensitive, so `MyNamespace` and `mynamespace` refer to the same Namespace. +- **Open source**: Namespace names are case-sensitive, so `MyNamespace` and `mynamespace` are different Namespaces. -When it comes to naming Namespaces for your team, we recommend grouping them by factors such as teams, products or lines of business. You’ll also likely want to distinguish between dev and prod environments in the naming convention. +To avoid confusion across environments, always use lowercase. -Each Namespace in Temporal Cloud runs in a specific region, which determines where your workflows and data are hosted. Temporal Cloud currently runs on AWS and GCP, with support for other clouds planned for the future. +**Example**: `payment-checkout-prd` -While your cloud infrastructure might be limited to a single region, Temporal Cloud supports multiple regions, and you’ll have access to a full list of available regions during Namespace creation. To view the current list of supported regions and their operational status, visit: https://status.temporal.io +### Follow a consistent naming pattern -### Best Practices: +Use a pattern like `--` to name Namespaces: -#### 1. Use lowercase and hyphens for Namespace names: Temporal Cloud treats Namespace names as case-insensitive. To maintain consistency and avoid potential issues, use lowercase letters and hyphen (-) as separators. Example: `payment-checkout-prd` +| Component | Max Length | Examples | +|-----------|------------|----------| +| Use case | 10 chars | `payments`, `fulfill`, `orders` | +| Domain | 10 chars | `checkout`, `notify`, `inventory` | +| Environment | 3 chars | `dev`, `stg`, `prd` | -#### 2. Use domain, service, and environment to name Namespaces -Use the following pattern to name Temporal Namespaces: `---` - - The following rules ensure that the Namespace name doesn’t exceed [39 characters](https://docs.temporal.io/cloud/namespaces#temporal-cloud-namespace-name): - - Use at most 10 characters for `use case` (e.g. `payments`, `fulfill`) - - Use at most 10 character for `domain` (e.g. `checkout`, `notify`) - - Use at most 5 characters for `region` (e.g. `aps1`, `apse1`) - - Use at most 3 characters for `environment` (e.g. `dev`, `prd`) - - Examples: `payments-checkout-dev`, `payments-checkout-prd`, `fulfill-notify-prd` +**Examples**: `payments-checkout-dev`, `fulfill-notify-prd`, `orders-inventory-stg` **Why this pattern?** -- Simple and easy to understand. -- Complies to [Temporal Cloud Namespace requirements](https://docs.temporal.io/cloud/namespaces#temporal-cloud-namespace-name) -- Clearly separates environments (e.g., `dev`, `prod`) -- Groups related services under domains that organization has defined -- Allows for platform teams to implement chargeback to application teams, given most domains are owned by separate teams within organizations -- Namespace level [system limits](https://docs.temporal.io/cloud/limits#namespace-level) are isolated between different services and environments. -- Multiple workflows that are part of the same use case need to communicate with each other via Signals or by starting Child Workflows. +- Simple and easy to understand +- Clearly separates environments +- Groups related services under domains +- Allows platform teams to implement chargeback to application teams +- Namespace-level limits are isolated between different services and environments + +:::tip Temporal Cloud +Cloud Namespace names are limited to [39 characters](/cloud/namespaces#temporal-cloud-namespace-name). +If you need to include region, use short codes (e.g., `aps1`, `use1`). +::: + +## Organizational Patterns + +### Pattern 1: Namespace per use case and environment + +For simple configurations without multiple services or team boundaries. + +**Naming convention**: `_` + +**Example**: `payments_prod`, `orders_dev` + +### Pattern 2: Namespace per use case, service, and environment + +When multiple services that are part of the same use case communicate externally to Temporal via API (HTTP/gRPC). + +**Naming convention**: `__` + +**Example**: `payments_gateway_prod`, `payments_processor_prod` + +### Pattern 3: Namespace per use case, domain, and environment + +When multiple services need to communicate with each other, use [Temporal Nexus](/nexus) to connect Workflows across Namespace boundaries. +This provides better security, fault isolation, and modularity than sharing a Namespace. + +**Naming convention**: `__` + +**Example**: `payments_checkout_prod`, `payments_refunds_prod` - Note: [A Temporal Cloud account can have up to 100 Namespaces](https://docs.temporal.io/cloud/limits#namespaces) (soft limit). +For systems without Nexus, services can communicate via [Signals](/sending-messages#sending-signals) or [Child Workflows](/child-workflows) within the same Namespace. -#### 3. When selecting a region for your Namespace, choose one that aligns with your application's latency, compliance, and data residency requirements (use https://status.temporal.io/ to identify the right region for you). +:::note Workflow ID uniqueness +When multiple teams share a Namespace, prefix each Workflow ID with a service-specific string to ensure uniqueness. +Task Queue names must also be unique within the Namespace. +::: - Check out some more best practices for configuring Namespaces in [our documentation](https://docs.temporal.io/cloud/namespaces#general-guidance). +## Production Safeguards -## Manage Namespaces +### Use an Authorizer (open source only) {#authorizer} -With Temporal, it’s important to be able to configure your Namespaces as well as see details for them. Whether you’re self-hosting or using Temporal Cloud, you’re able to get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces. +Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service to set restrictions on who can create, update, or deprecate Namespaces. -On Temporal Cloud, use the Temporal Cloud UI or `tcld` commands to manage Namespaces. We provide [guidance for both methods](https://docs.temporal.io/cloud/namespaces#manage-namespaces) in our docs that you can reference. +If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls. -Regardless of how you run Temporal, you must register a Namespace with the Temporal Service before setting it in the Temporal Client. +On Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration. -We recommend you use a custom [Authorizer](https://docs.temporal.io/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. If an Authorizer is not set in the server options, Temporal uses the nopAuthority authorizer that unconditionally allows all API calls to pass through. +### Enable deletion protection (Temporal Cloud only) {#deletion-protection} -### Best practices: +[Enable deletion protection](/cloud/namespaces#delete-protection) for production Namespaces to prevent accidental deletion. -#### 1. Enable deletion protection for `prd` Namespaces: [Prevent accidental deletion](https://docs.temporal.io/cloud/namespaces#delete-protection) of production Namespaces. +### Enable High Availability (Temporal Cloud only) {#high-availability} -#### 2. Enable multi-region replication for business critical use cases: For many organizations, ensuring high availability (HA) is required because of strict uptime requirements, compliance, and regulatory needs. +For business-critical use cases with strict uptime requirements, enable [High Availability features](/cloud/high-availability) for a [99.99% contractual SLA](/cloud/high-availability#high-availability-features). - For these critical use cases, enable High Availability features for specific Namespaces for a [99.99% contractual SLA](https://docs.temporal.io/cloud/high-availability#high-availability-features). When choosing between [same-region and multi-region replication](https://docs.temporal.io/cloud/high-availability/how-it-works#deployment-options), favor multi-region replication to optimize reliability over proximity. +### Use Infrastructure as Code (Temporal Cloud only) {#terraform} - By default, Temporal Cloud provides a [99.9% contractual SLA](https://docs.temporal.io/cloud/high-availability) guarantee against service errors for all Namespaces. +Use the [Temporal Cloud Terraform provider](/production-deployment/cloud/terraform-provider) to manage Namespaces. +If Terraform isn't suitable, scripting against the [Cloud Ops API](/ops) or [tcld](/cloud/tcld) is a good alternative. - Note: [enabling HA features for Namespaces will 2x the consumption cost](https://docs.temporal.io/cloud/pricing#high-availability-features). +This provides: +- Documentation of each Namespace's purpose and owners +- Prevention of infrastructure drift +- Version-controlled configuration changes -#### 3. Use Terraform to manage Namespaces: -Use [Temporal Cloud Terraform provider](https://docs.temporal.io/production-deployment/cloud/terraform-provider) to manage Temporal Cloud Namespaces. This allows us to maintain documentation that outlines the purpose of each Namespace and their owners. In addition, Terraform enables us to prevent infrastructure drift (e.g. someone accidentally deletes a Namespace). +Use `prevent_destroy = true` in your Terraform configuration to prevent accidental Namespace deletion via Terraform. +This is separate from [Temporal Cloud deletion protection](/cloud/namespaces#delete-protection), which prevents deletion through any interface. - Use `prevent_destroy = true` to prevent Terraform from destroying the Namespace. +**Reference**: [Example Terraform configuration](https://github.com/kawofong/temporal-terraform) - Reference: https://github.com/kawofong/temporal-terraform +## Tagging (Temporal Cloud only) {#tagging} -## Tagging +[Tags](/cloud/namespaces#tag-a-namespace) are key-value metadata pairs that help organize, track, and manage Namespaces. -[Tags](https://docs.temporal.io/cloud/namespaces#tag-a-namespace) are key-value metadata pairs that can be attached to Namespaces in Temporal Cloud to help operators organize, track, and manage Namespaces more easily. +Tags complement your naming convention by adding metadata that doesn't fit in the Namespace name. +While the name captures use case, domain, and environment, tags can capture additional dimensions like team ownership, data sensitivity, or business criticality. -### Tag Structure and Limits -- Each Namespace can have a maximum of 10 tags -- Each key must be unique for a given Namespace (e.g., a Namespace cannot have both `team:foo` and `team:bar` tags) -- Keys and values must be 1-63 characters in length -- Allowed characters: lowercase letters (a-z), numbers (0-9), periods (.), underscores (_), and hyphens (-) -- Tags are not a secure storage mechanism and should not store PII or PHI -- Tags will not change the behavior of the tagged resource -- There is a soft limit of 1000 unique tag keys per account +### Recommended tag categories -We also recommend tagging your Namespaces based on the following criteria: -- Environment -- Latency sensitivity -- Business criticality: regulatory, user-facing -- Data sensitivity -- Team or Project -- Division +| Tag Key | Purpose | Examples | +|---------|---------|----------| +| `environment` | Deployment stage | `dev`, `staging`, `production` | +| `team` | Owning team | `platform`, `payments`, `identity` | +| `division` | Business unit | `engineering`, `finance`, `ops` | +| `criticality` | Business importance | `high`, `medium`, `low` | +| `data-sensitivity` | Data classification | `pii`, `pci`, `public` | +| `latency-sensitivity` | Performance tier | `realtime`, `batch`, `async` | -## Setting +For tag structure, limits, and management instructions, see [How to tag a Namespace](/cloud/namespaces#tag-a-namespace). -Temporal Cloud provides a few configurable parameters associated with a Namespace, client, or service that determines how Temporal behaves for that scope. You can configure many of these settings when creating or editing a Namespace via the UI or CLI (`tcld`). +## SDK Client Configuration -You must also 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. +Set Namespaces in your SDK Client to isolate your Workflow Executions. +If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the `default` Namespace. -Here are some of the typical Namespace settings you’re able to configure: +You must register a Namespace before setting it in your Client. -| Setting | Description | -|---------|-------------| -| `namespace` (SDK/client) | The name of the Namespace your client is scoped to | -| `retention` | How long workflow execution history is kept | -| `certificate` | The client certificate used for mTLS authentication | -| `codec_server_endpoint` | URL to a Codec Server for decrypting encrypted payloads in the UI | -| `default_task_queue` | The task queue used if none is specified in the workflow code | -| `search_attributes` | Custom fields that allow filtering and querying workflow executions | -| `data_converter` | Used to serialize/deserialize and encrypt/decrypt workflow payloads | -| `visibility settings` | Controls how workflow status data is indexed and queried | +For configuration details, see: +- [Namespace concepts](/namespaces) +- [Namespaces (Temporal Cloud)](/cloud/namespaces#access-namespaces) diff --git a/docs/encyclopedia/namespaces/namespaces.mdx b/docs/encyclopedia/namespaces/namespaces.mdx index e784fbb766..6ba739aae3 100644 --- a/docs/encyclopedia/namespaces/namespaces.mdx +++ b/docs/encyclopedia/namespaces/namespaces.mdx @@ -2,7 +2,7 @@ id: namespaces title: Temporal Namespace 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. +description: A Namespace is a unit of isolation within the Temporal Platform that provides resource separation, Workflow ID uniqueness, and configuration boundaries. slug: /namespaces toc_max_heading_level: 4 keywords: @@ -12,99 +12,33 @@ tags: - Namespaces --- -This guide provides a comprehensive overview of Namespaces. +:::info Open source and Temporal Cloud +This page covers core namespace concepts that apply to both open source Temporal and Temporal Cloud. -A Namespace is a unit of isolation within the Temporal Platform. +Temporal Cloud namespaces include additional capabilities, such as [API key](/cloud/api-keys) and [mTLS authentication](/cloud/certificates), [built-in role-based access controls](/cloud/users#namespace-level-permissions), [high availability replication](/cloud/high-availability), and [namespace tags](/cloud/namespaces#tag-a-namespace). -A single Namespace is still multi-tenant. +Moving from self-hosting to Cloud, or the reverse, requires zero code changes and incurs zero downtime. +::: -## Usage - -Namespaces are created on the Temporal Service, and provide a range of controls to achieve isolation on Workflow Executions. - -- Namespaces are a mechanism for resource isolation. Heavy traffic from one Namespace will not impact other Namespaces running on the same Temporal Service. - For example, you can use Namespaces to match the development lifecycle by having separate `dev` and `prod` Namespaces. -- If no other Namespace is specified, the Temporal Service uses the Namespace "default" for all Temporal SDKs and the Temporal CLI. - See the [Registration](#registration) section for details. -- Namespaces created on self-hosted Temporal Service are case-sensitive. For example, `foo` and `Foo` are two different Namespaces. - On Temporal Cloud, Namespaces are case-insensitive, and we recommend using lowercase for Namespace names to avoid potential issues. -- **Membership:** [Task Queue](/task-queue) names and [Workflow Ids](/workflow-execution/workflowid-runid#workflow-id) must all correspond to a specific Namespace. - For example, when a Workflow Execution is spawned, it does so within a specific Namespace. -- **Uniqueness:** Temporal guarantees a unique Workflow Id within a Namespace. - Workflow Executions may have the same Workflow Id if they are in different Namespaces. -- **Namespace Configuration:** Various configuration options like the [Retention Period](/temporal-service/temporal-server#retention-period) and the [Archival](/temporal-service/archival) destination are configured per Namespace through a special CRUD API or through the [Temporal CLI](/cli). - -## Registration - -Registering a Namespace creates the Namespace on the Temporal Service. -When you register your Namespace, you must also set the [Retention Period](/temporal-service/temporal-server#retention-period) for the Namespace. - -On Temporal Cloud, use the [Temporal Cloud UI](/cloud/namespaces#create-a-namespace) or [tcld commands](https://docs.temporal.io/cloud/tcld/namespace/) to create and manage Namespaces. - -On self-hosted Temporal Service, you can register your Namespaces using the Temporal CLI (recommended) or programmatically using APIs. Note that these APIs and Temporal CLI commands will not work with Temporal Cloud. - -All SDKs require a Namespace on the Temporal Service (or Temporal Cloud) for their Client calls. If not set using Client options, the Workflow Client API looks for the `default` Namespace. If there is no default Namespace registered with your Temporal Service (or Temporal Cloud), all calls will throw errors. -You must register your Namespace with the Temporal Service (or Temporal Cloud) before setting it in your Client. - -On self-hosted Temporal Service, you can register your Namespaces in the following ways: - -- In your Temporal Service setup, create your Namespaces, including the default, in your setup script. - For example: - - - If deploying through Docker Compose or using the [auto-setup image](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh) in a custom Docker Compose application, the Namespace "default" is created, through the auto-setup script. - - If deploying through the [Temporal Helm charts](https://github.com/temporalio/helm-charts), you can create the "default" Namespace by using the Temporal CLI; for example, `temporal operator namespace create --namespace default` - -- Use the `temporal operator namespace create` or `temporal operator namespace update` command with the `--retention` modfiier to register your Namespaces, one at a time, and set the Retention Period on each. - - - [How to create a new Namespace using the Temporal CLI](/cli/operator#create) - - [How to create a new Namespace using the Go SDK](/develop/go/namespaces#register-namespace) - - [How to create a new Namespace using the Java SDK](/develop/java/namespaces#register-namespace) - -- In your Client program, register your Namespace using `RegisterNamespaceRequest` API available in all the SDKs. +A Namespace is a unit of isolation within the [Temporal Platform](/temporal#temporal-platform). -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. +[Task Queues](/task-queue) and [Workflow Executions](/workflow-execution) belong to a Namespace. +When a Workflow Execution is spawned, it does so within a specific Namespace. -## 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. - -On Temporal Cloud, use the [Temporal Cloud UI](/cloud/namespaces) or [tcld commands](/cloud/tcld/namespace/) to manage Namespaces. - -On self-hosted Temporal Service, you can manage your registered Namespaces using the Temporal CLI (recommended) or programmatically using APIs. - -{/* Technically correct but is this confusing for people since you can do this for non-self-hosted: _/} -{/_ Note that these APIs and temporal CLI commands will not work with Temporal Cloud. */} - -- [How to manage Namespaces using the Go SDK](/develop/go/namespaces#manage-namespaces) -- [How to manage Namespaces using the Java SDK](/develop/java/namespaces#manage-namespaces) - -- Update information and configuration for a registered Namespace on your Temporal Service: - - - With the Temporal CLI: [`temporal operator namespace update`](/cli/operator#update) - - Use the Update Namespace API to update configuration on a Namespace. - -- Get details for a registered Namespace on your Temporal Service: - - - With the Temporal CLI: [`temporal operator namespace describe`](/cli/operator#describe) - - Use the Describe Namespace to return information and configuration details for a registered Namespace. - -- Get details for all registered Namespaces on your Temporal Service: - - - With the Temporal CLI: [`temporal operator namespace list`](/cli/operator#list) - - Use the List Namespace API to return information and configuration details for all registered Namespaces on your Temporal Service. - -- Deprecate a Namespace: The Deprecate Namespace updates the state of a registered Namespace to "DEPRECATED". Once a Namespace is deprecated, you cannot start new Workflow Executions on it. All existing and running Workflow Executions on a deprecated Namespace will continue to run. - -- Delete a Namespace: Deletes a Namespace and all Workflow Executions on the Namespace. Note that this API is supported for Temporal Server version 1.17 and later. -- 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. +## Usage -## Setting +- **Workflow ID uniqueness**: Temporal guarantees a unique Workflow Id within a Namespace. + Workflow Executions may have the same Workflow Id if they are in different Namespaces. +- **Resource isolation**: Heavy traffic from one Namespace will not impact other Namespaces running on the same Temporal Service. +- **Configuration boundaries**: Options like the [Retention Period](/temporal-service/temporal-server#retention-period) and [Archival](/temporal-service/archival) destination are configured per Namespace. +- **Default Namespace**: If no Namespace is specified, the Temporal Service uses the Namespace "default" for all Temporal SDKs and the Temporal CLI. + You must create a Namespace before using it in your Client. +- **Multi-tenancy**: A single Namespace is still multi-tenant. + Multiple applications or teams can share a Namespace, but must coordinate on Workflow ID and Task Queue naming to avoid conflicts. -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. +## Namespace operations -{/* TODO add sample for this to link to -[How to set the Namespace for a Temporal Client](/) */} +For how to create and manage Namespaces: -- [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) +- **Open source Temporal**: [Managing Namespaces](/self-hosted-guide/namespaces) +- **Temporal Cloud**: [Temporal Cloud Namespaces](/cloud/namespaces) diff --git a/docs/production-deployment/cloud/get-started/namespaces.mdx b/docs/production-deployment/cloud/get-started/namespaces.mdx index d22358e6e2..d64d368afb 100644 --- a/docs/production-deployment/cloud/get-started/namespaces.mdx +++ b/docs/production-deployment/cloud/get-started/namespaces.mdx @@ -21,6 +21,12 @@ tags: import { CaptionedImage, ZoomingImage } from '@site/src/components'; +:::info Temporal Cloud +This page covers namespace operations in **Temporal Cloud**. +For core namespace concepts, see [Temporal Namespace](/namespaces). +For open source Temporal, see [Managing Namespaces](/self-hosted-guide/namespaces). +::: + A Namespace is a unit of isolation within Temporal Cloud, providing security boundaries, Workflow management, unique identifiers, and gRPC endpoints in Temporal Cloud. diff --git a/docs/production-deployment/self-hosted-guide/index.mdx b/docs/production-deployment/self-hosted-guide/index.mdx index 83db781cf0..f621ca1596 100644 --- a/docs/production-deployment/self-hosted-guide/index.mdx +++ b/docs/production-deployment/self-hosted-guide/index.mdx @@ -37,6 +37,7 @@ Check out the [dev guide](/develop) for application development best practices. - [Deployment](/self-hosted-guide/deployment) - [Defaults](/self-hosted-guide/defaults) - [Production checklist](/self-hosted-guide/production-checklist) +- [Namespaces](/self-hosted-guide/namespaces) - [Security](/self-hosted-guide/security) - [Monitoring](/self-hosted-guide/monitoring) - [Visibility](/self-hosted-guide/visibility) diff --git a/docs/production-deployment/self-hosted-guide/namespaces.mdx b/docs/production-deployment/self-hosted-guide/namespaces.mdx new file mode 100644 index 0000000000..d625f40749 --- /dev/null +++ b/docs/production-deployment/self-hosted-guide/namespaces.mdx @@ -0,0 +1,84 @@ +--- +id: namespaces +title: Managing Namespaces +sidebar_label: Namespaces +description: How to create and manage Namespaces in open source Temporal, including registration, configuration, and security. +slug: /self-hosted-guide/namespaces +keywords: + - namespaces + - self-hosted + - open source +tags: + - Namespaces + - Self-hosting +--- + +:::info Open source Temporal +This page covers namespace operations for **open source Temporal**. +For core namespace concepts, see [Temporal Namespace](/namespaces). +For Temporal Cloud, see [Temporal Cloud Namespaces](/cloud/namespaces). +::: + +A [Namespace](/namespaces) is a unit of isolation within the Temporal Platform. +Before you can run Workflows, you must register at least one Namespace with your Temporal Service. + +## Create a Namespace + +Registering a Namespace creates it on the Temporal Service. +When you register a Namespace, you must set a [Retention Period](/temporal-service/temporal-server#retention-period) that determines how long closed Workflow execution history is kept. + +You can create Namespaces using: + +- **Temporal CLI** (recommended): [`temporal operator namespace create`](/cli/operator#create) +- **Go SDK**: [`RegisterNamespace`](/develop/go/namespaces#register-namespace) +- **Java SDK**: [`RegisterNamespace`](/develop/java/namespaces#register-namespace) +- **TypeScript SDK**: [Namespace management](/develop/typescript/namespaces#register-namespace) + +### The default Namespace + +If no Namespace is specified, SDKs and CLI use the `default` Namespace. +You must register this Namespace before using it. + +When deploying with Docker Compose or the [auto-setup image](https://github.com/temporalio/docker-builds/blob/main/docker/auto-setup.sh), the `default` Namespace is created automatically. + +When deploying with [Helm charts](https://github.com/temporalio/helm-charts), create it manually: + +```bash +temporal operator namespace create --namespace default +``` + +Namespace registration takes up to 15 seconds to complete. +Wait for this process to finish before making calls to the Namespace. + +## Manage Namespaces + +Common namespace management operations: + +| Operation | CLI Command | Description | +|-----------|-------------|-------------| +| List | [`temporal operator namespace list`](/cli/operator#list) | List all registered Namespaces | +| Describe | [`temporal operator namespace describe`](/cli/operator#describe) | Get details for a Namespace | +| Update | [`temporal operator namespace update`](/cli/operator#update) | Update Namespace configuration | +| Delete | [`temporal operator namespace delete`](/cli/operator#delete) | Delete a Namespace and all its data | + +For SDK-based namespace management: +- [Go SDK namespace management](/develop/go/namespaces#manage-namespaces) +- [Java SDK namespace management](/develop/java/namespaces#manage-namespaces) +- [TypeScript SDK namespace management](/develop/typescript/namespaces#manage-namespaces) + +### Deprecate vs Delete + +- **Deprecate**: Prevents new Workflow Executions from starting, but existing Workflows continue to run. +- **Delete**: Removes the Namespace and all Workflow Executions. This is irreversible. + +## Security + +Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service to control who can create, update, or deprecate Namespaces. + +Without an Authorizer configured, Temporal uses the `nopAuthority` authorizer that allows all API calls unconditionally. + +For Temporal Cloud, [role-based access controls](/cloud/users#namespace-level-permissions) provide namespace-level authorization without custom configuration. + +## Best practices + +For namespace naming conventions, organizational patterns, and production safeguards, see [Namespace Best Practices](/best-practices/managing-namespace). diff --git a/sidebars.js b/sidebars.js index dac67dc06e..1aea3eacef 100644 --- a/sidebars.js +++ b/sidebars.js @@ -531,6 +531,7 @@ module.exports = { 'production-deployment/self-hosted-guide/deployment', 'production-deployment/self-hosted-guide/checklist', 'production-deployment/self-hosted-guide/defaults', + 'production-deployment/self-hosted-guide/namespaces', 'production-deployment/self-hosted-guide/security', 'production-deployment/self-hosted-guide/monitoring', 'production-deployment/self-hosted-guide/visibility',