From timelord
This skill should be used when the user asks about "temporal namespace", "create namespace", "namespace retention", "multi-tenant temporal", "namespace configuration", "namespace isolation", or needs guidance on organizing and managing Temporal namespaces.
How this skill is triggered — by the user, by Claude, or both
Slash command
/timelord:namespace-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guidance for creating, configuring, and managing Temporal namespaces.
Guidance for creating, configuring, and managing Temporal namespaces.
Namespaces provide logical isolation for workflows:
| Aspect | Isolation Level |
|---|---|
| Workflow IDs | Per namespace (can reuse IDs) |
| Task queues | Per namespace |
| Search attributes | Per namespace |
| Retention | Configurable per namespace |
| Security | Independent authorization |
| Nexus Endpoints | Cross-namespace routing (endpoint → target NS + TQ) |
# Basic creation
temporal operator namespace create --namespace orders
# With retention period
temporal operator namespace create \
--namespace orders \
--retention 168h
# With description
temporal operator namespace create \
--namespace orders \
--retention 168h \
--description "Order processing workflows"
timelord namespace create orders --retention 168h --description "Order processing"
import (
"go.temporal.io/api/operatorservice/v1"
"go.temporal.io/sdk/client"
)
func createNamespace(c client.Client) error {
ctx := context.Background()
_, err := c.OperatorService().CreateNamespace(ctx, &operatorservice.CreateNamespaceRequest{
Namespace: "orders",
WorkflowExecutionRetentionPeriod: &durationpb.Duration{
Seconds: 604800, // 7 days
},
Description: "Order processing workflows",
})
return err
}
How long completed workflow history is retained:
| Environment | Recommended Retention |
|---|---|
| Development | 1-3 days |
| Staging | 3-7 days |
| Production | 7-30 days |
| Compliance | Per requirements |
Update retention:
temporal operator namespace update \
--namespace orders \
--retention 336h # 14 days
Custom searchable fields per namespace:
# Add search attribute
temporal operator search-attribute create \
--namespace orders \
--name CustomerId \
--type Keyword
temporal operator search-attribute create \
--namespace orders \
--name OrderTotal \
--type Double
temporal operator search-attribute create \
--namespace orders \
--name OrderDate \
--type Datetime
Available types:
| Type | Description | Example |
|---|---|---|
| Keyword | Exact match string | CustomerID, Status |
| Text | Full-text search | Description |
| Int | Integer values | Count, Attempts |
| Double | Floating point | Amount, Price |
| Bool | Boolean | IsActive, IsPriority |
| Datetime | Timestamps | CreatedAt, DueDate |
| KeywordList | Multiple keywords | Tags, Categories |
Configure workflow archival:
# Enable archival
temporal operator namespace update \
--namespace orders \
--history-archival-state enabled \
--history-archival-uri "s3://bucket/archival"
├── team-a-dev
├── team-a-staging
├── team-a-prod
├── team-b-dev
├── team-b-staging
└── team-b-prod
Benefits:
├── development
├── staging
├── production
└── production-canary
Benefits:
├── orders
├── payments
├── inventory
├── shipping
└── notifications
Benefits:
When using namespace-per-service, Nexus endpoints connect them:
orders ──nexus: payments-ep──> payments
orders ──nexus: inventory-ep──> inventory
shipping ──nexus: inventory-ep──> inventory
Each endpoint routes to the handler namespace's task queue. Teams own their handler services independently.
Pattern: {team}-{service}-{environment}
orders-processing-prod
payments-api-staging
inventory-sync-dev
Rules:
| Service | Dev | Staging | Prod |
|---|---|---|---|
| Orders | orders-dev | orders-staging | orders-prod |
| Payments | payments-dev | payments-staging | payments-prod |
| Shared | shared-dev | shared-staging | shared-prod |
Configure authorization per namespace:
# Namespace-specific permissions
namespaces:
orders-prod:
allowed_principals:
- [email protected]
- [email protected]
permissions:
- READ
- WRITE
- ADMIN
orders-staging:
allowed_principals:
- [email protected]
permissions:
- READ
- WRITE
Map certificates to namespaces:
type ClaimMapper struct{}
func (c *ClaimMapper) GetClaims(authInfo *authorization.AuthInfo) (*authorization.Claims, error) {
// Extract namespace from certificate CN
cn := authInfo.TLSSubject.CommonName
// CN format: service.namespace.example.com
namespace := extractNamespace(cn)
return &authorization.Claims{
Namespaces: map[string]authorization.NamespaceClaims{
namespace: {
Permissions: []authorization.Permission{
authorization.PermissionRead,
authorization.PermissionWrite,
},
},
},
}, nil
}
Nexus endpoints route cross-namespace calls to handler task queues.
# Create endpoint
temporal operator nexus endpoint create \
--name payments-endpoint \
--target-namespace payments-ns \
--target-task-queue payments-tq
# List endpoints
temporal operator nexus endpoint list
# Describe endpoint
temporal operator nexus endpoint describe --name payments-endpoint
# Update endpoint
temporal operator nexus endpoint update \
--name payments-endpoint \
--target-task-queue new-payments-tq
# Delete endpoint
temporal operator nexus endpoint delete --name payments-endpoint
Follow the namespace naming pattern: {service}-{target}-ep
| Caller | Handler | Endpoint Name |
|---|---|---|
| orders | payments | payments-ep |
| orders | inventory | inventory-ep |
| shipping | notifications | notifications-ep |
┌──────────────┐ payments-ep ┌──────────────┐
│ orders-ns │────────────────>│ payments-ns │
│ │ inventory-ep ┌──────────────┐
│ │────────────────>│ inventory-ns │
└──────────────┘ └──────────────┘
# CLI
temporal operator namespace list
# timelord
timelord namespace list --json
# CLI
temporal operator namespace describe --namespace orders
# timelord
timelord namespace describe orders --json
temporal operator namespace update \
--namespace orders \
--retention 336h \
--description "Updated description"
# Requires force flag - destructive!
temporal operator namespace delete --namespace orders-test
Export and replay approach:
# Export histories
temporal workflow list --namespace source-ns --query "ExecutionStatus='Completed'" | \
while read wf; do
temporal workflow show --namespace source-ns --workflow-id $wf --output json > histories/$wf.json
done
# Replay in target (for verification)
# Run replay tests against new namespace
# Workflows per namespace
sum by (namespace) (temporal_workflow_active_count)
# Task queue depth per namespace
sum by (namespace, task_queue) (temporal_task_queue_depth)
# Failures per namespace
rate(temporal_workflow_failed_total[5m]) by (namespace)
groups:
- name: namespace-alerts
rules:
- alert: NamespaceHighFailureRate
expr: rate(temporal_workflow_failed_total[5m]) > 0.1
for: 5m
labels:
severity: warning
annotations:
summary: "High failure rate in namespace {{ $labels.namespace }}"
For detailed namespace patterns, consult:
references/namespace-patterns.md - Advanced organization patternsreferences/migration-procedures.md - Namespace migration guidesnpx claudepluginhub therealbill/mynet --plugin timelordDevelop and manage Temporal workflows and activities using Python, TypeScript, Go, Java, .NET, or Ruby SDKs. Debug non-determinism, stuck workflows, activity retries. Run Temporal CLI commands and dev server.
Implements durable Temporal workflows using Python SDK: sagas, distributed transactions, async/await, testing strategies, and production deployment.
Design durable workflows with Temporal for distributed systems. Covers workflow vs activity separation, saga patterns, state management, and determinism constraints.