Ejemplo de ConfigMap en Kubernetes: guía total con casos reales

Головна » Python » Ejemplo de ConfigMap en Kubernetes: guía total con casos reales

Якщо ви працюєте з Kubernetes y necesitas separar la configuración del código, los ConfigMaps son tu mejor aliado. Permiten inyectar pares clave-valor no sensibles en tus Pods sin hornear esa configuración dentro de la imagen, lo que facilita despliegues limpios, portables y fáciles de mantener.

Además de lo básico, hay matices importantes: límites de tamaño, actualización automatica al montarlos como volumen, cómo afectan los cambios a variables de entorno, buenas practicas de seguridad y hasta estrategias de observabilidad. Este recorrido practico ya fondo reúne todo lo que necesitas para dominar los ConfigMaps sin dejarte nada en el tintero.

Qué es un ConfigMap y por qué usarlo

ConfigMap — це об’єкт API Kubernetes, призначений для зберігання конфіденційних даних конфігурації в розділі clave-valor. Su objetivo es desacoplar la configuración específica del entorno de las imágenes de contenedor, evitando que tengas que reconstruirlas cada vez que cambie un parametro.

Los Pods може використовувати ConfigMaps як змінні для входу, аргументи порядку, монтовані файли та об’єми або напрямні файли через API. Este diseño encaja con el factor config de las 12-Factor Apps y mejora la portabilidad entre desarrollo, pruebas y producción.

Уявіть, що ваша програма використовує змінну DATABASE_HOST. En local apuntas a localhost, y en la nube usas el nombre de un Service que expone la base de datos. Con un ConfigMap puedes alternar esos valores sin tocar la imagen ni el binario, depurando el mismo código en cualquier entorno.

Є ключове обмеження: un ConfigMap не має значення 1 MiB. Якщо потрібно більше, розділіть конфігурацію на різні ConfigMaps або використовуйте зовнішню службу, об’єм або базу даних конфігурації.

Objeto ConfigMap: валідні поля, номери та розділи

A diferencia de la mayoría de objetos con campo spec, ConfigMap визначає вміст даних і бінарні дані. текстові дані в кодуванні UTF‑8; binaryData містить бінарну кодифікацію на базі 64, ідеально підходить для форматів без UTF‑8.

У назві ConfigMap є дійсне піддомініо DNS, яке містить дані про двійкові дані або двійкові дані. Las claves de data no pueden solaparse con las de binaryData, así que organizalas con criterio para evitar conflictos.

У Kubernetes v1.19 створюється незмінні ConfigMaps, які не змінюються: true. La inmutabilidad, estable desde v1.21, evita cambios incidentales y reduce carga en el API server cerrando los watches, a costa de que, si necesitas cambiar algo, tendrás que borrar y recrear el objeto.

ConfigMaps y Pods: cuatro formas de consumo

Щоб використовувати ConfigMap, ви можете створити простір імен mismo. Hay cuatro maneras principales de consumirlos según lo que necesite tu aplicación.

1. Передайте значення команди й аргументи контендера, посилання на дані ConfigMap. Útil para binarios que leen configuración solo por argumentos.
2. Exponer pares clave-valor como variables de entorno dentro del contenedor. La opción más común para apps que leen del entorno.
3. Змонтуйте ConfigMap як файли в окремому обсязі лекції. Perfecto para aplicaciones que esperan archivos de configuración.
4. Ознайомтеся з ConfigMap від API з власним кодом. Дозвольте підписатися на cambios y reaccionar en caliente, включно з іншими просторами імен, якщо ви використовуєте API.

Cuando se usa como volume, Kubernetes crea archivos por clave. Si визначає елементи в обсязі, puedes seleccionar y renombrar claves concretas; si no, se proyectan todas. También puedes elegir rutas específicas y permisos POSIX para cada fichero.

Actualización de ConfigMaps montados y variables de entorno

Детальна критика: cuando montas un ConfigMap en un volumen, los cambios se propagan Automaticamente con un pequeño retraso. El kubelet comprueba el contenido en cada sincronización y se apoya en una caché local.

Цей компонент залежить від configMapAndSecretChangeDetectionStrategy, який може спостерігати, базуючись на TTL або прямому сервері API. El tardo total será la suma del periodo de sync del kubelet más la propagación de caché; por defecto, 1 хвилина синхронізації та 1 хвилина TTL pueden suponer hasta 2 minutes de latencia.

