configmap.yml

Descrição: este arquivo cria um ConfigMap no Kubernetes.

Um ConfigMap é usado para armazenar dados de configuração não sensíveis em pares chave/valor, para que Pods e aplicações possam consumir essas informações sem que elas fiquem fixas dentro da imagem do container.

Ele permite separar configuração da imagem da aplicação. Assim, a mesma imagem pode ser usada em desenvolvimento, homologação e produção, mudando apenas o ConfigMap aplicado no namespace.

No arquivo de referência do cluster, o recurso aparece como:

Recurso: configmaps
Tipo: ConfigMap
Versão: v1

TIPO:       ConfigMap
VERSÃO:    v1

DESCRIÇÃO:
    ConfigMap contém dados de configuração para consumo pelos pods.

---

Quando usar ConfigMap

Use ConfigMap quando a aplicação precisa consumir configuração não sensível, como:

• nome do ambiente;
• URL de serviço interno;
• modo de execução;
• nível de log;
• nome de fila;
• porta lógica da aplicação;
• flags de recurso;
• parâmetros de comportamento;
• arquivos de configuração;
• templates de configuração;
• configurações lidas como variáveis de ambiente;
• configurações montadas como arquivos dentro do container;
• argumentos de comando baseados em configuração.

Exemplos comuns:

• AMBIENTE=homologacao;
• LOG_LEVEL=info;
• API_URL=http://backend;
• REDIS_HOST=redis;
• FEATURE_X_ENABLED=true;
• arquivo application.properties;
• arquivo nginx.conf;
• arquivo config.yaml;
• arquivo .env não sensível;
• configuração de aplicação de laboratório;
• parâmetros de sistema acadêmico, administrativo ou de pesquisa.

---

Quando ConfigMap não é o recurso indicado

ConfigMap não é o melhor recurso quando o problema exige outro tipo de controle.

Necessidade	Recurso mais indicado	Motivo
Guardar senha, token ou chave privada	Secret	ConfigMap não foi feito para dados sensíveis.
Executar aplicação	Deployment	ConfigMap apenas armazena configuração.
Criar endereço de rede para Pods	Service	ConfigMap não expõe aplicação.
Publicar por domínio HTTP/HTTPS	Ingress	ConfigMap não faz roteamento de entrada.
Persistir dados da aplicação	PersistentVolumeClaim	ConfigMap não é volume persistente de dados.
Controlar CPU/memória	ResourceQuota, LimitRange ou resources	ConfigMap não controla recursos computacionais.
Isolar rede entre aplicações	NetworkPolicy	ConfigMap não controla tráfego.
Rodar tarefa pontual	Job	ConfigMap não executa tarefas.
Rodar tarefa agendada	CronJob	ConfigMap não agenda execução.
Configuração muito grande	Arquivo externo, volume persistente ou solução própria	ConfigMap tem limite de tamanho e não deve virar repositório de arquivos grandes.
Configuração que precisa de criptografia forte	Secret ou ferramenta externa de segredo	ConfigMap não fornece sigilo.

---

Uso em cenário de universidade

Em uma universidade, um ConfigMap pode ser usado para padronizar configurações de aplicações acadêmicas, administrativas, laboratoriais e de pesquisa sem rebuildar imagens de container para cada ambiente.

Exemplos:

• definir AMBIENTE=homologacao para sistema em teste;
• definir URL interna de API usada por um frontend;
• configurar nível de log de uma aplicação de laboratório;
• montar arquivo de configuração de uma aplicação web;
• separar configuração de desenvolvimento, homologação e produção;
• parametrizar aplicações de disciplinas;
• manter a mesma imagem da aplicação em vários namespaces;
• permitir que equipes alterem configuração sem alterar o Dockerfile;
• organizar configurações por projeto, sistema, laboratório ou ambiente.

Uso recomendado em ambiente universitário:

