Qué es un ConfigMap en Kubernetes: guía completa con ejemplos

Uno de los principios fundamentales del diseño de aplicaciones en contenedores es que la imagen del contenedor debe ser independiente del entorno donde se ejecuta.

La misma imagen debe funcionar igual en desarrollo, en staging y en producción. Lo que cambia entre entornos no es el código, sino la configuración: la URL de la base de datos, el nivel de logging, las feature flags o los parámetros de conexión.

ConfigMap es el objeto de Kubernetes diseñado específicamente para resolver ese problema. Almacena la configuración separada del contenedor y permite que los Pods la consuman sin que el código de la aplicación sepa si está en un entorno u otro.

Es uno de los objetos más usados en cualquier clúster de Kubernetes, junto con Deployments, Services y Secrets.

---

Qué es un ConfigMap en Kubernetes

Un ConfigMap es un objeto de la API de Kubernetes que almacena datos de configuración no confidenciales en formato clave-valor. El nombre es explícito: es un mapa de configuración. Un conjunto de pares clave-valor que la aplicación puede leer en tiempo de ejecución.

El propósito central de un ConfigMap es desacoplar la configuración de la imagen del contenedor. Sin ConfigMap, la configuración va dentro del Dockerfile o de la imagen, lo que significa que cualquier cambio de configuración requiere reconstruir la imagen y redesplegar. Con ConfigMap, la imagen es genérica y la configuración se inyecta externamente al arrancar el Pod.

Esto tiene una consecuencia práctica muy directa: el mismo Deployment puede usarse en desarrollo, staging y producción cambiando únicamente el ConfigMap que lo alimenta, sin tocar la imagen Docker.

Una restricción importante: un ConfigMap tiene un límite de tamaño de 1 MiB. Si la configuración supera ese límite, se debe dividir en múltiples ConfigMaps o usar un mecanismo externo como un servicio de configuración distribuida.

ConfigMap no cifra sus datos. Para almacenar información sensible como contraseñas, tokens de API o certificados TLS, se usa un Secret, no un ConfigMap. Para entender la arquitectura de contenedores sobre la que opera Kubernetes, el artículo sobre qué es Docker explica los fundamentos de contenedores e imágenes.

Estructura de un ConfigMap en YAML

---

La forma más recomendada de crear ConfigMaps en entornos de producción es mediante archivos YAML declarativos, que se pueden versionar en Git y gestionar como código de infraestructura.

Un ConfigMap básico tiene esta estructura:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  # Variables de entorno simples
  APP_ENV: "production"
  APP_PORT: "8080"
  LOG_LEVEL: "info"
  DATABASE_HOST: "postgres-service.production.svc.cluster.local"
  # Archivo de configuración completo
  app.yaml: |
    server:
      port: 8080
      timeout: 30s
    features:
      login: true
      metrics: true

Los campos principales son:

• apiVersion: v1 — versión de la API de Kubernetes para ConfigMaps.
• kind: ConfigMap — tipo de objeto.
• metadata.name — nombre del ConfigMap. Debe ser único dentro del namespace.
• metadata.namespace — namespace donde vive el ConfigMap. Un Pod solo puede referenciar ConfigMaps del mismo namespace.
• data — los pares clave-valor de configuración. Los valores son texto UTF-8.
• binaryData — para contenido binario codificado en base64 (certificados, fuentes, etc.).

Cómo crear un ConfigMap con kubectl

Además de la forma declarativa con YAML, kubectl permite crear ConfigMaps directamente desde la línea de comandos en tres formas distintas.

Desde literales:

# Una sola clave-valor
kubectl create configmap app-config --from-literal=APP_ENV=production

# Múltiples claves
kubectl create configmap app-config \
  --from-literal=APP_ENV=production \
  --from-literal=APP_PORT=8080 \
  --from-literal=LOG_LEVEL=info

Desde un archivo de configuración:

# El nombre del archivo se convierte en la clave
kubectl create configmap nginx-config --from-file=nginx.conf

# Con nombre de clave personalizado
kubectl create configmap nginx-config --from-file=config=nginx.conf

Desde un directorio:

# Todos los archivos del directorio se añaden como claves
kubectl create configmap app-configs --from-file=./configs/

Aplicar un YAML:

kubectl apply -f configmap.yaml

Para listar los ConfigMaps del clúster y verificar que se han creado correctamente:

# Listar ConfigMaps del namespace actual
kubectl get configmaps

# Ver el contenido completo de un ConfigMap
kubectl describe configmap app-config

# Ver el YAML completo
kubectl get configmap app-config -o yaml

Cómo usar un ConfigMap en un Pod

Hay tres formas de consumir los datos de un ConfigMap en un Pod: como variables de entorno individuales, como todas las claves del ConfigMap de una vez con envFrom, o como archivos montados en un volumen.

Opción 1: Variables de entorno con configMapKeyRef

Inyecta claves específicas del ConfigMap como variables de entorno en el contenedor:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mi-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mi-app
  template:
    metadata:
      labels:
        app: mi-app
    spec:
      containers:
        - name: mi-app
          image: mi-app:latest
          env:
            - name: APP_ENV          # nombre de la variable en el contenedor
              valueFrom:
                configMapKeyRef:
                  name: app-config   # nombre del ConfigMap
                  key: APP_ENV       # clave dentro del ConfigMap
            - name: APP_PORT
              valueFrom:
                configMapKeyRef:
                  name: app-config
                  key: APP_PORT

Opción 2: Todas las claves de una vez con envFrom

Inyecta todas las claves del ConfigMap como variables de entorno, sin tener que listarlas una a una. Es más conciso pero menos explícito:

spec:
  containers:
    - name: mi-app
      image: mi-app:latest
      envFrom:
        - configMapRef:
            name: app-config    # todas las claves del ConfigMap pasan a ser variables de entorno

Con envFrom se puede añadir un prefijo a las variables para evitar colisiones entre varios ConfigMaps:

envFrom:
  - prefix: APP_        # las claves LOG_LEVEL → APP_LOG_LEVEL, PORT → APP_PORT
    configMapRef:
      name: app-config

Opción 3: Montar el ConfigMap como volumen

Monta los datos del ConfigMap como archivos en un directorio del contenedor. Cada clave del ConfigMap se convierte en un archivo cuyo contenido es el valor correspondiente:

spec:
  containers:
    - name: mi-app
      image: mi-app:latest
      volumeMounts:
        - name: config-volume
          mountPath: /etc/config    # directorio donde se montan los archivos
  volumes:
    - name: config-volume
      configMap:
        name: app-config            # cada clave → un archivo en /etc/config/

Para montar solo claves específicas, no todo el ConfigMap:

volumes:
  - name: config-volume
    configMap:
      name: app-config
      items:
        - key: app.yaml              # solo se monta esta clave
          path: application.yaml    # con este nombre de archivo

Actualización automática: volúmenes sí, variables de entorno no

Este es uno de los comportamientos más importantes de los ConfigMaps y el que genera más confusión.

En la práctica, esto significa que si necesitas que los cambios de configuración se apliquen sin downtime, la forma más apropiada es montar el ConfigMap como volumen y diseñar la aplicación para que recargue su configuración al detectar cambios en el archivo.

ConfigMaps inmutables

A partir de Kubernetes 1.21, los ConfigMaps pueden marcarse como inmutables con el campo immutable: true:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config-v2
immutable: true
data:
  APP_ENV: "production"
  APP_PORT: "8080"

Las ventajas de los ConfigMaps inmutables son significativas en clústeres grandes:

• Kubernetes deja de monitorizar cambios en el ConfigMap, reduciendo la carga del API server.
• Protege contra cambios accidentales que podrían afectar a aplicaciones en producción.
• Mejora el rendimiento del clúster en entornos con decenas de miles de ConfigMaps.

La contrapartida: una vez marcado como inmutable, no se pueden modificar los datos. Para actualizar la configuración hay que crear un nuevo ConfigMap con un nombre diferente (por ejemplo, usando versionado: app-config-v2, app-config-v3) y actualizar el Deployment para que lo referencie.

Diferencia entre ConfigMap y Secret

La regla es simple: si el valor es algo que podrías ver en un log sin problema, va en un ConfigMap. Si es algo que no debería aparecer en un log ni en el código fuente, va en un Secret.

Buenas prácticas con ConfigMaps

• Gestiona los ConfigMaps como código. Declara los ConfigMaps en archivos YAML, guárdalos en el repositorio Git junto con el resto de los manifiestos de Kubernetes y aplícalos con kubectl apply o con un sistema de CD como ArgoCD o Flux.
• Usa namespaces para aislar entornos. Un ConfigMap de desarrollo y uno de producción con el mismo nombre en namespaces distintos permiten que el mismo Deployment funcione en ambos entornos sin cambios.
• Versiona los ConfigMaps que no deberían cambiar. Para configuración estable, usa nombres versionados (app-config-v1) y marca el ConfigMap como inmutable. Actualizar la versión es un cambio explícito y controlado.
• No almacenes secretos en ConfigMaps. Aunque sea más cómodo, las contraseñas o tokens en un ConfigMap son visibles para cualquiera con acceso de lectura al namespace.
• Prefiere volúmenes para configuración que puede cambiar. Si la configuración puede actualizarse sin reiniciar los Pods, monta el ConfigMap como volumen. Si la aplicación no necesita recargar configuración en caliente, las variables de entorno son más simples.

ConfigMap en el contexto de un flujo DevOps real

En un flujo de DevOps maduro, los ConfigMaps son parte del pipeline de despliegue. El proceso habitual es:

• Los ConfigMaps de cada entorno viven en directorios separados del repositorio de manifiestos (o en un sistema de gestión de secretos como Vault para los valores sensibles).
• Un sistema de CD como ArgoCD monitoriza el repositorio y aplica los cambios automáticamente al clúster cuando se hace merge en la rama del entorno correspondiente.
• Los Deployments referencian los ConfigMaps por nombre. Si el ConfigMap cambia, ArgoCD detecta la diferencia y hace el rollout del Deployment.

Este patrón, conocido como GitOps, hace que la configuración del clúster sea reproducible, auditable y reversible. Cualquier cambio de configuración queda registrado en el historial de commits.

Para entender cómo se construye la infraestructura de contenedores sobre la que opera Kubernetes, el artículo sobre qué es Docker Compose explica la orquestación de contenedores en el nivel anterior a Kubernetes.

---

Conclusión

---

ConfigMap es uno de los objetos más usados en Kubernetes precisamente porque resuelve un problema fundamental del despliegue de aplicaciones en contenedores: cómo separar la configuración del código para que la misma imagen funcione en cualquier entorno. Bootcamp en DevOps & Cloud Computing Full Stack Bootcamp.

Dominar ConfigMap no es solo saber crear el YAML. Es entender cuándo usar variables de entorno frente a volúmenes montados según si se necesita actualización automática, cuándo marcar un ConfigMap como inmutable para mejorar el rendimiento del clúster, y cómo integrar la gestión de ConfigMaps en un pipeline GitOps reproducible.

La documentación oficial más completa sobre ConfigMaps, con todos los campos disponibles y los patrones de uso avanzados, está en kubernetes.io/es/docs/concepts/configuration/configmap/.