Замість цього las variables de entorno derivadas de ConfigMaps no se actualizan maticamente. Necesitarás reiniciar el Pod o hacer un rollout para que el processo recoja los nuevos valores. Un truco común para forzar una recarga en Deployments es modificar una anotación del Pod Template, provocando un nuevo ReplicaSet.

Створити ConfigMaps за допомогою kubectl

Ви можете створити configmap kubectl, або середні генератори Kustomize та kustomization.yaml. kubectl admite varias fuentes: directorios, ficheros individuales, literales y env‑files.

З директорії

kubectl empaqueta todos los ficheros regulares con nombre válido del directorio, usando el nombre de cada archivo como clave y su contenido como valor. Entradas que no son ficheros regulares se ignoran como subdirectorios o enlaces simbólicos.

kubectl create configmap game-config --from-file=configure-pod-container/configmap/

Опис версії ConfigMap, наприклад, даних game.properties і ui.properties з оригінальним текстом. Es la forma más cómoda de llevar ficheros de configuración tal cual al cúmoda.

З бетонних стяжок

También puedes pasar varios – from-file repetidos para combinar fuentes. Por defecto la clave es el nombre base del archivo, aunque puedes asignar una clave distinta.

kubectl create configmap game-config-2 
  --from-file=configure-pod-container/configmap/game.properties 
  --from-file=configure-pod-container/configmap/ui.properties

Якщо потрібно визначити іншу клаву для фічера, використовуйте форму клава=шлях. Esto es útil cuando varios archivos comparten nombres o quieres darles nombres más expresivos.

kubectl create configmap game-config-3 
  --from-file=game-special-key=configure-pod-container/configmap/game.properties

Від буквальних цінностей

Con –from-literal визначає pares clave-valor en línea, repitiendo la opción las veces necesarias. Ideal para ajustes rápidos o un puñado de propiedades.

kubectl create configmap special-config 
  --from-literal=special.type=charm 
  --from-literal=special.how=very

Файли env Desde

–from-env-file створює розділ для архіву змінних, що входять до типу .env. Desde v1.23 puedes especificar varias veces –from-env-file for combinar fuentes.

kubectl create configmap my-config --from-env-file=app.env --from-env-file=extra.env

Створити ConfigMaps з налаштуванням

Customize дозволяє оголосити створювані файли kustomization.yaml для створення ConfigMaps файлів або літер. El generado nombre incluye un sufijo hash del contenido para garantizar un nuevo objeto al cambiar los datos.

configMapGenerator:
- name: game-config-4
  files:
  - configure-pod-container/configmap/game.properties

También es posible fijar la clave distinta al nombre del fichero. Esta técnica facilita despliegues declarativos y evita problemas de caché de configuración.

configMapGenerator:
- name: game-config-5
  files:
  - game-special-key=configure-pod-container/configmap/game.properties

Використовуйте ConfigMaps як змінні для входу

Tienes dos patrones principales. Con envFrom importas todas las claves del ConfigMap como variables del contenedor. Rápido y cómodo cuando la aplicación espera muchas variables.

envFrom:
- configMapRef:
    name: my-config

Якщо ви самі запитуєте алгунас-клави або змінюєте значення, використовуйте env y valueFrom.configMapKeyRef. Así eliges claves puntuales y el nombre de la variable puede ser diferente.

env:
- name: CONFIGMAP_USERNAME
  valueFrom:
    configMapKeyRef:
      name: my-config
      key: username

Ojo: los nombres de variables de entorno admiten un conjunto restringido de caracteres. Якщо один розділ ConfigMap не є дійсним для змінної env, опустіть його та зареєструйте подію типу InvalidEnvironmentVariableNames, так само й підготувати Pod.

Montar ConfigMaps як файли

Para exponer datos como archivos, añade el volumen en spec.volumes con configMap.name y monta ese volume con volumeMounts en cada contenedor que lo necesite. Цей розділ проектується як архів mountPath.

volumes:
- name: config-volume
  configMap:
    name: special-config

containers:
- name: app
  image: my-image
  volumeMounts:
  - name: config-volume
    mountPath: /etc/config
    readOnly: true

Puedes mapear claves a rutas y nombres exactos usando items y path, o montar una sola clave con subPath. También se pueden ajustar permisos de archivo con defaultMode або por clave.

volumes:
- name: config-volume
  configMap:
    name: special-config
    items:
    - key: SPECIAL_LEVEL
      path: keys

Важлива примітка: si en la imagen ya existen ficheros bajo el directorio de montaje, quedarán ocultos por el volumen. Tenlo en cuenta para no perder archivos necesarios en tiempo de ejecución.