• um Namespace por projeto, sistema, disciplina, laboratório ou ambiente;
• um ConfigMap por aplicação ou componente;
• um Deployment consumindo o ConfigMap por env, envFrom ou volume;
• um Secret separado para dados sensíveis;
• nomes claros e padronizados para ConfigMaps;
• GitLab, Argo CD ou outro GitOps/CI para aplicar os manifestos;
• evitar colocar senha, token, chave privada ou certificado em ConfigMap;
• versionar mudanças de configuração no repositório quando não forem sensíveis;
• usar immutable: true quando a configuração não deve mudar em runtime.

---

Exemplo completo: configmap.yml

apiVersion: v1
kind: ConfigMap

metadata:
  name: minha-aplicacao-config
  namespace: meu-projeto
  labels:
    app: minha-aplicacao
    ambiente: homologacao
    componente: configuracao
  annotations:
    descricao: "ConfigMap exemplo para configuração não sensível da aplicação"

immutable: false

data:
  AMBIENTE: "homologacao"
  LOG_LEVEL: "info"
  API_URL: "http://minha-api"
  FEATURE_X_ENABLED: "true"

  application.yaml: |
    servidor:
      porta: 8080
    log:
      nivel: info
    recurso:
      habilitado: true

binaryData:
  exemplo.bin: "AAEC"

---

Explicação linha por linha

apiVersion: v1

Define a versão da API usada pelo manifesto.

Para ConfigMap, normalmente é:

apiVersion: v1

Significado:

• v1: versão estável da API core do Kubernetes.

Use exatamente v1 para ConfigMap.

---

kind: ConfigMap

Define o tipo de recurso que será criado.

kind: ConfigMap

Significado:

• ConfigMap: recurso que armazena dados de configuração não sensíveis para consumo por Pods.

Não confundir com:

• Secret: guarda dados sensíveis;
• Deployment: cria e atualiza Pods;
• Service: expõe Pods na rede;
• Ingress: publica Services por HTTP/HTTPS;
• PersistentVolumeClaim: fornece armazenamento persistente.

---

metadata

metadata identifica e organiza o ConfigMap.

metadata:
  name: minha-aplicacao-config
  namespace: meu-projeto
  labels:
    app: minha-aplicacao
  annotations:
    descricao: "ConfigMap exemplo"

metadata.name

Nome do ConfigMap.

name: minha-aplicacao-config

Uso:

• identifica o recurso dentro do namespace;
• aparece em kubectl get configmaps;
• é referenciado por Pods, Deployments e outros recursos;
• deve ser único dentro do namespace.

Exemplos bons:

name: portal-academico-config
name: api-pesquisa-config
name: backend-laboratorio-config

Regras práticas:

• use letras minúsculas;
• use hífen;
• evite acentos;
• evite espaços;
• escolha nome curto e claro;
• use sufixo -config quando ajudar na padronização.

---

metadata.namespace

Namespace onde o ConfigMap será criado.

namespace: meu-projeto

Uso:

• separa configurações por projeto;
• evita mistura entre ambientes;
• permite ter ConfigMaps com o mesmo nome em namespaces diferentes;
• ajuda em RBAC, quotas, isolamento e organização.

Regra importante:

• o Pod ou Deployment que consome o ConfigMap normalmente precisa estar no mesmo namespace do ConfigMap.

Se omitir:

• Kubernetes usa o namespace atual do contexto;
• em produção isso pode causar ConfigMap no namespace errado.

Recomendação:

• sempre declarar namespace.

---

metadata.labels

Labels são pares chave/valor usados para organização e filtros.

labels:
  app: minha-aplicacao
  ambiente: homologacao
  componente: configuracao

Uso:

• filtrar ConfigMaps com kubectl;
• organizar recursos;
• permitir automações;
• associar recursos ao mesmo sistema;
• ajudar ferramentas de observabilidade e GitOps.

Exemplo:

kubectl get configmaps -l app=minha-aplicacao

Boas labels:

app: minha-aplicacao
ambiente: producao
componente: configuracao

Evite usar label com dado sensível.

---

metadata.annotations

Annotations são metadados livres.

annotations:
  descricao: "ConfigMap da aplicação"

