Version: 10.0

Namespace Configuration

Namespaces provide a logical categorization system for organizing keys, prefixes, and identifiers in cluster deployments. They enable multi-tenancy, environment segregation, and resource isolation across different deployment scenarios.

Overview

A namespace in webPDF Server is used to:

Generate unique prefixes for Redis/Valkey keys
Create default names for storage resources (S3 buckets, Azure Blob containers, MinIO buckets)
Isolate resources between different environments, regions, or deployments
Support multi-tenancy by segregating data from different organizations or applications

Namespace Structure

A namespace consists of multiple optional and required components that combine to form hierarchical identifiers:

Components

Component	Type	Required	Description	Example
`org`	string	No	Organization or vendor identifier	`acme`, `webpdf`
`app`	string	Yes	Application identifier	`webpdf`
`env`	string	No	Environment name	`prod`, `dev`, `staging`
`region`	string	No	Regional identifier	`eu1`, `us-east`, `eu-central`
`cluster`	string	No	Cluster discriminator for blue/green or canary deployments	`blue`, `green`, `canary`
`version`	string	Yes	Key schema version	`v10.0`, `v9.0`

Default Values

If components are not specified, the following defaults are used:

app: webpdf (from product name)
version: Current product version (e.g., v10.0)

Configuration

Namespace settings are configured in the cluster configuration file (cluster.json):

Important

The namespace configuration must be identical across all cluster nodes. The cluster coordinator will validate the configuration and member join will fail if it does not match.

cluster.json

{
  "mode": "cluster",
  "role": "coordinator",
  "name": "webpdf-cluster",
  "namespace": {
    "org": "acme",
    "app": "webpdf",
    "env": "prod",
    "region": "eu-central",
    "cluster": "blue",
    "version": "v10.0"
  }
}

Environment Variables

Namespace components can be configured via environment variables:

# Organization
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_ORG=acme

# Application
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_APP=webpdf

# Environment
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_ENV=prod

# Region
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_REGION=eu-central

# Cluster discriminator
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_CLUSTER=blue

# Version
WEBPDF_CLUSTER_SETTINGS_NAMESPACE_VERSION=v10.0

Usage in Providers

Namespaces are primarily used by storage and session providers to create prefixes and identifiers.

Redis and Valkey Providers

Redis and Valkey use namespaces to construct hierarchical key prefixes for different data domains:

Key Structure

Keys follow a hierarchical pattern:

<namespace>:<domain>:<type>:<identifier>

Where:

namespace: Built from namespace components
domain: Key domain (session, document, event, history)
type: Key type (data, index, lock)
identifier: Unique ID (session ID, document ID, etc.)

Key Domains

Domain	Purpose	Example Keys
`session`	Session management	`<ns>:session:data:<sessionId>`
`document`	Document storage	`<ns>:document:data:<sessionId>:<documentId>`
`event`	Event notifications	`<ns>:event`
`history`	Document history	`<ns>:history:data:<sessionId>:<documentId>`

Examples

Simple Namespace:

{
  "namespace": {
    "app": "webpdf",
    "version": "v10.0"
  }
}

Generated key examples:

webpdf:v10-0:session:data:abc123
webpdf:v10-0:document:data:abc123:doc456
webpdf:v10-0:event

Complex Namespace:

{
  "namespace": {
    "org": "acme",
    "app": "webpdf",
    "env": "prod",
    "region": "eu1",
    "version": "v10.0"
  }
}

Generated key examples:

acme:webpdf:prod:eu1:v10-0:session:data:abc123
acme:webpdf:prod:eu1:v10-0:document:data:abc123:doc456

Index Keys

Index keys are used for listing and searching:

<namespace>:session:index
<namespace>:document:index

Lock Keys

Lock keys are used for distributed locking:

<namespace>:session:lock:<sessionId>
<namespace>:session:lock:expiration
<namespace>:session:lock:reconciliation
<namespace>:document:lock:<sessionId>:<documentId>

File Storage Providers (MinIO, Azure Blob, S3)

