Support hot-reloading of Ditto HOCON configuration via Kubernetes ConfigMap file watching

Adds a DynamicConfigWatcherActor that polls a ConfigMap-mounted file for changes,
merges dynamic config with the static config, and notifies consumers via two patterns:
- EventStream-based DynamicConfigChanged events for singleton/low-count actors
- DynamicConfigPoller utility for high-volume sharded actors (version-polling pattern)

Config values that can now be changed without pod restart include namespace-scoped
activity checks, custom metrics, entity creation restrictions, gateway authentication
(OAuth issuers, DevOps auth, pre-authentication), streaming config, background sync,
persistence cleanup, and WoT ThingModel validation.

Includes Helm chart changes to support a separate dynamic ConfigMap (without checksum
annotation, so updates don't trigger pod restarts) and version-keyed parsed config
caching in DynamicConfigWatcherExtension to minimize memory overhead across 500K+
sharded actor instances.

Closes: #2366

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: thjaeckle

base/service/src/main/java/org/eclipse/ditto/base/service/DittoService.java

@@ -41,6 +41,7 @@
 import org.eclipse.ditto.base.service.config.json.JsonConfig;
 import org.eclipse.ditto.base.service.devops.DevOpsCommandsActor;
 import org.eclipse.ditto.base.service.devops.LogbackLoggingFacade;
+import org.eclipse.ditto.internal.utils.pekko.config.DynamicConfigWatcherExtension;
 import org.eclipse.ditto.internal.utils.config.DefaultScopedConfig;
 import org.eclipse.ditto.internal.utils.config.DittoConfigError;
 import org.eclipse.ditto.internal.utils.config.InstanceIdentifierSupplier;
@@ -271,6 +272,7 @@ private void startPrometheusReporter() {
     private void initializeActorSystem(final ActorSystem actorSystem) {
         startPekkoManagement(actorSystem);
         startClusterBootstrap(actorSystem);
+        DynamicConfigWatcherExtension.get(actorSystem);
 
         startStatusSupplierActor(actorSystem);
         startDevOpsCommandsActor(actorSystem);

connectivity/service/src/main/java/org/eclipse/ditto/connectivity/service/ConnectivityRootActor.java

@@ -129,7 +129,8 @@ private ConnectivityRootActor(final ConnectivityConfig connectivityConfig,
 
 
         final var cleanupConfig = connectivityConfig.getConnectionConfig().getCleanupConfig();
-        final var cleanupActorProps = PersistenceCleanupActor.props(cleanupConfig, mongoReadJournal, CLUSTER_ROLE);
+        final var cleanupActorProps = PersistenceCleanupActor.props(cleanupConfig, mongoReadJournal, CLUSTER_ROLE,
+                "ditto.connectivity.connection.cleanup");
         startChildActor(PersistenceCleanupActor.ACTOR_NAME, cleanupActorProps);
 
         final ActorRef healthCheckingActor = getHealthCheckingActor(connectivityConfig);

deployment/helm/ditto/Chart.yaml

@@ -16,7 +16,7 @@ description: |
   A digital twin is a virtual, cloud based, representation of his real world counterpart
   (real world “Things”, e.g. devices like sensors, smart heating, connected cars, smart grids, EV charging stations etc).
 type: application
-version: 3.8.16  # chart version is effectively set by release-job
+version: 3.8.17  # chart version is effectively set by release-job
 appVersion: 3.8.12
 keywords:
   - iot-chart

deployment/helm/ditto/templates/connectivity-deployment.yaml

@@ -374,6 +374,14 @@ spec:
               value: "{{ .Values.connectivity.config.connections.encryption.migration.batchSize }}"
             - name: CONNECTIVITY_ENCRYPTION_MIGRATION_MAX_DOCS_PER_MINUTE
               value: "{{ .Values.connectivity.config.connections.encryption.migration.maxDocumentsPerMinute }}"
+            {{- if .Values.connectivity.dynamicConfig.enabled }}
+            - name: DITTO_DYNAMIC_CONFIG_ENABLED
+              value: "true"
+            - name: DITTO_DYNAMIC_CONFIG_FILE_PATH
+              value: "{{ .Values.connectivity.dynamicConfig.filePath }}"
+            - name: DITTO_DYNAMIC_CONFIG_POLL_INTERVAL
+              value: "{{ .Values.connectivity.dynamicConfig.pollInterval }}"
+            {{- end }}
             {{- if .Values.connectivity.extraEnv }}
               {{- toYaml .Values.connectivity.extraEnv | nindent 12 }}
             {{- end }}
@@ -447,6 +455,11 @@ spec:
             {{- end }}
             - name: ditto-heap-dumps
               mountPath: /opt/ditto/dumps
+            {{- if .Values.connectivity.dynamicConfig.enabled }}
+            - name: ditto-dynamic-config
+              mountPath: {{ dir .Values.connectivity.dynamicConfig.filePath }}
+              readOnly: true
+            {{- end }}
           resources:
             requests:
               cpu: {{ mulf .Values.connectivity.resources.cpu 1000 }}m
@@ -503,4 +516,9 @@ spec:
         {{- end }}
         - name: ditto-heap-dumps
           emptyDir: {}
+        {{- if .Values.connectivity.dynamicConfig.enabled }}
+        - name: ditto-dynamic-config
+          configMap:
+            name: {{ .Release.Name }}-connectivity-dynamic-config
+        {{- end }}
 {{- end }}

deployment/helm/ditto/templates/dynamic-configmap.yaml

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0
+#
+# SPDX-License-Identifier: EPL-2.0
+{{- $releaseName := .Release.Name -}}
+{{- $name := include "ditto.name" . -}}
+{{- $labels := include "ditto.labels" . -}}
+{{- $namespace := .Release.Namespace -}}
+{{- range $serviceName, $serviceValues := dict "policies" .Values.policies "things" .Values.things "thingsSearch" .Values.thingsSearch "connectivity" .Values.connectivity "gateway" .Values.gateway }}
+{{- if $serviceValues.dynamicConfig.enabled }}
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ $releaseName }}-{{ $serviceName | kebabcase }}-dynamic-config
+  namespace: {{ $namespace }}
+  labels:
+    app.kubernetes.io/name: {{ $name }}-{{ $serviceName | kebabcase }}-dynamic-config
+{{ $labels | indent 4 }}
+data:
+  dynamic.conf: |-
+{{- if $serviceValues.dynamicConfig.content }}
+{{ $serviceValues.dynamicConfig.content | indent 4 }}
+{{- end }}
+{{- end }}
+{{- end }}

deployment/helm/ditto/templates/gateway-deployment.yaml

@@ -279,6 +279,14 @@ spec:
               value: "{{ .Values.gateway.config.wotDirectory.basePrefix }}"
             - name: GATEWAY_WOT_DIRECTORY_AUTHENTICATION_REQUIRED
               value: "{{ .Values.gateway.config.wotDirectory.authenticationRequired }}"
+            {{- if .Values.gateway.dynamicConfig.enabled }}
+            - name: DITTO_DYNAMIC_CONFIG_ENABLED
+              value: "true"
+            - name: DITTO_DYNAMIC_CONFIG_FILE_PATH
+              value: "{{ .Values.gateway.dynamicConfig.filePath }}"
+            - name: DITTO_DYNAMIC_CONFIG_POLL_INTERVAL
+              value: "{{ .Values.gateway.dynamicConfig.pollInterval }}"
+            {{- end }}
             {{- if .Values.gateway.extraEnv }}
               {{- toYaml .Values.gateway.extraEnv | nindent 12 }}
             {{- end }}
@@ -341,6 +349,11 @@ spec:
             {{- end }}
             - name: ditto-heap-dumps
               mountPath: /opt/ditto/dumps
+            {{- if .Values.gateway.dynamicConfig.enabled }}
+            - name: ditto-dynamic-config
+              mountPath: {{ dir .Values.gateway.dynamicConfig.filePath }}
+              readOnly: true
+            {{- end }}
           resources:
             requests:
               cpu: {{ mulf .Values.gateway.resources.cpu 1000 }}m
@@ -397,4 +410,9 @@ spec:
         {{- end }}
         - name: ditto-heap-dumps
           emptyDir: {}
+        {{- if .Values.gateway.dynamicConfig.enabled }}
+        - name: ditto-dynamic-config
+          configMap:
+            name: {{ .Release.Name }}-gateway-dynamic-config
+        {{- end }}
 {{- end }}

deployment/helm/ditto/templates/policies-deployment.yaml

@@ -314,6 +314,14 @@ spec:
               value: "{{ .Values.policies.config.policiesEnforcer.cache.expireAfterWrite }}"
             - name: DITTO_POLICIES_ENFORCER_CACHE_EXPIRE_AFTER_ACCESS
               value: "{{ .Values.policies.config.policiesEnforcer.cache.expireAfterAccess }}"
+            {{- if .Values.policies.dynamicConfig.enabled }}
+            - name: DITTO_DYNAMIC_CONFIG_ENABLED
+              value: "true"
+            - name: DITTO_DYNAMIC_CONFIG_FILE_PATH
+              value: "{{ .Values.policies.dynamicConfig.filePath }}"
+            - name: DITTO_DYNAMIC_CONFIG_POLL_INTERVAL
+              value: "{{ .Values.policies.dynamicConfig.pollInterval }}"
+            {{- end }}
             {{- if .Values.policies.extraEnv }}
               {{- toYaml .Values.policies.extraEnv | nindent 12 }}
             {{- end }}
@@ -390,6 +398,11 @@ spec:
             {{- end }}
             - name: ditto-heap-dumps
               mountPath: /opt/ditto/dumps
+            {{- if .Values.policies.dynamicConfig.enabled }}
+            - name: ditto-dynamic-config
+              mountPath: {{ dir .Values.policies.dynamicConfig.filePath }}
+              readOnly: true
+            {{- end }}
           resources:
             requests:
               cpu: {{ mulf .Values.policies.resources.cpu 1000 }}m
@@ -446,4 +459,9 @@ spec:
         {{- end }}
         - name: ditto-heap-dumps
           emptyDir: {}
+        {{- if .Values.policies.dynamicConfig.enabled }}
+        - name: ditto-dynamic-config
+          configMap:
+            name: {{ .Release.Name }}-policies-dynamic-config
+        {{- end }}
 {{- end }}

deployment/helm/ditto/templates/things-deployment.yaml

@@ -386,6 +386,14 @@ spec:
               value: "{{ index .Values.things.config.wot.tmValidation.feature.forbid "non-modeled-desired-properties" }}"
             - name: THINGS_WOT_TM_MODEL_VALIDATION_FEATURE_FORBID_NON_MODELED_OUTBOX_MESSAGES
               value: "{{ index .Values.things.config.wot.tmValidation.feature.forbid "non-modeled-outbox-messages" }}"
+            {{- if .Values.things.dynamicConfig.enabled }}
+            - name: DITTO_DYNAMIC_CONFIG_ENABLED
+              value: "true"
+            - name: DITTO_DYNAMIC_CONFIG_FILE_PATH
+              value: "{{ .Values.things.dynamicConfig.filePath }}"
+            - name: DITTO_DYNAMIC_CONFIG_POLL_INTERVAL
+              value: "{{ .Values.things.dynamicConfig.pollInterval }}"
+            {{- end }}
             {{- if .Values.things.extraEnv }}
               {{- toYaml .Values.things.extraEnv | nindent 12 }}
             {{- end }}
@@ -459,6 +467,11 @@ spec:
             {{- end }}
             - name: ditto-heap-dumps
               mountPath: /opt/ditto/dumps
+            {{- if .Values.things.dynamicConfig.enabled }}
+            - name: ditto-dynamic-config
+              mountPath: {{ dir .Values.things.dynamicConfig.filePath }}
+              readOnly: true
+            {{- end }}
           resources:
             requests:
               cpu: {{ mulf .Values.things.resources.cpu 1000 }}m
@@ -515,4 +528,9 @@ spec:
         {{- end }}
         - name: ditto-heap-dumps
           emptyDir: {}
+        {{- if .Values.things.dynamicConfig.enabled }}
+        - name: ditto-dynamic-config
+          configMap:
+            name: {{ .Release.Name }}-things-dynamic-config
+        {{- end }}
 {{- end }}

deployment/helm/ditto/templates/thingssearch-deployment.yaml

@@ -286,6 +286,14 @@ spec:
               value: "{{ .Values.thingsSearch.config.updater.backgroundSync.throttle.throughput }}"
             - name: BACKGROUND_SYCN_THROTTLE_PERIOD
               value: "{{ .Values.thingsSearch.config.updater.backgroundSync.throttle.period }}"
+            {{- if .Values.thingsSearch.dynamicConfig.enabled }}
+            - name: DITTO_DYNAMIC_CONFIG_ENABLED
+              value: "true"
+            - name: DITTO_DYNAMIC_CONFIG_FILE_PATH
+              value: "{{ .Values.thingsSearch.dynamicConfig.filePath }}"
+            - name: DITTO_DYNAMIC_CONFIG_POLL_INTERVAL
+              value: "{{ .Values.thingsSearch.dynamicConfig.pollInterval }}"
+            {{- end }}
             {{- if .Values.thingsSearch.extraEnv }}
               {{- toYaml .Values.thingsSearch.extraEnv | nindent 12 }}
             {{- end }}
@@ -359,6 +367,11 @@ spec:
             {{- end }}
             - name: ditto-heap-dumps
               mountPath: /opt/ditto/dumps
+            {{- if .Values.thingsSearch.dynamicConfig.enabled }}
+            - name: ditto-dynamic-config
+              mountPath: {{ dir .Values.thingsSearch.dynamicConfig.filePath }}
+              readOnly: true
+            {{- end }}
           resources:
             requests:
               cpu: {{ mulf .Values.thingsSearch.resources.cpu 1000 }}m
@@ -415,4 +428,9 @@ spec:
         {{- end }}
         - name: ditto-heap-dumps
           emptyDir: {}
+        {{- if .Values.thingsSearch.dynamicConfig.enabled }}
+        - name: ditto-dynamic-config
+          configMap:
+            name: {{ .Release.Name }}-things-search-dynamic-config
+        {{- end }}
 {{- end }}

deployment/helm/ditto/values.yaml

@@ -763,6 +763,24 @@ policies:
     enabled: false
     # interval: 30s
     # scrapeTimeout: 15s
+  # dynamicConfig enables hot-reloading of HOCON configuration from a ConfigMap without pod restart.
+  #  When enabled, a ConfigMap is mounted at the specified file path and polled at the given interval.
+  #  Changes to the ConfigMap are detected and propagated to actors via Pekko EventStream.
+  #  content: |
+  #    ditto {
+  #      policies {
+  #        policy {
+  #          activity-check {
+  #            inactive-interval = 2h
+  #          }
+  #        }
+  #      }
+  #    }
+  dynamicConfig:
+    enabled: false
+    pollInterval: 30s
+    filePath: "/opt/ditto/dynamic-config/dynamic.conf"
+    content: ""
   # config holds policies specific configuration
   config:
     # cluster contains policies specific clustering config
@@ -1102,6 +1120,22 @@ things:
     enabled: false
     # interval: 30s
     # scrapeTimeout: 15s
+  # dynamicConfig enables hot-reloading of HOCON configuration from a ConfigMap without pod restart.
+  #  content: |
+  #    ditto {
+  #      things {
+  #        thing {
+  #          activity-check {
+  #            inactive-interval = 2h
+  #          }
+  #        }
+  #      }
+  #    }
+  dynamicConfig:
+    enabled: false
+    pollInterval: 30s
+    filePath: "/opt/ditto/dynamic-config/dynamic.conf"
+    content: ""
   # config holds things specific configuration
   config:
     # cluster contains things specific clustering config
@@ -1601,6 +1635,22 @@ thingsSearch:
     enabled: false
     # interval: 30s
     # scrapeTimeout: 15s
+  # dynamicConfig enables hot-reloading of HOCON configuration from a ConfigMap without pod restart.
+  #  content: |
+  #    ditto {
+  #      search {
+  #        operator-metrics {
+  #          custom-metrics {
+  #            my_metric { ... }
+  #          }
+  #        }
+  #      }
+  #    }
+  dynamicConfig:
+    enabled: false
+    pollInterval: 30s
+    filePath: "/opt/ditto/dynamic-config/dynamic.conf"
+    content: ""
   # config holds things-search specific configuration
   config:
     # cluster contains things-search specific clustering config
@@ -1941,6 +1991,20 @@ connectivity:
     enabled: false
     # interval: 30s
     # scrapeTimeout: 15s
+  # dynamicConfig enables hot-reloading of HOCON configuration from a ConfigMap without pod restart.
+  #  content: |
+  #    ditto {
+  #      connectivity {
+  #        connection {
+  #          ...
+  #        }
+  #      }
+  #    }
+  dynamicConfig:
+    enabled: false
+    pollInterval: 30s
+    filePath: "/opt/ditto/dynamic-config/dynamic.conf"
+    content: ""
   # config holds connectivity specific configuration
   config:
     # cluster contains connectivity specific clustering config
@@ -2368,6 +2432,20 @@ gateway:
     enabled: false
     # interval: 30s
     # scrapeTimeout: 15s
+  # dynamicConfig enables hot-reloading of HOCON configuration from a ConfigMap without pod restart.
+  #  content: |
+  #    ditto {
+  #      gateway {
+  #        streaming {
+  #          ...
+  #        }
+  #      }
+  #    }
+  dynamicConfig:
+    enabled: false
+    pollInterval: 30s
+    filePath: "/opt/ditto/dynamic-config/dynamic.conf"
+    content: ""
   # config holds gateway specific configuration
   config:
     # cluster contains gateway specific clustering config