Uso:

• documentação;
• configuração de ferramentas;
• automações;
• rastreabilidade;
• integração com GitOps.

Diferença entre labels e annotations:

Campo	Uso
labels	seleção, filtro e organização
annotations	informação extra e configuração de ferramentas

---

Campos de metadata normalmente gerenciados pelo Kubernetes

O kubectl explain mostra vários campos de metadata, mas muitos são preenchidos pelo próprio cluster.

Normalmente você não escreve manualmente:

creationTimestamp:
deletionTimestamp:
resourceVersion:
uid:
generation:
managedFields:
selfLink:

Eles servem para controle interno do Kubernetes.

---

data

data armazena dados de configuração em formato texto.

data:
  AMBIENTE: "homologacao"
  LOG_LEVEL: "info"
  API_URL: "http://minha-api"

Formato:

chave: valor

Uso:

• variáveis de ambiente;
• arquivos de configuração em texto;
• parâmetros simples;
• conteúdo YAML, JSON, properties, conf, ini etc.

Regras importantes:

• chaves devem usar caracteres válidos;
• valores em data são texto;
• dados não UTF-8 devem ficar em binaryData;
• uma chave não pode existir ao mesmo tempo em data e binaryData.

Exemplos de chaves válidas:

data:
  LOG_LEVEL: "info"
  application.yaml: |
    log:
      level: info
  nginx.conf: |
    server {
      listen 80;
    }

---

Chaves simples em data

data:
  AMBIENTE: "homologacao"
  LOG_LEVEL: "info"

Uso:

• consumir como variável de ambiente;
• consumir via envFrom;
• parametrizar aplicação sem rebuild da imagem.

Exemplo de consumo no Deployment:

envFrom:
  - configMapRef:
      name: minha-aplicacao-config

---

Arquivos em data

Uma chave do ConfigMap pode representar um arquivo.

data:
  application.yaml: |
    servidor:
      porta: 8080
    log:
      nivel: info

Quando montado como volume, essa chave vira um arquivo chamado:

application.yaml

Exemplo de montagem:

volumes:
  - name: config
    configMap:
      name: minha-aplicacao-config

containers:
  - name: app
    volumeMounts:
      - name: config
        mountPath: /app/config

Resultado dentro do container:

/app/config/application.yaml

---

binaryData

binaryData armazena dados binários.

binaryData:
  exemplo.bin: "AAEC"

Uso:

• conteúdo que não é texto UTF-8;
• pequenos arquivos binários;
• dados que precisam ser representados como bytes.

Regras importantes:

• valores são representados em base64 no manifesto;
• chaves de binaryData não podem repetir chaves de data;
• não use para segredo sensível; para isso use Secret.

Exemplo:

binaryData:
  arquivo.bin: "AAEC"

Cuidado:

• ConfigMap não é recomendado para arquivos grandes;
• ConfigMap não fornece criptografia nem sigilo;
• se o dado é sensível, use Secret.

---

immutable

Define se o conteúdo do ConfigMap pode ser alterado depois de criado.

immutable: false

Valores:

immutable: true
immutable: false

immutable: false

Permite alterar data e binaryData.

immutable: false

Uso:

• configuração que pode mudar;
• ambiente de desenvolvimento;
• homologação;
• ConfigMaps simples.

Também pode ser omitido quando não houver necessidade de imutabilidade.

---

immutable: true

Impede alteração futura de data e binaryData.

immutable: true

Uso:

• configuração versionada;
• produção;
• evitar mudanças acidentais;
• melhorar previsibilidade do ambiente;
• ConfigMap referenciado por aplicações críticas.

Cuidado:

• depois de marcado como imutável, não é possível voltar para mutável;
• não é possível alterar data ou binaryData;
• para mudar a configuração, crie outro ConfigMap ou delete e recrie o objeto;
• Pods que montam o ConfigMap antigo podem continuar referenciando o conteúdo antigo até serem atualizados/recriados.

---

kind

O campo kind já aparece no topo do manifesto.

