Namespaces
This page shows how to do the following:
You can create, update, deprecate or delete your Namespaces using either the Temporal CLI or SDK APIs.
Use Namespaces to isolate your Workflow Executions according to your needs.
For example, you can use Namespaces to match the development lifecycle by having separate dev and prod Namespaces.
You could also use them to ensure Workflow Executions between different teams never communicate - such as ensuring that the teamA Namespace never impacts the teamB Namespace.
On Temporal Cloud, use the Temporal Cloud UI to create and manage a Namespace from the UI, or temporal cloud namespace commands to manage Namespaces from the command line.
On self-hosted Temporal Service, you can register and manage your Namespaces using the Temporal CLI (recommended) or programmatically using APIs.
Note that these APIs and temporal operator namespace commands will not work with Temporal Cloud. To manage Namespaces from the command line on Temporal Cloud, use the Temporal Cloud extension.
Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.
You must register a Namespace with the Temporal Service before setting it in the Temporal Client.
Register a Namespace
Registering a Namespace creates a Namespace on the Temporal Service or Temporal Cloud.
On Temporal Cloud, use the Temporal Cloud UI or temporal cloud namespace commands to create 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 operator namespace commands will not work with Temporal Cloud. To manage Namespaces from the command line on Temporal Cloud, use the Temporal Cloud extension.
Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.
Use the RegisterNamespace API to register a Namespace and set the Retention Period for the Workflow Execution Event History for the Namespace.
public static void createNamespace(WorkflowServiceStubs service, String name) {
RegisterNamespaceRequest req =
RegisterNamespaceRequest.newBuilder()
.setNamespace(name)
// Keeps the Workflow Execution Event History for up to 3 days in the Persistence store.
// Not setting this value throws an error.
.setWorkflowExecutionRetentionPeriod(Durations.fromDays(3))
.build();
service.blockingStub().registerNamespace(req);
}
The Retention Period setting using WorkflowExecutionRetentionPeriod is mandatory.
The minimum value is 1 hour for a local Namespace and 1 day for a global Namespace that replicates across clusters.
Once registered, set Namespace using WorkflowClientOptions within a Workflow Client to run your Workflow Executions within that Namespace.
See Connect to a Development Temporal Service for details.
Note that Namespace registration using this API takes up to 10 seconds to complete. Ensure that you wait for this registration to complete before starting the Workflow Execution against the Namespace.
To update your Namespace, use the UpdateNamespace API on the same WorkflowServiceStubs.
Manage Namespaces
You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces.
On Temporal Cloud, use the Temporal Cloud UI or temporal cloud namespace commands to manage Namespaces.
On self-hosted Temporal Service, you can manage your registered Namespaces using the Temporal CLI (recommended) or programmatically using APIs.
Note that these APIs and temporal operator namespace commands will not work with Temporal Cloud. To manage Namespaces from the command line on Temporal Cloud, use the Temporal Cloud extension.
Use a custom Authorizer on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces.
Update information and configuration for a registered Namespace on your Temporal Service with the Temporal CLI
command temporal operator namespace update, or with the
UpdateNamespace API:
UpdateNamespaceRequest updateNamespaceRequest =
UpdateNamespaceRequest.newBuilder()
// The Namespace that you want to update
.setNamespace(name)
// Has options to update Namespace info
.setUpdateInfo(
UpdateNamespaceInfo.newBuilder()
// Updates the description in the Namespace info
.setDescription("your updated namespace description")
.build())
// Has options to update Namespace configuration
.setConfig(
NamespaceConfig.newBuilder()
// Updates the Retention Period for the Namespace to 30 hours
.setWorkflowExecutionRetentionTtl(Durations.fromHours(30))
.build())
.build();
UpdateNamespaceResponse updateNamespaceResponse =
service.blockingStub().updateNamespace(updateNamespaceRequest);
Get details for a registered Namespace with
temporal operator namespace describe, or use the
DescribeNamespace API to
return information and configuration details for a registered Namespace:
DescribeNamespaceRequest descNamespace =
DescribeNamespaceRequest.newBuilder()
// Specify the Namespace you want details for
.setNamespace(name)
.build();
DescribeNamespaceResponse describeNamespaceResponse =
service.blockingStub().describeNamespace(descNamespace);
System.out.println("Namespace Description: " + describeNamespaceResponse);
Get details for all registered Namespaces with temporal operator namespace list,
or use the ListNamespaces API
to return information and configuration details for all registered Namespaces on your Temporal Service:
ListNamespacesRequest listNamespaces = ListNamespacesRequest.newBuilder().build();
// Lists one page of Namespaces. To list all of them, pass
// getNextPageToken() back in the next request until it is empty.
ListNamespacesResponse listNamespacesResponse =
service.blockingStub().listNamespaces(listNamespaces);
The DeprecateNamespace API
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.
DeprecateNamespaceRequest deprecateNamespace =
DeprecateNamespaceRequest.newBuilder()
// Specify the Namespace that you want to deprecate
.setNamespace(name)
.build();
DeprecateNamespaceResponse response =
service.blockingStub().deprecateNamespace(deprecateNamespace);
The DeleteNamespace API
deletes a Namespace. Deleting a Namespace deletes all running and completed Workflow Executions on the Namespace, and
removes them from the persistence store and the visibility store. It's part of the Operator Service, so call it through
OperatorServiceStubs:
DeleteNamespaceResponse res =
OperatorServiceStubs.newServiceStubs(
OperatorServiceStubsOptions.newBuilder()
.setChannel(service.getRawChannel())
.validateAndBuildWithDefaults())
.blockingStub()
.deleteNamespace(DeleteNamespaceRequest.newBuilder().setNamespace(name).build());