From 0642095dc458ef0a0277c3bc3ed3ea9c16aaff5d Mon Sep 17 00:00:00 2001
From: Kumar Mallikarjuna <kmallikarjuna@confluent.io>
Date: Tue, 19 Aug 2025 18:09:39 +0530
Subject: [PATCH] [FLINK-37391][docs] Improve documentation for dynamic
 namespace watching configuration

- Add example configuration for enabling dynamic namespace watching
- Clarify that dynamic.namespaces.enabled requires dynamic.config.enabled to be true
---
 docs/content.zh/docs/operations/configuration.md     | 12 ++++++++++++
 .../kubernetes_operator_config_configuration.html    |  2 +-
 .../layouts/shortcodes/generated/system_section.html |  2 +-
 .../config/KubernetesOperatorConfigOptions.java      |  3 ++-
 4 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/content.zh/docs/operations/configuration.md b/docs/content.zh/docs/operations/configuration.md
index 0755a6e11b..8aff224aca 100644
--- a/docs/content.zh/docs/operations/configuration.md
+++ b/docs/content.zh/docs/operations/configuration.md
@@ -86,6 +86,18 @@ Verify whether the config value of `kubernetes.operator.reconcile.interval` is u
 2022-05-28 13:08:30,115 o.a.f.k.o.c.FlinkConfigManager [INFO ] Updating default configuration to {kubernetes.operator.reconcile.interval=PT30S}
 ```
 
+### Example: Enabling Dynamic Namespace Watching
+
+To allow the operator to react to changes in the `watchNamespaces` list dynamically, i.e., without restarting its pod, you must set both of the following in your configuration:
+
+```yaml
+# 1. Enable the global dynamic configuration feature
+kubernetes.operator.dynamic.config.enabled: true
+
+# 2. Enable the specific feature for dynamic namespaces
+kubernetes.operator.dynamic.namespaces.enabled: true
+```
+
 ## Leader Election and High Availability
 
 The operator supports high availability through leader election and standby operator instances. To enable leader election you need to add the following two mandatory operator configuration parameters.
diff --git a/docs/layouts/shortcodes/generated/kubernetes_operator_config_configuration.html b/docs/layouts/shortcodes/generated/kubernetes_operator_config_configuration.html
index 2ba0de9ed5..5667d88852 100644
--- a/docs/layouts/shortcodes/generated/kubernetes_operator_config_configuration.html
+++ b/docs/layouts/shortcodes/generated/kubernetes_operator_config_configuration.html
@@ -96,7 +96,7 @@
             <td><h5>kubernetes.operator.dynamic.namespaces.enabled</h5></td>
             <td style="word-wrap: break-word;">false</td>
             <td>Boolean</td>
-            <td>Enables dynamic change of watched/monitored namespaces.</td>
+            <td>Enables the operator to dynamically update the list of namespaces it watches. Requires dynamic.config.enabled to be set to true.</td>
         </tr>
         <tr>
             <td><h5>kubernetes.operator.events.exceptions.limit-per-reconciliation</h5></td>
diff --git a/docs/layouts/shortcodes/generated/system_section.html b/docs/layouts/shortcodes/generated/system_section.html
index ec30301189..6331b62a0c 100644
--- a/docs/layouts/shortcodes/generated/system_section.html
+++ b/docs/layouts/shortcodes/generated/system_section.html
@@ -12,7 +12,7 @@
             <td><h5>kubernetes.operator.dynamic.namespaces.enabled</h5></td>
             <td style="word-wrap: break-word;">false</td>
             <td>Boolean</td>
-            <td>Enables dynamic change of watched/monitored namespaces.</td>
+            <td>Enables the operator to dynamically update the list of namespaces it watches. Requires dynamic.config.enabled to be set to true.</td>
         </tr>
         <tr>
             <td><h5>kubernetes.operator.exception.field.max.length</h5></td>
diff --git a/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/config/KubernetesOperatorConfigOptions.java b/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/config/KubernetesOperatorConfigOptions.java
index bd5e0a46e8..38108bd168 100644
--- a/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/config/KubernetesOperatorConfigOptions.java
+++ b/flink-kubernetes-operator/src/main/java/org/apache/flink/kubernetes/operator/config/KubernetesOperatorConfigOptions.java
@@ -404,7 +404,8 @@ public static String operatorConfigKey(String key) {
             operatorConfig("dynamic.namespaces.enabled")
                     .booleanType()
                     .defaultValue(false)
-                    .withDescription("Enables dynamic change of watched/monitored namespaces.");
+                    .withDescription(
+                            "Enables the operator to dynamically update the list of namespaces it watches. Requires dynamic.config.enabled to be set to true.");
 
     @Documentation.Section(SECTION_SYSTEM)
     public static final ConfigOption<Duration> OPERATOR_RETRY_INITIAL_INTERVAL =