kind: ConfigMap

Ele indica que este objeto é um ConfigMap.

---

apiVersion

O campo apiVersion já aparece no topo do manifesto.

apiVersion: v1

Ele indica que este objeto usa a API core v1.

---

Como consumir ConfigMap em um Deployment

Um ConfigMap sozinho não altera uma aplicação.

Ele precisa ser consumido por um Pod, normalmente dentro de um Deployment.

---

Consumo com env

Use env quando quiser escolher chaves específicas.

env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: minha-aplicacao-config
        key: LOG_LEVEL

Uso:

• importar uma chave específica;
• controlar exatamente quais valores entram no container;
• evitar importar variáveis desnecessárias.

---

Consumo com envFrom

Use envFrom quando quiser importar todas as chaves como variáveis de ambiente.

envFrom:
  - configMapRef:
      name: minha-aplicacao-config

Uso:

• muitas variáveis simples;
• configuração no estilo .env;
• aplicações que já leem tudo por ambiente.

Cuidado:

• todas as chaves viram variáveis de ambiente;
• nomes de chaves precisam ser válidos como variáveis de ambiente;
• pode importar mais configuração do que a aplicação precisa.

---

Consumo como volume

Use volume quando a aplicação espera arquivo de configuração.

volumes:
  - name: config
    configMap:
      name: minha-aplicacao-config

containers:
  - name: app
    volumeMounts:
      - name: config
        mountPath: /app/config
        readOnly: true

Uso:

• application.yaml;
• application.properties;
• nginx.conf;
• config.json;
• arquivos de template.

---

Consumo como argumento de comando

ConfigMaps podem ser usados para definir variáveis que depois são usadas em comandos ou argumentos do container.

Exemplo:

env:
  - name: PORTA
    valueFrom:
      configMapKeyRef:
        name: minha-aplicacao-config
        key: PORTA

args:
  - "--porta=$(PORTA)"

Uso:

• aplicação recebe configuração via argumentos;
• imagem de container já suporta flags;
• configuração precisa entrar no processo no momento da inicialização.

---

Observações sobre atualização

Alterar um ConfigMap não significa que toda aplicação consumidora será reiniciada automaticamente.

Quando usado como variável de ambiente

Se o ConfigMap é consumido por env ou envFrom:

• o valor é definido na criação do Pod;
• Pods existentes não recebem automaticamente a nova variável;
• normalmente é necessário reiniciar o Deployment ou recriar os Pods.

Comando comum:

kubectl rollout restart deployment/minha-aplicacao -n meu-projeto

Quando usado como volume

Se o ConfigMap é montado como volume:

• o conteúdo projetado no volume pode ser atualizado pelo kubelet;
• a aplicação precisa ser capaz de reler o arquivo;
• se a aplicação só lê o arquivo na inicialização, pode ser necessário reiniciar o Pod.

Cuidado:

• ConfigMap montado usando subPath não recebe atualizações automáticas do volume projetado.

---

Limite de tamanho

ConfigMap não deve ser usado para dados grandes.

Regra prática:

• use ConfigMap para configuração pequena;
• evite arquivos grandes;
• evite muitos dados acumulados;
• para arquivos grandes, use imagem, volume, PVC, objeto externo ou outra solução adequada.

O limite documentado para ConfigMap é de até 1 MiB.

---

status

ConfigMap não possui uma seção status no manifesto de referência.

Você normalmente trabalha com:

apiVersion
kind
metadata
data
binaryData
immutable

Para ver o objeto aplicado:

kubectl get configmap minha-aplicacao-config -n meu-projeto -o yaml

---

Manifesto mínimo funcional

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
  namespace: meu-projeto
data:
  NOME_AMBIENTE: "homologacao"

Aplicar:

kubectl apply -f configmap.yml

Verificar:

kubectl get configmap nginx-config -n meu-projeto
kubectl describe configmap nginx-config -n meu-projeto

---

Manifesto recomendado para aplicação web simples

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-web-config
  namespace: meu-projeto
  labels:
    app: app-web
    componente: configuracao