File storage providers use namespaces to generate default bucket or container names when not explicitly configured.

Naming Pattern

{org}-{app}-{env}-{version}

Examples

MinIO Bucket Name:

{
  "namespace": {
    "org": "acme",
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Generated bucket name: acme-webpdf-prod-v10-0

Azure Blob Container Name:

{
  "namespace": {
    "app": "webpdf",
    "env": "staging",
    "version": "v10.0"
  }
}

Generated container name: webpdf-staging-v10-0

note

Storage provider naming rules apply. For example, Azure Blob containers must be lowercase (automatically converted), and S3 buckets must follow AWS naming rules.

Use Cases

Multi-Environment Deployment

Separate resources for different environments:

Production cluster.json:

{
  "namespace": {
    "org": "mycompany",
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Development cluster.json:

{
  "namespace": {
    "org": "mycompany",
    "app": "webpdf",
    "env": "dev",
    "version": "v10.0"
  }
}

Result:

Production keys: mycompany:webpdf:prod:v10-0:*
Development keys: mycompany:webpdf:dev:v10-0:*

Multi-Region Deployment

Isolate resources by region:

EU Region cluster.json:

{
  "namespace": {
    "org": "global",
    "app": "webpdf",
    "env": "prod",
    "region": "eu-central",
    "version": "v10.0"
  }
}

US Region cluster.json:

{
  "namespace": {
    "org": "global",
    "app": "webpdf",
    "env": "prod",
    "region": "us-east",
    "version": "v10.0"
  }
}

Result:

EU keys: global:webpdf:prod:eu-central:v10-0:*
US keys: global:webpdf:prod:us-east:v10-0:*

Blue/Green Deployment

Support parallel deployments:

Blue Deployment cluster.json:

{
  "namespace": {
    "app": "webpdf",
    "env": "prod",
    "cluster": "blue",
    "version": "v10.0"
  }
}

Green Deployment cluster.json:

{
  "namespace": {
    "app": "webpdf",
    "env": "prod",
    "cluster": "green",
    "version": "v10.0"
  }
}

Result:

Blue keys: webpdf:prod:blue:v10-0:*
Green keys: webpdf:prod:green:v10-0:*

Multi-Tenancy

Separate data for different organizations:

Tenant A cluster.json:

{
  "namespace": {
    "org": "tenant-a",
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Tenant B cluster.json:

{
  "namespace": {
    "org": "tenant-b",
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Result:

Tenant A keys: tenant-a:webpdf:prod:v10-0:*
Tenant B keys: tenant-b:webpdf:prod:v10-0:*

Best Practices

1. Use Meaningful Names

Choose descriptive names that clearly indicate the purpose:

Good:

{
  "namespace": {
    "org": "acme-corp",
    "env": "production",
    "region": "eu-central-1"
  }
}

Avoid:

{
  "namespace": {
    "org": "ac",
    "env": "p",
    "region": "eu1"
  }
}

2. Be Consistent

Use the same naming pattern across all deployments:

Always use lowercase for organization names
Use standardized environment names (prod, staging, dev)
Follow consistent region naming (e.g., AWS region names)

3. Version Appropriately

Include version information for schema compatibility:

{
  "namespace": {
    "version": "v10.0"
  }
}

4. Plan for Growth

Consider future expansion when choosing namespace structure:

{
  "namespace": {
    "org": "company",
    "app": "webpdf",
    "env": "prod",
    "region": "eu-central",
    "version": "v10.0"
  }
}

This allows adding regions later (us-east, asia-pacific, etc.)

5. Document Your Strategy

Maintain documentation of your namespace strategy:

List all namespaces in use
Document the purpose of each component
Define naming conventions for your organization

Migration Considerations

Changing Namespaces

Changing namespace configuration requires careful planning:

Redis/Valkey: Keys will be created under new namespace, existing keys remain
File Storage: New bucket/container will be created, existing files remain
Data Migration: Manual migration may be required to move data to new namespace

Version Updates

When upgrading webPDF:

Keep version if you want to maintain compatibility
Update version if you want to isolate new version data

Keep same namespace across versions:

{
  "namespace": {
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Or isolate by version:

{
  "namespace": {
    "app": "webpdf",
    "env": "prod",
    "version": "v10.1"
  }
}

Troubleshooting

Keys Not Found in Redis/Valkey

Verify namespace configuration matches across all nodes
Check key prefix in Redis CLI:
```
redis-cli KEYS "<namespace>:*"
```
Ensure consistent configuration in cluster coordinator and members

Bucket/Container Not Created

Check namespace settings in provider configuration
Verify automatic naming is enabled (no explicit bucket name)
Review logs for bucket creation attempts
Check provider permissions for bucket creation

Conflicting Resources

If resources conflict:

Add discriminator (cluster, region, or org component)
Verify uniqueness of generated names
Check for typos in namespace configuration

Examples

Minimal Configuration

{
  "namespace": {
    "app": "webpdf"
  }
}

Generated keys: webpdf:v10-0:session:data:*

Production Configuration

{
  "namespace": {
    "org": "acme",
    "app": "webpdf",
    "env": "prod",
    "version": "v10.0"
  }
}

Generated keys: acme:webpdf:prod:v10-0:session:data:*

Multi-Region Configuration

{
  "namespace": {
    "org": "global",
    "app": "webpdf",
    "env": "prod",
    "region": "eu-central",
    "version": "v10.0"
  }
}

Generated keys: global:webpdf:prod:eu-central:v10-0:session:data:*

Blue/Green Configuration

Blue cluster.json:

{
  "namespace": {
    "org": "company",
    "app": "webpdf",
    "env": "prod",
    "cluster": "blue",
    "version": "v10.0"
  }
}

Green cluster.json:

{
  "namespace": {
    "org": "company",
    "app": "webpdf",
    "env": "prod",
    "cluster": "green",
    "version": "v10.0"
  }
}

Generated keys:

Blue: company:webpdf:prod:blue:v10-0:*
Green: company:webpdf:prod:green:v10-0:*

Cluster Configuration - Overall cluster setup
Redis Provider - Redis session storage
Valkey Provider - Valkey session storage
MinIO Provider - MinIO file storage
Azure Blob Provider - Azure Blob storage

Overview​

Namespace Structure​

Components​

Default Values​

Configuration​

cluster.json​

Environment Variables​

Usage in Providers​

Redis and Valkey Providers​

Key Structure​

Key Domains​

Examples​

Index Keys​

Lock Keys​

File Storage Providers (MinIO, Azure Blob, S3)​

Naming Pattern​

Examples​

Use Cases​

Multi-Environment Deployment​

Multi-Region Deployment​

Blue/Green Deployment​

Multi-Tenancy​

Best Practices​

1. Use Meaningful Names​

2. Be Consistent​

3. Version Appropriately​

4. Plan for Growth​

5. Document Your Strategy​

Migration Considerations​

Changing Namespaces​

Version Updates​

Troubleshooting​

Keys Not Found in Redis/Valkey​

Bucket/Container Not Created​

Conflicting Resources​

Examples​

Minimal Configuration​

Production Configuration​

Multi-Region Configuration​

Blue/Green Configuration​

Related Configuration​

Overview

Namespace Structure

Components

Default Values

Configuration

cluster.json

Environment Variables

Usage in Providers

Redis and Valkey Providers

Key Structure

Key Domains

Examples

Index Keys

Lock Keys

File Storage Providers (MinIO, Azure Blob, S3)

Naming Pattern

Examples

Use Cases

Multi-Environment Deployment

Multi-Region Deployment

Blue/Green Deployment

Multi-Tenancy

Best Practices

1. Use Meaningful Names

2. Be Consistent

3. Version Appropriately

4. Plan for Growth

5. Document Your Strategy

Migration Considerations

Changing Namespaces

Version Updates

Troubleshooting

Keys Not Found in Redis/Valkey

Bucket/Container Not Created

Conflicting Resources

Examples

Minimal Configuration

Production Configuration

Multi-Region Configuration

Blue/Green Configuration

Related Configuration