|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "Kubernetes ConfigMap" |
| 4 | +linkTitle: "Kubernetes ConfigMap" |
| 5 | +description: Detailed information on the Kubernetes ConfigMap configuration store component |
| 6 | +--- |
| 7 | + |
| 8 | +## Component format |
| 9 | + |
| 10 | +To set up a Kubernetes ConfigMap configuration store, create a component of type `configuration.kubernetes`. See [this guide]({{% ref "howto-manage-configuration.md#configure-a-dapr-configuration-store" %}}) on how to create and apply a configuration store configuration. |
| 11 | + |
| 12 | +```yaml |
| 13 | +apiVersion: dapr.io/v1alpha1 |
| 14 | +kind: Component |
| 15 | +metadata: |
| 16 | + name: <NAME> |
| 17 | +spec: |
| 18 | + type: configuration.kubernetes |
| 19 | + version: v1 |
| 20 | + metadata: |
| 21 | + - name: configMapName |
| 22 | + value: "<CONFIGMAP_NAME>" |
| 23 | + # Optional: path to kubeconfig (only needed when running outside the cluster) |
| 24 | + #- name: kubeconfigPath |
| 25 | + # value: "/path/to/kubeconfig" |
| 26 | + # Optional: informer resync period |
| 27 | + #- name: resyncPeriod |
| 28 | + # value: "0" |
| 29 | +``` |
| 30 | + |
| 31 | +## Spec metadata fields |
| 32 | + |
| 33 | +| Field | Required | Details | Example | |
| 34 | +|-------|:--------:|---------|---------| |
| 35 | +| `configMapName` | Y | The name of the Kubernetes ConfigMap to use as the configuration source. Must be a valid [RFC 1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names) DNS label name. | `"my-app-config"` | |
| 36 | +| `kubeconfigPath` | N | Path to a kubeconfig file. When running inside a Kubernetes cluster (the typical case), this is not needed. When running outside the cluster, it falls back to the `KUBECONFIG` environment variable, then to `~/.kube/config`. | `"/path/to/kubeconfig"` | |
| 37 | +| `resyncPeriod` | N | How often the informer fully re-syncs the ConfigMap state from the API server as a consistency safety net, independent of watch events. Set to `"0"` (default) to disable periodic resync and rely solely on watch events. | `"10m"` | |
| 38 | + |
| 39 | +## Set up a Kubernetes ConfigMap as Configuration Store |
| 40 | + |
| 41 | +The Kubernetes ConfigMap configuration store requires no external infrastructure beyond the Kubernetes cluster itself. |
| 42 | + |
| 43 | +### Prerequisites |
| 44 | + |
| 45 | +- A running Kubernetes cluster |
| 46 | +- The Dapr sidecar must have RBAC permissions to `get`, `list`, and `watch` ConfigMaps in the target namespace |
| 47 | + |
| 48 | +### 1. Create the ConfigMap |
| 49 | + |
| 50 | +Create a ConfigMap that holds your configuration data: |
| 51 | + |
| 52 | +```bash |
| 53 | +kubectl create configmap my-app-config \ |
| 54 | + --from-literal=log.level=info \ |
| 55 | + --from-literal=feature.enable-v2=true \ |
| 56 | + --from-literal=database.pool-size=10 |
| 57 | +``` |
| 58 | + |
| 59 | +Or using a YAML manifest: |
| 60 | + |
| 61 | +```yaml |
| 62 | +apiVersion: v1 |
| 63 | +kind: ConfigMap |
| 64 | +metadata: |
| 65 | + name: my-app-config |
| 66 | + namespace: default |
| 67 | +data: |
| 68 | + log.level: "info" |
| 69 | + feature.enable-v2: "true" |
| 70 | + database.pool-size: "10" |
| 71 | +``` |
| 72 | +
|
| 73 | +### 2. Configure RBAC |
| 74 | +
|
| 75 | +The Dapr sidecar's service account needs permission to access ConfigMaps. Create a Role and RoleBinding: |
| 76 | +
|
| 77 | +```yaml |
| 78 | +apiVersion: rbac.authorization.k8s.io/v1 |
| 79 | +kind: Role |
| 80 | +metadata: |
| 81 | + name: dapr-configmap-reader |
| 82 | + namespace: default |
| 83 | +rules: |
| 84 | +- apiGroups: [""] |
| 85 | + resources: ["configmaps"] |
| 86 | + verbs: ["get", "list", "watch"] |
| 87 | +--- |
| 88 | +apiVersion: rbac.authorization.k8s.io/v1 |
| 89 | +kind: RoleBinding |
| 90 | +metadata: |
| 91 | + name: dapr-configmap-reader-binding |
| 92 | + namespace: default |
| 93 | +subjects: |
| 94 | +- kind: ServiceAccount |
| 95 | + name: default |
| 96 | + namespace: default |
| 97 | +roleRef: |
| 98 | + kind: Role |
| 99 | + name: dapr-configmap-reader |
| 100 | + apiGroup: rbac.authorization.k8s.io |
| 101 | +``` |
| 102 | +
|
| 103 | +{{% alert title="Note" color="primary" %}} |
| 104 | +If you installed Dapr using the Helm chart with default settings, the Dapr sidecar service account may already have sufficient permissions. Verify your cluster's RBAC configuration. |
| 105 | +{{% /alert %}} |
| 106 | +
|
| 107 | +### 3. Apply the component |
| 108 | +
|
| 109 | +Apply the Dapr component configuration: |
| 110 | +
|
| 111 | +```yaml |
| 112 | +apiVersion: dapr.io/v1alpha1 |
| 113 | +kind: Component |
| 114 | +metadata: |
| 115 | + name: myconfigstore |
| 116 | +spec: |
| 117 | + type: configuration.kubernetes |
| 118 | + version: v1 |
| 119 | + metadata: |
| 120 | + - name: configMapName |
| 121 | + value: "my-app-config" |
| 122 | +``` |
| 123 | +
|
| 124 | +## How it works |
| 125 | +
|
| 126 | +### Data model |
| 127 | +
|
| 128 | +Each key in the ConfigMap's `data` field becomes a configuration item. The ConfigMap's `resourceVersion` (assigned by Kubernetes) is used as the version for all items. |
| 129 | + |
| 130 | +Keys in the `binaryData` field are also supported. Their values are returned as base64-encoded strings with `"encoding": "base64"` in the item metadata. |
| 131 | +
|
| 132 | +### Subscriptions |
| 133 | +
|
| 134 | +When you subscribe to configuration changes, the component uses a [Kubernetes SharedIndexInformer](https://pkg.go.dev/k8s.io/client-go/tools/cache#SharedIndexInformer) with a field selector scoped to the specific ConfigMap. This means: |
| 135 | +
|
| 136 | +- Only changes to the watched ConfigMap generate API traffic |
| 137 | +- Changes are detected in near real-time via the Kubernetes watch API |
| 138 | +- Only changed keys are included in update notifications |
| 139 | +
|
| 140 | +When a key is deleted from the ConfigMap, the notification includes `"deleted": "true"` in the item's metadata with an empty value. |
| 141 | + |
| 142 | +### Namespace |
| 143 | + |
| 144 | +The component watches ConfigMaps in the same namespace as the Dapr sidecar. The namespace is derived from the `NAMESPACE` environment variable, which is automatically set by the Dapr sidecar injector via the Kubernetes downward API. If the variable is not set, the component defaults to `"default"`. |
| 145 | + |
| 146 | +Cross-namespace ConfigMap access is not supported. This is by design to maintain Kubernetes namespace security boundaries. |
| 147 | + |
| 148 | +{{% alert title="Note" color="primary" %}} |
| 149 | +ConfigMaps are not encrypted at rest by default in Kubernetes. Do not store sensitive values (passwords, API keys, tokens) in ConfigMaps. Use [Kubernetes Secrets]({{% ref "kubernetes-secret-store" %}}) or a dedicated secret store instead. |
| 150 | +{{% /alert %}} |
| 151 | + |
| 152 | +## Related links |
| 153 | + |
| 154 | +- [Basic schema for a Dapr component]({{% ref component-schema %}}) |
| 155 | +- [Configuration building block]({{% ref configuration-api-overview %}}) |
| 156 | +- Read [How-To: Manage configuration from a store]({{% ref "howto-manage-configuration" %}}) for instructions on how to use a configuration store. |
| 157 | +- [Kubernetes ConfigMap documentation](https://kubernetes.io/docs/concepts/configuration/configmap/) |
0 commit comments