Текст викладено в UTF‑8; для інших кодифікацій або двійкових файлів, usa binaryData. Актуалізуйте ConfigMap, оновлюйте вміст проекту з затримкою до згадування. Puedes acelerar la actualización cambiando una anotación del Pod para forzar relectura.

Referencias opcionales, namespaces y restrictiones

Посилання на ConfigMap можна позначити як необов’язкове. Si el ConfigMap не існує, el volumen se montará vacío y la variable de entorno no tendrá valor; si la clave concreta no existe, la ruta o la variable estarán ausentes.

Правила запису: debe existir el ConfigMap antes de referenciarlo salvo que lo marques como opcional, y tanto Pod como ConfigMap deben estar en el mismo namespace. Los ConfigMaps не сумісні зі статичними модулями, призначеними безпосередньо для kubelet.

Незмінні ConfigMaps

La funcionalidad de ConfigMaps inmutables porta dos ventajas claras en clústeres con muchos montajes: protege frente a cambios indeseados que causen caídas y reduce carga del API server al cerrar watches. Una vez immutable es true, no supported data redage ni binaryData; toca borrar y recrear, y normalmente reiniciar los Pods que lo montaban para evitar referencias huérfanas.

Límites, tamaño y almacenamiento interno

Los ConfigMaps зберігається в etcd як джерело об’єктів API. No están cifrados por defecto; quien tenga acceso a etcd oa los backups podrá leer su contenido, por lo que no debes almacenar secretos aquí.

Існує обмежений розмір: повний об’єкт має розмір менше 1 МіБ. Superarlo generará un error de entidad demasiado grande. Si te acercas a ese tehcho, reparte la configuración en varios ConfigMaps or cambia de enfoque a volúmenes o servicios externos.

Comparativa rápida: ConfigMaps, variables de entorno y Secrets

Varias opciones resuelven la configuración. ConfigMaps centralizan datos no sensibles y admiten actualizaciones dinámicas. Змінні de entorno puras también separan configuración, pero exigen redeploy para cambios. Secrets almacenan datos sensibles codificados en base64; no es cifrado real, pero permiten politícas de acceso separadas y mejores controles.

• ConfigMaps: no sensibles, dinámicos, fáciles de montar como archivos o env. No cifrados por defecto.
• Змінні середовища: sencillas, pero poco prácticas si hay muchas y no se actualizan en caliente.
• Секрети: datos sensibles; separan credenciales de la configuración normal, requieren tratamiento specífico.

Належні практики та безпека

Підтримуйте описи версій ConfigMaps у git і usa для суфій версій. Con Kustomize, los hashes de contenido te ayudan a forzar relecturas en despliegues sin trucos adicionales.

Evita introducir secretos en ConfigMaps; usa Secrets і RBAC для обмеженого доступу. Valida la sintaxis con linters y pruebas básicas antes de aplicar para reducir errores de formato o indentación.

Контроль доступу до RBAC. Наприклад, роль сольної лекції para configmaps en un namespace:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: configmap-reader
rules:
- apiGroups: ['']
  resources: ['configmaps']
  verbs: ['get', 'list', 'watch']

Para cambios, kubectl edit es cómodo y aplica en vivo, pero en producción es preferible flujo declarativo con apply y revisión por PR. Якщо ви використовуєте змінні де entorno, planea el rollout al editar el ConfigMap para que los Pods recojan los nuevos valores.

Patrones avanzados y escenarios reales

Кілька елементів: створіть ConfigMaps, особливу для розробників, постановки та виробництва. Así evitas mezclar ajustes y зменшує помилки в версіях промоуверів.

Copiar entre clusteres: al ser manifiestos, puedes moverlos y aplicarlos con kubectl donde lo necesites. Це рухома міграція ДР.

Applicaciones que reaccionan a cambios: якщо залишити ConfigMaps desde la API, підпишіться на подію та реакцію на вуело. Este enfoque permite adaptar comportamiento sin reinicios, aunque implica más complejidad de código.

Despliegues con Deployments: referencia ConfigMaps con vvFrom o volúmenes. Para forzar renovación cuando cambie un ConfigMap consumido como env, añade una anotación checksum or incrementa una etiqueta en el Pod Template, lo que desencadenará un nuevo ReplicaSet.

Detalles finos de volúmenes proyectados

Si el Pod define un volumen desde varios orígenes, usa projected volumes para combinarlos. Las claves mapeadas con items permiten nombres de archivo coherentes con lo que tu app espera. subPath es útil para montar una única clave sin montar el directorio completo.

