Skip to main content
StreamNative Ursa supports dynamic configuration at the cluster, namespace, and topic levels. This guide explains the supported configuration keys, the cluster-name prefix requirement, and how to apply them with pulsar-admin.

​
Configuration Key Format

All dynamic configuration keys must be prefixed with the cluster name.
ScopeKey formatExample (cluster name private-cloud)
Cluster<cluster-name>.cluster.<key>private-cloud.cluster.sdt.enabled
Namespace<cluster-name>.<key>private-cloud.sdt.enabled
Topic<cluster-name>.<key>private-cloud.sdt.enabled

​
Finding the Cluster Name

The cluster name is the value of the clusterName property in the Pulsar broker configuration (conf/broker.conf): 
# conf/broker.conf
clusterName=private-cloud
You can also retrieve it from a running broker pod: 
kubectl exec -n pulsar <broker-pod> -- grep '^clusterName' /pulsar/conf/broker.conf
Use this exact value as the <cluster-name> prefix in all the keys below.

​
Backward Compatibility

For existing clusters that do not use the cluster-name prefix, disable the prefix check by setting the following property in the broker configuration: 
checkClusterName=false

​
Override Priority

Settings at a more specific level override broader settings: 
Topic properties
    ↓ (overrides)
Namespace properties
    ↓ (overrides)
Cluster properties (sn/system)

​
Supported Dynamic Configuration Keys

​
Cluster-Level Keys

Cluster-level keys are applied via the sn/system namespace.
KeyDescription
<cluster-name>.cluster.sdt.enabledEnable External Table (SDT) for the cluster
<cluster-name>.cluster.sbt.enabledEnable Internal Table (SBT) — Coming Soon
<cluster-name>.cluster.sdt.catalog.nameDefault catalog name for SDT
<cluster-name>.cluster.tail.compact.data.visibility.interval.in.secondsData visibility delay (seconds)

​
Namespace-Level and Topic-Level Keys

These keys can be applied at either the namespace or topic level. Topic-level values override namespace-level values.

​
Enablement and Catalog Selection

KeyDescription
<cluster-name>.sdt.enabledEnable SDT for the namespace or topic
<cluster-name>.sbt.enabledEnable SBT — Coming Soon
<cluster-name>.sdt.catalog.nameCatalog name to use for the namespace or topic
<cluster-name>.tail.compact.data.visibility.interval.in.secondsData visibility delay (seconds)
Compaction task publishing is enabled when either sdt.enabled or sbt.enabled is true.

​
Topic-Level Feature Configuration

These keys configure feature behavior for individual topics:
KeyScopeDescription
<cluster-name>.partition.keyTopic onlyJSON-encoded partition specification for Iceberg tables. Setting this at cluster or namespace level has no effect.
<cluster-name>.upsert.mode.enabledCluster / Namespace / TopicEnable upsert mode (true / false)
<cluster-name>.identifier.fieldsTopic onlyComma-separated list of identifier fields used as the primary key. Setting this at cluster or namespace level has no effect.
<cluster-name>.iceberg.write-props.<property>Namespace / TopicIceberg write properties
<cluster-name>.iceberg.table-props.<property>Namespace / TopicIceberg table properties
For the detailed semantics of each feature key, see:

​
Apply Dynamic Configuration

The examples below assume a cluster named private-cloud.

​
Cluster Level

Cluster-level properties are stored in the sn/system namespace. 
bin/pulsar-admin namespaces set-properties \
  -p private-cloud.cluster.sdt.enabled=true \
  sn/system

​
Namespace Level

bin/pulsar-admin namespaces set-properties \
  -p private-cloud.sdt.enabled=true \
  <tenant>/<namespace>

​
Topic Level

bin/pulsar-admin topics update-properties \
  -p private-cloud.sdt.enabled=true \
  persistent://<tenant>/<namespace>/<topic>

​
Apply Multiple Keys at Once

You can specify -p key=value multiple times in a single command: 
bin/pulsar-admin topics update-properties \
  -p private-cloud.sdt.enabled=true \
  -p private-cloud.sdt.catalog.name=polaris-prod \
  -p private-cloud.upsertModeEnabled=true \
  -p private-cloud.identifierFields=userId,email \
  persistent://public/default/users

​
Extending Valid Dynamic Configuration Keys

By default, only the keys listed above are accepted. To add additional keys, set the following environment variable when starting the Pulsar broker: 
LAKEHOUSE_DYNAMIC_EXTRA_VALID_KEYS_IN_CONF_FILE=<key1>,<key2>,<key3>
Example: 
LAKEHOUSE_DYNAMIC_EXTRA_VALID_KEYS_IN_CONF_FILE=clusterSdtEnabled,clusterSbtEnabled,clusterSdtCatalogName

​
Next Steps