data:
  AMBIENTE: "homologacao"
  LOG_LEVEL: "info"
  API_URL: "http://app-web-api"
  FEATURE_X_ENABLED: "false"

Este modelo é adequado para uma aplicação web/API que recebe configuração não sensível por variáveis de ambiente.

---

Manifesto com arquivo de configuração

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-web-config
  namespace: meu-projeto
  labels:
    app: app-web
data:
  application.yaml: |
    servidor:
      porta: 8080
    log:
      nivel: info
    recurso:
      habilitado: false

Uso comum:

• montar o ConfigMap como volume;
• aplicação lê /app/config/application.yaml;
• configuração fica separada da imagem.

---

Manifesto com ConfigMap imutável

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-web-config-v1
  namespace: meu-projeto
  labels:
    app: app-web
immutable: true
data:
  AMBIENTE: "producao"
  LOG_LEVEL: "warn"

Uso:

• configuração versionada;
• produção;
• evitar alteração acidental.

Para mudar:

• crie outro ConfigMap, por exemplo app-web-config-v2;
• atualize o Deployment para usar o novo nome;
• faça rollout da aplicação.

---

Exemplo de Deployment consumindo ConfigMap por envFrom

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-web
  namespace: meu-projeto
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app-web
  template:
    metadata:
      labels:
        app: app-web
    spec:
      containers:
        - name: app
          image: registry.exemplo.local/projeto/app-web:1.0.0
          envFrom:
            - configMapRef:
                name: app-web-config

---

Exemplo de Deployment consumindo ConfigMap como volume

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-web
  namespace: meu-projeto
spec:
  replicas: 1
  selector:
    matchLabels:
      app: app-web
  template:
    metadata:
      labels:
        app: app-web
    spec:
      containers:
        - name: app
          image: registry.exemplo.local/projeto/app-web:1.0.0
          volumeMounts:
            - name: config
              mountPath: /app/config
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: app-web-config

---

Comandos úteis

Aplicar

kubectl apply -f configmap.yml

Ver ConfigMaps

kubectl get configmaps -n meu-projeto

Ver ConfigMap específico

kubectl get configmap minha-aplicacao-config -n meu-projeto

Ver detalhes

kubectl describe configmap minha-aplicacao-config -n meu-projeto

Ver YAML real aplicado

kubectl get configmap minha-aplicacao-config -n meu-projeto -o yaml

Criar ConfigMap por literal

kubectl create configmap minha-aplicacao-config \
  -n meu-projeto \
  --from-literal=AMBIENTE=homologacao \
  --from-literal=LOG_LEVEL=info

Criar ConfigMap a partir de arquivo

kubectl create configmap minha-aplicacao-config \
  -n meu-projeto \
  --from-file=application.yaml

Criar ConfigMap a partir de diretório

kubectl create configmap minha-aplicacao-config \
  -n meu-projeto \
  --from-file=./config/

Editar ConfigMap

kubectl edit configmap minha-aplicacao-config -n meu-projeto

Reiniciar Deployment após mudança em ConfigMap

kubectl rollout restart deployment/minha-aplicacao -n meu-projeto

Ver Pods que usam uma label da aplicação

kubectl get pods -n meu-projeto -l app=minha-aplicacao

---

Relação com outros manifestos

Um ConfigMap normalmente faz parte de um conjunto de manifestos.

Uso típico:

Namespace
  ├── ConfigMap
  ├── Secret
  ├── ServiceAccount
  ├── Deployment
  ├── Service
  ├── Ingress
  ├── NetworkPolicy
  ├── ResourceQuota
  └── LimitRange

ConfigMap + Deployment

ConfigMap fornece configuração.

Deployment consome essa configuração nos Pods.

ConfigMap + Secret

ConfigMap guarda dados não sensíveis.

Secret guarda dados sensíveis.

ConfigMap + Volume

ConfigMap pode ser montado como arquivos dentro do container.

ConfigMap + env/envFrom

ConfigMap pode virar variável de ambiente no container.