Recuerda que los montajes de ConfigMap son de solo lectura y que en imagenes con ficheros en la misma ruta quedarán ocultos por el volumen. Planifica ubicaciones de montaje que no pisen artefactos esenciales de la imagen.

Actualización y detección de cambios en detalle

Kubelet вирішує, як виявити стратегію виявлення змін конфігурації MapAndSecretChangeDetectionStrategy. watch es el modo por defecto, TTL mantiene una caché con caducidad y direct consulta siempre al API server. Escoger uno uno utro afecta latencia y carga del control plane.

El refresco efectivo de claves montadas puede tardar hasta el periodo de sync más la propagación de caché. Si necesitas actualización inmediata, modificar una anotación del Pod desencadena una sincronización que fuerza la relectura. Este patrón es frecuente cuando la latencia por defecto no es aceptable.

Restrictiones y comportamiento con errores

Якщо посилання на ConfigMap не існує, це означає, що він не є необов’язковим, але Pod no arrancará. Del mismo modo, referenciar claves que no existen bloqueará el inicio salvo que esas referencias concretas sean opcionales.

Cuando usas envFrom, las claves con nombres incompatibles para variables de entorno se omiten y verás un evento con la list de claves saltadas. Esto evita fallos de arranque pero puede sorprender si esperabas esas variables.

Ejemplos practicos habituales

Створіть опис конфігураційної карти файлів

kubectl create configmap app-config --from-file=.env.local --from-file=.env.remote
kubectl describe configmap app-config

Las claves serán los nombres de los ficheros y sus contenidos, los valores. Inspeccionar el objeto con describe te ayuda a verificar que las claves se han empaquetado como esperabas.

Variables de entorno desde una clave concreta

env:
- name: PORT
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: port

Este patrón mantiene el control fino sobre qué exportas al entorno del processo. Es specialmente útil si el ConfigMap incluye fragmentos multiclave que no queeres exponer íntegros.

Montaje selectivo con items y permisos

volumes:
- name: config-volume
  configMap:
    name: special-config
    items:
    - key: SPECIAL_TYPE
      path: conf/type
      mode: 0640

Proyectar claves en rutas concretas con permisos adecuados зменшують fuga de información y alinea la estructura con la jerarquía esperada por tu aplicación. Usa defaultMode para un valor por defecto y sobreescríbelo por clave cuando lo necesites.

Усунення типових проблем

Змінні під назвами: перегляньте клави в ConfigMap, щоб вони були дійсними, як імена env і envFrom США. Consulta eventos del Pod para ver si se han descartado por nombres inválidos.

Montajes que ocultan archivos: si tras montar el volumen faltan archivos que venían en la imagen, probablemente el mountPoint los ha eclipsado. Mueve el mountPath a tra ruta o pasa a subPath si solo necesitas una clave.

Actualizaciones que no llegan: con variables de entorno necesitarás reinicios o rollouts; con volúmenes, espera la ventana de sync o fuerza una relectura actualizando una anotación. Si quieres cero espera, evalúa la estrategia direct para detección de cambios.

Errores por tamaño: si recibes entidad demasiado grande, divide el ConfigMap or cambia la estrategia de configuración. Recuerda el límite de 1 MiB por objecto.

Безпека: evita secretos en ConfigMaps; Секрети США та додаток RBAC. Considera el cifrado en reposo de etcd si tu plataforma lo soporta y tu política lo exige.

Patrones de organización y mantenimiento

Розділіть ConfigMaps для домініо функціоналу: база даних, API, інтерфейс користувача. Esto reduce el radius de cambios y facilita la rotación de valores concretos.

Documenta propósito, claves y contacto. Aunque kubectl get te list objetos, la documentación viva en el repo ayuda a evitar malentendidos. Incluye ejemplos de consumo con env y con volumenes para cada ConfigMap.

Automatiza validación con linters y tests de humo al aplicar, sobre todo si generas desde fúltiples fuentes. Combina pruebas de sintaxis YAML con checks de presencia de claves ríticas.

Параметр despliegues, уна estrategia robusta es anotar el Pod Template con un checksum del ConfigMap, de forma que cada cambio provoque un rollout. Esto garantiza que los contenedores que usan env reciban los nuevos valores.

La esencia de los ConfigMaps es sencilla, pero su valor real aparece cuando dominas las variantes de consumo, la politica de actualizaciones y el gobierno de cambios. Siguiendo las practicas anteriores, tendrás configuraciones seguras, controladas y listes para escalar.