CLI: Resources

This page covers the resource management commands for namespaces, topics, and schemas. For cluster and broker operations, see CLI: Cluster & Brokers.

---

Namespaces

Namespaces provide logical isolation for topics. Use them to organize by application, team, or environment.

List Topics in Namespace

danube-admin namespaces topics <NAMESPACE>

Example output

Topics in namespace 'default':
  /default/user-events
  /default/payment-logs
  /default/analytics

View Policies

danube-admin namespaces policies <NAMESPACE>

Example output

{
  "max_topics_per_namespace": 1000,
  "max_producers_per_topic": 100,
  "max_consumers_per_topic": 100,
  "message_ttl_seconds": 604800,
  "retention_policy": "time_based"
}

Policy	Description	Typical Values
max_topics_per_namespace	Maximum number of topics	100 – 10000
max_producers_per_topic	Maximum producers per topic	10 – 1000
max_consumers_per_topic	Maximum consumers per topic	10 – 1000
message_ttl_seconds	Message time-to-live	3600 (1h) – 604800 (7d)
retention_policy	How messages are retained	time_based, size_based

Create Namespace

danube-admin namespaces create production

Naming conventions: use lowercase letters and hyphens. Keep names descriptive — production, staging, team-analytics, payment-service.

Delete Namespace

danube-admin namespaces delete old-namespace

Caution

Deleting a namespace removes all topics within it. This is immediate and irreversible. All connected producers and consumers will be disconnected.

Safety checklist

# 1. List topics before deletion
danube-admin namespaces topics my-namespace

# 2. Check policies to understand impact
danube-admin namespaces policies my-namespace

# 3. Only then delete
danube-admin namespaces delete my-namespace

Multi-Environment Setup

Create environments with matching topics

# Create environments
danube-admin namespaces create production
danube-admin namespaces create staging
danube-admin namespaces create development

# Create same topics in each
for env in production staging development; do
  danube-admin topics create /$env/user-events
  danube-admin topics create /$env/order-events
done

---

Topics

Topics are the fundamental messaging primitive in Danube — named channels for publishing and consuming messages.

List Topics

By namespace or broker

danube-admin topics list --namespace default
danube-admin topics list --broker broker-001
danube-admin topics list --namespace default --output json

Create Topic

Create topics

# Simple topic (non-reliable delivery)
danube-admin topics create /default/logs

# With reliable delivery
danube-admin topics create /default/events --dispatch-strategy reliable

# Partitioned with schema
danube-admin topics create /default/orders \
  --partitions 5 \
  --schema-subject order-events \
  --dispatch-strategy reliable

# Using namespace flag instead of path prefix
danube-admin topics create my-topic --namespace default

Option	Description	Default
--namespace	Namespace (if not in topic path)	—
--partitions	Number of partitions	1
--schema-subject	Schema subject from registry	None
--dispatch-strategy	reliable or non_reliable	non_reliable

Dispatch strategies:

Strategy	Delivery	Use Case
non_reliable	At-most-once (fire-and-forget)	Logs, metrics, non-critical events
reliable	At-least-once (with acknowledgments)	Transactions, orders, critical events

Describe Topic

View detailed information about a topic including schema and subscriptions.

danube-admin topics describe /default/user-events

Example output

Topic: /default/user-events
Broker ID: broker-001
Delivery: Reliable

📋 Schema Registry:
  Subject: user-events
  Schema ID: 12345
  Version: 2
  Type: json_schema
  Compatibility: BACKWARD

Subscriptions: ["analytics-consumer", "audit-logger"]

JSON output (--output json)

{
  "topic": "/default/user-events",
  "broker_id": "broker-001",
  "delivery": "Reliable",
  "schema_subject": "user-events",
  "schema_id": 12345,
  "schema_version": 2,
  "schema_type": "json_schema",
  "compatibility_mode": "BACKWARD",
  "subscriptions": ["analytics-consumer", "audit-logger"]
}

List Subscriptions

danube-admin topics subscriptions /default/orders

Delete Topic

danube-admin topics delete /default/old-topic

Caution

All messages in the topic are permanently deleted. Connected consumers will be disconnected. The schema in the registry is not deleted.

Safety checklist

# 1. Check active subscriptions
danube-admin topics subscriptions /default/my-topic

# 2. Verify topic details
danube-admin topics describe /default/my-topic

# 3. Delete
danube-admin topics delete /default/my-topic

Unsubscribe

Remove a specific subscription from a topic, disconnecting consumers using it.

danube-admin topics unsubscribe /default/events --subscription old-consumer

Unload Topic

Gracefully unload a topic from its current broker for reassignment.

Reassign to another broker

danube-admin topics unload /default/events

Dispatch Configuration

Override the cluster-wide max_unacked_messages for a specific subscription. This controls how many messages the broker pipelines to consumers before waiting for acknowledgments.

Set pipelining depth

danube-admin topics set-dispatch-config /default/orders \
  --subscription order-workers \
  --max-unacked-messages 50

Read current setting

danube-admin topics get-dispatch-config /default/orders \
  --subscription order-workers

Option	Required	Description
--subscription	Yes	Subscription name
--max-unacked-messages	Yes (set)	Pipelining depth (1–10,000)

Per-subscription overrides are persisted in the metadata store and take effect on the next consumer reconnect. If no override is set, the cluster-wide default from dispatch.max_unacked_messages in danube_broker.yml is used. See Broker Configuration for the config reference.

