Skip to content

Commit dca68a9

Browse files
marcduikermarcduiker
authored
Merge branch 'v1.18' into affinity-docs
2 parents 57774e1 + 5a670e0 commit dca68a9

2 files changed

Lines changed: 163 additions & 1 deletion

File tree

‎daprdocs/content/en/reference/components-reference/supported-configuration-stores/kubernetes-configmap-configuration-store.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
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/)

‎daprdocs/data/components/configuration_stores/generic.yaml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,9 @@
77
link: postgresql-configuration-store
88
state: Stable
99
version: v1
10-
since: "1.11"
10+
since: "1.11"
11+
- component: Kubernetes ConfigMap
12+
link: kubernetes-configmap-configuration-store
13+
state: Alpha
14+
version: v1
15+
since: "1.18"

0 commit comments

Comments
 (0)