ConfigMap + GitOps

ConfigMap pode ser versionado junto dos manifestos da aplicação, quando não contém dados sensíveis.

---

Erros comuns

Colocar senha em ConfigMap

Errado:

data:
  SENHA_BANCO: "senha123"

Correto:

Use Secret para senha, token, chave privada e credencial.

---

Alterar ConfigMap e esperar que env mude em Pods já existentes

Quando o ConfigMap é consumido como variável de ambiente, Pods existentes não recebem automaticamente o novo valor.

Depois de alterar:

kubectl rollout restart deployment/minha-aplicacao -n meu-projeto

---

ConfigMap no namespace errado

Sintoma:

• Deployment referencia ConfigMap;
• Pod não inicia;
• evento mostra ConfigMap não encontrado.

Verificar:

kubectl get configmap -A | grep minha-aplicacao-config
kubectl describe pod -n meu-projeto POD

Correção:

• criar o ConfigMap no mesmo namespace do Deployment/Pod;
• ou corrigir o namespace do manifesto.

---

Chave inexistente

Errado:

env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: LOGLEVEL

Mas no ConfigMap existe:

data:
  LOG_LEVEL: "info"

Correção:

key: LOG_LEVEL

---

Usar binaryData para dado sensível

binaryData não significa segredo.

Errado:

binaryData:
  senha.txt: "..."

Correto:

Use Secret para dados sensíveis.

---

Repetir a mesma chave em data e binaryData

Errado:

data:
  arquivo: "texto"
binaryData:
  arquivo: "AAEC"

A mesma chave não pode existir nos dois campos.

---

ConfigMap grande demais

ConfigMap não é para armazenar arquivos grandes.

Evite:

• arquivos extensos;
• dumps;
• binários grandes;
• conteúdo que deveria estar em imagem, PVC ou storage externo.

---

Usar subPath esperando atualização automática

Quando ConfigMap é montado com subPath, atualizações do ConfigMap não são refletidas automaticamente naquele arquivo montado.

Se precisa atualização dinâmica:

• monte o ConfigMap como volume normal;
• ou reinicie os Pods após alteração.

---

Criar ConfigMap imutável e tentar editar depois

Se immutable: true, não é possível alterar data e binaryData.

Solução:

• criar novo ConfigMap com outro nome;
• atualizar o Deployment;
• fazer rollout;
• remover o ConfigMap antigo quando não estiver mais em uso.

---

Checklist para uso em produção

Antes de aplicar um ConfigMap em ambiente compartilhado:

• namespace definido;
• name claro;
• labels claras;
• contém apenas dados não sensíveis;
• senhas/tokens/chaves foram colocados em Secret, não em ConfigMap;
• chaves têm nomes claros;
• chaves de data não repetem chaves de binaryData;
• valores em data são texto;
• dados binários pequenos usam binaryData;
• ConfigMap não ultrapassa limite de tamanho;
• aplicação sabe consumir a configuração;
• Deployment referencia o ConfigMap correto;
• ConfigMap está no mesmo namespace do Pod/Deployment;
• mudança em ConfigMap tem estratégia de rollout;
• immutable: true foi usado apenas quando faz sentido;
• configuração de produção não depende de edição manual fora do GitOps;
• alteração de configuração foi testada em homologação.

---

Resumo

Use ConfigMap para armazenar configuração não sensível consumida por Pods.

O ConfigMap controla:

• pares chave/valor de configuração;
• arquivos de configuração em texto;
• pequenos dados binários em binaryData;
• imutabilidade opcional com immutable;
• separação entre imagem da aplicação e configuração do ambiente.

Para aplicação web comum, o conjunto mínimo geralmente é:

Namespace + ConfigMap + Deployment + Service + Ingress

Para ambiente institucional compartilhado, o conjunto recomendado é:

Namespace + ResourceQuota + LimitRange + ServiceAccount + Role/RoleBinding
+ ConfigMap + Secret + Deployment + Service + Ingress + NetworkPolicy + PDB