---

Schema Configuration (Admin-Only)

These commands let administrators control topic-level schema enforcement independently of what producers set.

Configure Topic Schema

Associate a schema subject with a topic and set the validation policy.

Configure schema validation

danube-admin topics configure-schema /production/orders \
  --subject order-events \
  --validation-policy enforce \
  --enable-payload-validation

Option	Required	Values	Description
--subject	Yes	String	Schema subject from registry
--validation-policy	No	none, warn, enforce	Validation strictness (default: none)
--enable-payload-validation	No	Flag	Enable deep payload validation

Set Validation Policy

Update the validation policy without changing the schema subject.

Change validation mode

# Switch to warn mode for debugging
danube-admin topics set-validation-policy /production/orders \
  --policy warn --enable-payload-validation

# Re-enable strict validation
danube-admin topics set-validation-policy /production/orders \
  --policy enforce --enable-payload-validation

# Disable validation temporarily
danube-admin topics set-validation-policy /production/orders \
  --policy none

Policy	Behavior	Use Case
none	No validation	Development, unstructured data
warn	Validate and log errors, accept messages	Monitoring, gradual rollout
enforce	Reject invalid messages	Production data quality

Get Schema Configuration

danube-admin topics get-schema-config /production/orders

Example output

Topic: /production/orders
Schema Subject: order-events
Validation Policy: ENFORCE
Payload Validation: ENABLED
Cached Schema ID: 12345

---

Topic with Schema: Full Workflow

End-to-end setup

# 1. Register schema
danube-admin schemas register order-events \
  --schema-type json_schema \
  --file schemas/orders.json \
  --description "Order transaction schema"

# 2. Set compatibility mode
danube-admin schemas set-compatibility order-events --mode backward

# 3. Create topic
danube-admin topics create /production/orders \
  --dispatch-strategy reliable --partitions 5

# 4. Configure schema with strict validation
danube-admin topics configure-schema /production/orders \
  --subject order-events \
  --validation-policy enforce \
  --enable-payload-validation

# 5. Verify
danube-admin topics describe /production/orders
danube-admin topics get-schema-config /production/orders

---

Schemas

Manage the Schema Registry: register schemas, track versions, check compatibility, and control evolution policies.

Register

Register a schema

danube-admin schemas register user-events \
  --schema-type json_schema \
  --file schemas/user-events.json \
  --description "User event schema" \
  --tags users analytics

Example output

✅ Registered new schema version
Subject: user-events
Schema ID: 12345
Version: 1
Fingerprint: sha256:abc123...

Type	Description	Extension
json_schema	JSON Schema (Draft 7)	.json
avro	Apache Avro	.avsc
protobuf	Protocol Buffers	.proto
string	Plain text, no validation	.txt
bytes	Raw bytes, no validation	—

Get Schema

Retrieve schema details

# By subject (latest version)
danube-admin schemas get --subject user-events

# By schema ID
danube-admin schemas get --id 12345

# JSON output
danube-admin schemas get --subject user-events --output json

Example output

Schema ID: 12345
Version: 2
Subject: user-events
Type: json_schema
Compatibility Mode: BACKWARD
Description: User registration and login events
Tags: users, authentication, analytics

List Versions

danube-admin schemas versions user-events

Example output

Versions for subject 'user-events':
  Version 1: schema_id=12344, fingerprint=sha256:old123...
    Created by: alice
    Description: Initial schema
  Version 2: schema_id=12345, fingerprint=sha256:abc123...
    Created by: bob
    Description: Added email field

Check Compatibility

Validate if a new schema is compatible with existing versions before registering.

Validate before registration

danube-admin schemas check user-events \
  --file schemas/user-events-v2.json \
  --schema-type json_schema

Compatible

✅ Schema is compatible with subject 'user-events'

Incompatible

❌ Schema is NOT compatible with subject 'user-events'

Compatibility errors:
  - Field 'user_id' was removed (breaking change)
  - Field 'email' is now required (breaking change for existing consumers)

Compatibility Mode

Get and set compatibility

danube-admin schemas get-compatibility user-events
danube-admin schemas set-compatibility user-events --mode backward

Mode	Description	Allows
none	No checks	Any changes
backward	New schema reads old data (default)	Add optional fields, remove fields
forward	Old schema reads new data	Remove optional fields, add fields
full	Both backward and forward	Add/remove optional fields only

Delete Version

danube-admin schemas delete user-events --version 1 --confirm

Caution

Cannot delete a version currently used by topics. Deletion is permanent. Requires the --confirm flag.

Schema Evolution Workflow

Safe schema update

# 1. Check current schema and compatibility mode
danube-admin schemas get --subject user-events
danube-admin schemas get-compatibility user-events

# 2. Check compatibility of new version
danube-admin schemas check user-events \
  --file schemas/user-events-v2.json \
  --schema-type json_schema

# 3. Register if compatible
danube-admin schemas register user-events \
  --schema-type json_schema \
  --file schemas/user-events-v2.json \
  --description "Added email field"

# 4. Verify
danube-admin schemas versions user-events

---

Security

Security CLI commands (tokens, roles, bindings) are documented in the Securing a Cluster guide. See also:

• Authentication (JWT): token creation and validation details
• Authorization (RBAC): roles, permissions, and binding model