pod.yml

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

Um Pod é a menor unidade executável comum do Kubernetes. Ele representa um ou mais containers que rodam juntos, compartilham a mesma rede do Pod, podem compartilhar volumes e são agendados em um nó do cluster.

Na prática, normalmente você não cria Pods diretamente para produção. O mais comum é criar Deployment, StatefulSet, DaemonSet, Job ou CronJob, e esses controladores criam e recriam Pods conforme necessário.

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

Recurso: pods
Tipo: Pod
Versão: v1

TIPO:       Pod
VERSÃO:    v1

DESCRIÇÃO:
    Pod é uma coleção de contêineres que podem rodar em um host. Este recurso é criado por
    clientes e agendado em hosts.

Quando usar Pod

Use Pod diretamente quando você precisa:

testar rapidamente uma imagem;
executar um container simples para diagnóstico;
abrir um shell temporário no cluster;
validar conectividade de rede;
testar DNS interno;
testar acesso a Service;
testar montagem de ConfigMap;
testar montagem de Secret;
testar uma configuração antes de colocá-la em Deployment;
entender como o Kubernetes agenda e executa containers;
criar exemplos didáticos;
criar workloads muito simples e temporários.

Exemplos comuns:

Pod temporário com busybox;
Pod temporário com curl;
Pod de teste com nginx;
Pod para validar DNS;
Pod para validar acesso ao banco;
Pod para testar Secret;
Pod para testar ConfigMap;
Pod para debug de rede.

Quando Pod não é o recurso indicado

Pod não é o melhor recurso quando o problema exige controle, recriação automática ou gestão de ciclo de vida.

Necessidade	Recurso mais indicado	Motivo
Aplicação web contínua	`Deployment`	Deployment recria Pods, controla réplicas e faz rollout.
API ou backend sem estado	`Deployment`	Deployment é o padrão para aplicação contínua sem estado.
Banco de dados com identidade fixa	`StatefulSet`	StatefulSet dá identidade e volume estável por réplica.
Agente em todos os nós	`DaemonSet`	DaemonSet garante Pod por nó ou por grupo de nós.
Tarefa pontual que termina	`Job`	Job acompanha conclusão da tarefa.
Tarefa agendada	`CronJob`	CronJob executa tarefas em horários definidos.
Publicar Pods na rede interna	`Service`	Service cria ponto de acesso estável.
Publicar por domínio HTTP/HTTPS	`Ingress`	Ingress publica Service por hostname e path.
Guardar configuração	`ConfigMap`	Pod apenas consome ConfigMap.
Guardar senha/token	`Secret`	Pod apenas consome Secret.
Persistir dados	`PersistentVolumeClaim`	Pod apenas monta PVC.
Isolar tráfego	`NetworkPolicy`	Pod não define política de rede por si só.
Controlar limites por namespace	`ResourceQuota` e `LimitRange`	Pod pode declarar resources, mas não limita o namespace inteiro.

Uso em cenário de universidade

Em uma universidade, um Pod pode ser usado diretamente para ensino, teste, diagnóstico e validação de infraestrutura.

Exemplos:

aula prática mostrando como containers rodam no Kubernetes;
teste de conectividade entre namespaces;
validação de DNS interno;
teste de acesso a Service;
teste de leitura de ConfigMap;
teste de leitura de Secret;
diagnóstico de aplicação em laboratório;
simulação de falha de container;
validação de permissões de ServiceAccount;
teste temporário de imagem produzida por CI/CD.

Uso recomendado em ambiente universitário:

usar Pod direto para aprendizado, laboratório, diagnóstico e teste curto;
usar Deployment para aplicações web/API contínuas;
usar Job para tarefas que terminam;
usar CronJob para tarefas agendadas;
usar StatefulSet para aplicações com identidade persistente;
usar DaemonSet para agentes de nó;
sempre definir namespace;
usar resources.requests e resources.limits;
evitar hostNetwork, hostPID, hostIPC e privileged salvo necessidade real;
evitar rodar containers como root quando possível;
usar ServiceAccount com menor privilégio;
usar ConfigMap para configuração não sensível;
usar Secret para credenciais;
usar Service se o Pod precisar ser acessado por outros Pods.

Exemplo completo: pod.yml

apiVersion: v1
kind: Pod

metadata:
  name: minha-aplicacao
  namespace: meu-projeto
  labels:
    app: minha-aplicacao
    ambiente: homologacao
    componente: backend
  annotations:
    descricao: "Pod exemplo para aplicação web"

spec:
  serviceAccountName: minha-aplicacao
  automountServiceAccountToken: false

  restartPolicy: Always
  terminationGracePeriodSeconds: 30
  dnsPolicy: ClusterFirst
  enableServiceLinks: true

  imagePullSecrets:
    - name: registry-credencial

  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault

  initContainers:
    - name: preparar-ambiente
      image: busybox:1.36
      command:
        - sh
        - -c
      args:
        - "echo preparando ambiente && sleep 5"

  containers:
    - name: app
      image: registry.exemplo.local/projeto/minha-aplicacao:1.0.0
      imagePullPolicy: IfNotPresent

      command:
        - "/app/bin/start"
      args:
        - "--porta=8080"

      workingDir: /app

      ports:
        - name: http
          containerPort: 8080
          protocol: TCP

      env:
        - name: AMBIENTE
          value: "homologacao"
        - name: LOG_LEVEL
          value: "info"
        - name: SENHA_BANCO
          valueFrom:
            secretKeyRef:
              name: minha-aplicacao-secret
              key: SENHA_BANCO

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

      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "512Mi"

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

      readinessProbe:
        httpGet:
          path: /ready
          port: http
        initialDelaySeconds: 10
        periodSeconds: 10
        timeoutSeconds: 2
        failureThreshold: 3
        successThreshold: 1

      livenessProbe:
        httpGet:
          path: /health
          port: http
        initialDelaySeconds: 30
        periodSeconds: 20
        timeoutSeconds: 2
        failureThreshold: 3

      startupProbe:
        httpGet:
          path: /startup
          port: http
        periodSeconds: 5
        failureThreshold: 30

      lifecycle:
        preStop:
          exec:
            command:
              - sh
              - -c
              - "sleep 10"

      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: false
        capabilities:
          drop:
            - ALL

  volumes:
    - name: config
      configMap:
        name: minha-aplicacao-config
    - name: cache
      emptyDir: {}

  nodeSelector:
    kubernetes.io/os: linux

  tolerations: []

  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchLabels:
                app: minha-aplicacao
            topologyKey: kubernetes.io/hostname

  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: ScheduleAnyway
      labelSelector:
        matchLabels:
          app: minha-aplicacao

Explicação linha por linha

`apiVersion: v1`

Define a versão da API usada pelo manifesto.

Para Pod, normalmente é:

apiVersion: v1

Significado:

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

Use exatamente v1 para Pod.

`kind: Pod`

Define o tipo de recurso que será criado.

kind: Pod

Significado:

Pod: unidade que executa um ou mais containers no Kubernetes.

Não confundir com:

Deployment: gerencia Pods e ReplicaSets;
StatefulSet: gerencia Pods com identidade estável;
DaemonSet: cria Pods em nós;
Job: cria Pods para tarefa que termina;
Service: expõe Pods na rede;
Ingress: publica Services por HTTP/HTTPS.

`metadata`

metadata identifica e organiza o Pod.

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

`metadata.name`

Nome do Pod.

name: minha-aplicacao

Uso:

identifica o Pod dentro do namespace;
aparece em kubectl get pods;
deve ser único dentro do namespace.

Exemplos bons:

name: teste-curl
name: debug-dns
name: nginx-exemplo
name: minha-aplicacao

Cuidado:

em produção, Pods criados por Deployment recebem nomes gerados automaticamente;
evite depender do nome fixo de um Pod para aplicação contínua.

`metadata.namespace`

Namespace onde o Pod será criado.

namespace: meu-projeto

Uso:

separa aplicações;
evita mistura entre projetos;
define onde o Pod buscará ConfigMaps, Secrets, ServiceAccounts e PVCs;
ajuda em RBAC, quotas, limites e isolamento.

Recomendação:

sempre declarar namespace.

`metadata.labels`

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

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

Uso:

Service usa labels para encontrar Pods;
NetworkPolicy pode selecionar Pods por labels;
kubectl pode filtrar Pods por labels;
ferramentas de observabilidade e GitOps usam labels.

Exemplo:

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

`metadata.annotations`

Annotations são metadados livres.

annotations:
  descricao: "Pod de exemplo"

Uso:

documentação;
configuração de ferramentas;
observabilidade;
integração com controladores;
metadados que não servem para seleção.

Campos de `metadata` normalmente gerenciados pelo Kubernetes

Normalmente você não escreve manualmente:

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

Eles servem para controle interno do Kubernetes.

`spec`

spec descreve como o Pod deve ser criado e executado.

spec:
  containers:
    - name: app
      image: nginx:1.27

Campo obrigatório principal:

containers

Campos comuns:

serviceAccountName
automountServiceAccountToken
imagePullSecrets
securityContext
initContainers
containers
volumes
restartPolicy
terminationGracePeriodSeconds
dnsPolicy
dnsConfig
nodeSelector
affinity
tolerations
topologySpreadConstraints
priorityClassName
runtimeClassName

`spec.containers`

Lista de containers principais do Pod.

containers:
  - name: app
    image: nginx:1.27

Este campo é obrigatório.

Um Pod pode ter um ou mais containers.

Use múltiplos containers no mesmo Pod quando eles precisam:

compartilhar rede local;
compartilhar volumes;
nascer e morrer juntos;
funcionar como sidecar;
colaborar diretamente na mesma unidade de execução.

Cuidado:

containers no mesmo Pod compartilham destino de agendamento;
escalam juntos;
são reiniciados conforme política do Pod;
se containers não precisam estar juntos, prefira Pods separados.

`containers[].name`

Nome do container.

name: app

Uso:

identificar logs;
referenciar container em comandos;
facilitar debug;
distinguir containers quando há mais de um no Pod.

Exemplo:

kubectl logs pod/minha-aplicacao -c app -n meu-projeto

`containers[].image`

Imagem do container.

image: registry.exemplo.local/projeto/minha-aplicacao:1.0.0

Formato comum:

registry/projeto/imagem:tag

Recomendação:

em produção, evite latest;
use tags versionadas;
quando necessário, use digest para reprodutibilidade.

`containers[].imagePullPolicy`

Define quando a imagem será baixada.

imagePullPolicy: IfNotPresent

Valores:

Valor	Comportamento
`Always`	sempre tenta baixar a imagem
`IfNotPresent`	baixa se não existir no nó
`Never`	nunca baixa, usa apenas imagem local

`containers[].command`

Sobrescreve o comando principal da imagem.

command:
  - "/app/bin/start"

Equivale ao ENTRYPOINT do Docker.

Use quando:

precisa trocar o comando padrão da imagem;
a mesma imagem executa modos diferentes;
está criando Pod de debug ou teste.

`containers[].args`

Argumentos passados ao comando.

args:
  - "--porta=8080"

Equivale ao CMD do Docker.

Exemplo:

command:
  - sh
  - -c
args:
  - "echo teste && sleep 3600"

`containers[].workingDir`

Diretório de trabalho dentro do container.

workingDir: /app

Use quando:

a aplicação espera rodar a partir de um diretório específico;
scripts usam caminhos relativos.

`containers[].ports`

Declara portas expostas pelo container.

ports:
  - name: http
    containerPort: 8080
    protocol: TCP

Campos:

Campo	Função
`name`	nome lógico da porta
`containerPort`	porta dentro do container
`protocol`	protocolo
`hostPort`	porta exposta diretamente no nó
`hostIP`	IP do host usado com hostPort

Protocolos aceitos:

protocol: TCP
protocol: UDP
protocol: SCTP

Cuidado:

containerPort é informativo para o Kubernetes e ferramentas;
para expor o Pod de forma estável, use Service;
evite hostPort salvo necessidade real.

`containers[].env`

Variáveis de ambiente individuais.

env:
  - name: AMBIENTE
    value: "homologacao"

Campos:

Campo	Função
`name`	nome da variável
`value`	valor literal
`valueFrom`	valor vindo de Secret, ConfigMap, campo do Pod ou recurso

`env.valueFrom.configMapKeyRef`

Valor vindo de ConfigMap.

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

Use para configuração não sensível.

`env.valueFrom.secretKeyRef`

Valor vindo de Secret.

env:
  - name: SENHA_BANCO
    valueFrom:
      secretKeyRef:
        name: minha-aplicacao-secret
        key: SENHA_BANCO

Use para:

senhas;
tokens;
credenciais;
chaves.

`env.valueFrom.fieldRef`

Valor vindo de campos do próprio Pod.

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Exemplos úteis:

fieldPath: metadata.name
fieldPath: metadata.namespace
fieldPath: spec.nodeName
fieldPath: status.podIP

`env.valueFrom.resourceFieldRef`

Valor vindo de recursos do container.

env:
  - name: LIMITE_MEMORIA
    valueFrom:
      resourceFieldRef:
        resource: limits.memory

Exemplos:

resource: limits.cpu
resource: limits.memory
resource: requests.cpu
resource: requests.memory

`containers[].envFrom`

Importa várias variáveis de uma vez.

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

Use quando:

há muitas variáveis;
quer centralizar configuração;
Secret/ConfigMap já está pronto.

Cuidado:

pode expor variáveis demais para a aplicação;
nomes de chaves viram nomes de variáveis;
use Secret apenas para dados sensíveis;
use ConfigMap para dados não sensíveis.

`containers[].resources`

Define CPU, memória e outros recursos do container.

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

`resources.requests`

Recursos mínimos solicitados ao scheduler.

requests:
  cpu: "100m"
  memory: "128Mi"

Uso:

ajuda o Kubernetes a escolher o nó;
garante reserva mínima;
evita agendamento sem planejamento.

CPU:

100m = 0,1 CPU
500m = 0,5 CPU
1 = 1 CPU

Memória:

128Mi
512Mi
1Gi

`resources.limits`

Limite máximo permitido.

limits:
  cpu: "500m"
  memory: "512Mi"

Uso:

evita consumo excessivo;
protege outros workloads;
ajuda em ambientes compartilhados.

Cuidado:

limite de memória muito baixo causa OOMKilled;
limite de CPU muito baixo pode degradar resposta.

Probes

Probes verificam saúde da aplicação dentro do container.

Tipos principais:

Probe	Função
`readinessProbe`	diz se o Pod pode receber tráfego
`livenessProbe`	diz se o container deve ser reiniciado
`startupProbe`	dá tempo extra para aplicação iniciar

`readinessProbe`

Verifica se a aplicação está pronta para receber tráfego.

readinessProbe:
  httpGet:
    path: /ready
    port: http
  initialDelaySeconds: 10
  periodSeconds: 10

Se falhar:

o Pod continua vivo;
mas deixa de receber tráfego por Services que selecionam esse Pod.

`livenessProbe`

Verifica se a aplicação está viva.

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 20

Se falhar:

Kubernetes reinicia o container conforme a política de reinício.

Cuidado:

uma livenessProbe mal configurada pode reiniciar aplicação saudável.

`startupProbe`

Verifica inicialização lenta.

startupProbe:
  httpGet:
    path: /startup
    port: http
  periodSeconds: 5
  failureThreshold: 30

Use quando:

aplicação demora para subir;
frameworks pesados demoram a iniciar;
migrações ou inicializações atrasam o serviço;
você quer evitar que livenessProbe mate o container cedo demais.

Tipos de probe

`httpGet`

httpGet:
  path: /health
  port: 8080

Usa HTTP ou HTTPS.

`tcpSocket`

tcpSocket:
  port: 5432

Testa se a porta TCP responde.

`exec`

exec:
  command:
    - sh
    - -c
    - "test -f /tmp/ok"

Executa comando dentro do container.

`grpc`

grpc:
  port: 50051

Usa verificação gRPC.

Campos comuns das probes

Campo	Função
`initialDelaySeconds`	espera inicial antes da primeira verificação
`periodSeconds`	intervalo entre verificações
`timeoutSeconds`	tempo máximo de espera
`failureThreshold`	falhas antes de considerar problema
`successThreshold`	sucessos necessários para considerar OK
`terminationGracePeriodSeconds`	tempo de encerramento específico para a probe

`containers[].lifecycle`

Executa ações em momentos do ciclo de vida do container.

lifecycle:
  preStop:
    exec:
      command:
        - sh
        - -c
        - "sleep 10"

`preStop`

Executa antes de parar o container.

Uso:

dar tempo para conexões finalizarem;
encerrar processo com segurança;
permitir drenagem antes do término.

`postStart`

Executa logo após iniciar o container.

Uso menos comum.

`containers[].securityContext`

Configura segurança do container.

securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: false
  capabilities:
    drop:
      - ALL

Campos comuns:

Campo	Função
`allowPrivilegeEscalation`	impede escalada de privilégio
`readOnlyRootFilesystem`	deixa filesystem raiz somente leitura
`capabilities.add`	adiciona capacidades Linux
`capabilities.drop`	remove capacidades Linux
`privileged`	executa container privilegiado
`runAsUser`	UID do processo
`runAsGroup`	GID do processo
`runAsNonRoot`	exige não-root
`seccompProfile`	define perfil seccomp
`appArmorProfile`	define perfil AppArmor
`seLinuxOptions`	define opções SELinux

Recomendação:

allowPrivilegeEscalation: false
capabilities:
  drop:
    - ALL

Evite salvo necessidade real:

privileged: true

`containers[].volumeMounts`

Monta volumes dentro do container.

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

Campos:

Campo	Função
`name`	nome do volume declarado em `spec.volumes`
`mountPath`	caminho dentro do container
`readOnly`	monta como somente leitura
`subPath`	monta um item/caminho específico
`subPathExpr`	monta subPath usando expressão
`mountPropagation`	controla propagação de montagem
`recursiveReadOnly`	controla somente leitura recursivo quando suportado

Use para:

ConfigMap como arquivo;
Secret como arquivo;
cache temporário;
PVC;
diretórios compartilhados entre containers.

`containers[].volumeDevices`

Expõe volumes de bloco para o container.

volumeDevices:
  - name: disco
    devicePath: /dev/xvda

Uso:

volume em modo bloco;
aplicações que precisam acessar dispositivo de bloco diretamente.

Cuidado:

é caso mais avançado;
normalmente aplicações comuns usam volumeMounts.

`containers[].stdin`, `stdinOnce` e `tty`

Campos usados para interação com o container.

stdin: true
tty: true

Uso:

Pods de debug;
containers interativos;
testes manuais.

Cuidado:

não costuma ser usado em aplicações de produção.

`initContainers`

Containers que rodam antes dos containers principais.

initContainers:
  - name: preparar-ambiente
    image: busybox:1.36
    command:
      - sh
      - -c
    args:
      - "sleep 5"

Use para:

preparar diretório;
aguardar dependência;
criar arquivo inicial;
validar configuração;
executar preparação simples.

Cuidado:

initContainer precisa terminar com sucesso;
se falhar, o Pod não inicia os containers principais;
não use para lógica complexa que deveria ser Job.

`ephemeralContainers`

Containers efêmeros são usados para debug de Pods existentes.

ephemeralContainers:
  - name: debug
    image: busybox:1.36
    targetContainerName: app

Uso:

troubleshooting;
debug quando kubectl exec não basta;
inspecionar Pod com imagem distroless;
diagnóstico temporário.

Cuidado:

não são usados para construir aplicação;
não substituem containers principais;
normalmente são adicionados por comando de debug, não no manifesto comum.

Exemplo de comando:

kubectl debug -it pod/minha-aplicacao -n meu-projeto --image=busybox:1.36 --target=app

`spec.restartPolicy`

Define política de reinício dos containers do Pod.

restartPolicy: Always

Valores aceitos:

restartPolicy: Always
restartPolicy: OnFailure
restartPolicy: Never

`Always`

Reinicia containers quando eles terminam.

Uso:

aplicações contínuas;
Pods gerenciados por Deployment;
comportamento comum para serviços.

`OnFailure`

Reinicia apenas se terminar com falha.

Uso:

tarefas;
testes;
workloads que podem concluir com sucesso.

`Never`

Não reinicia containers.

Uso:

debug;
teste pontual;
execução única em Pod direto.

Cuidado:

em Deployment, o uso normal é Always;
para tarefa pontual, normalmente prefira Job.

`spec.activeDeadlineSeconds`

Define tempo máximo de execução do Pod.

activeDeadlineSeconds: 3600

Significado:

valor em segundos;
após esse tempo, o Pod pode ser finalizado.

Uso:

limitar tempo de execução;
evitar Pod de teste rodando indefinidamente;
tarefas temporárias.

Cuidado:

para tarefas reais, Job costuma ser mais adequado.

`spec.serviceAccountName`

Define a ServiceAccount usada pelo Pod.

serviceAccountName: minha-aplicacao

Use quando:

o Pod precisa acessar a API Kubernetes;
precisa ler recursos autorizados por RBAC;
precisa usar identidade específica;
quer evitar usar a ServiceAccount padrão do namespace.

Recomendação:

use ServiceAccount dedicada quando o Pod precisa de permissões;
aplique menor privilégio.

`spec.automountServiceAccountToken`

Controla se o token da ServiceAccount será montado automaticamente no Pod.

automountServiceAccountToken: false

Recomendação de segurança:

automountServiceAccountToken: false

Use true apenas se a aplicação realmente precisa chamar a API Kubernetes.

`spec.imagePullSecrets`

Secrets usados para baixar imagens de registry privado.

imagePullSecrets:
  - name: registry-credencial

Use quando:

a imagem está em registry privado;
registry exige autenticação;
CI/CD publica imagens privadas.

O Secret normalmente é do tipo:

type: kubernetes.io/dockerconfigjson

`spec.securityContext`

Configura segurança padrão do Pod.

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  runAsGroup: 1000
  fsGroup: 1000
  seccompProfile:
    type: RuntimeDefault

Campos comuns:

Campo	Função
`runAsNonRoot`	exige usuário não-root
`runAsUser`	UID padrão
`runAsGroup`	GID padrão
`fsGroup`	grupo para volumes
`fsGroupChangePolicy`	controla ajuste de permissão em volumes
`supplementalGroups`	grupos adicionais
`supplementalGroupsPolicy`	política para grupos suplementares
`seccompProfile`	perfil seccomp
`appArmorProfile`	perfil AppArmor
`seLinuxOptions`	opções SELinux
`sysctls`	parâmetros sysctl permitidos
`windowsOptions`	opções para Windows

Recomendação:

evitar root quando possível;
usar runAsNonRoot: true;
usar seccompProfile.type: RuntimeDefault quando compatível.

`spec.volumes`

Define volumes disponíveis para o Pod.

volumes:
  - name: config
    configMap:
      name: minha-aplicacao-config
  - name: cache
    emptyDir: {}

Tipos comuns:

Tipo	Uso
`configMap`	montar configuração como arquivo
`secret`	montar senha/certificado como arquivo
`emptyDir`	diretório temporário do Pod
`persistentVolumeClaim`	disco persistente
`projected`	combina várias fontes em um volume
`downwardAPI`	expõe metadados do Pod como arquivo
`hostPath`	monta caminho do nó
`nfs`	monta compartilhamento NFS
`csi`	volume fornecido por driver CSI
`ephemeral`	volume efêmero baseado em PVC temporário

Volume `configMap`

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

Uso:

arquivos de configuração;
templates;
parâmetros não sensíveis.

Volume `secret`

volumes:
  - name: segredo
    secret:
      secretName: minha-aplicacao-secret

Uso:

certificados;
chaves;
senhas;
tokens.

Volume `emptyDir`

volumes:
  - name: cache
    emptyDir: {}

Uso:

cache temporário;
arquivos gerados em runtime;
compartilhamento entre containers do mesmo Pod.

Cuidado:

é apagado quando o Pod é removido do nó.

Volume `persistentVolumeClaim`

volumes:
  - name: dados
    persistentVolumeClaim:
      claimName: minha-aplicacao-pvc

Uso:

dados persistentes;
uploads;
arquivos que precisam sobreviver à recriação do Pod.

Cuidado:

se a aplicação precisa identidade fixa por réplica, talvez StatefulSet seja melhor.

Volume `projected`

Combina várias fontes em um volume.

volumes:
  - name: projetado
    projected:
      sources:
        - configMap:
            name: app-config
        - secret:
            name: app-secret
        - downwardAPI:
            items:
              - path: "podname"
                fieldRef:
                  fieldPath: metadata.name

Uso:

combinar ConfigMap, Secret, Downward API e token;
organizar arquivos de configuração em um único ponto de montagem.

Volume `hostPath`

Monta caminho do nó dentro do Pod.

volumes:
  - name: host
    hostPath:
      path: /var/log
      type: Directory

Cuidado:

pode expor arquivos do nó;
aumenta risco de segurança;
reduz portabilidade;
use apenas quando necessário e controlado.

Campos de DNS

`spec.dnsPolicy`

Define política de DNS do Pod.

dnsPolicy: ClusterFirst

Valores aceitos:

dnsPolicy: ClusterFirst
dnsPolicy: ClusterFirstWithHostNet
dnsPolicy: Default
dnsPolicy: None

Uso comum:

dnsPolicy: ClusterFirst

Significado:

usa DNS interno do cluster primeiro;
permite resolver Services por nome.

`spec.dnsConfig`

Configura DNS customizado do Pod.

dnsConfig:
  nameservers:
    - 10.0.0.10
  searches:
    - meu-projeto.svc.cluster.local
  options:
    - name: ndots
      value: "2"

Cuidado:

normalmente não é necessário;
configuração errada pode quebrar resolução de nomes.

`spec.enableServiceLinks`

Controla criação automática de variáveis de ambiente para Services.

enableServiceLinks: true

Valores:

enableServiceLinks: true
enableServiceLinks: false

Cuidado:

muitos Services no namespace podem gerar muitas variáveis;
para ambientes mais previsíveis, pode-se usar false.

Campos de host e rede

`spec.hostNetwork`

Faz o Pod usar a rede do nó.

hostNetwork: true

Cuidado:

aumenta exposição;
pode causar conflito de portas;
reduz isolamento;
normalmente evite em aplicações comuns.

`spec.hostPID`

Compartilha namespace de processos do nó.

hostPID: true

Cuidado:

recurso sensível;
pode expor processos do nó;
normalmente deve ser evitado.

`spec.hostIPC`

Compartilha namespace IPC do nó.

hostIPC: true

Cuidado:

recurso sensível;
normalmente deve ser evitado.

`spec.hostname`, `subdomain` e `setHostnameAsFQDN`

Controlam nome do host dentro do Pod.

hostname: app-1
subdomain: app
setHostnameAsFQDN: true

Uso:

cenários que precisam nome específico;
integração com DNS interno;
workloads que dependem de hostname previsível.

Cuidado:

para identidade estável por réplica, normalmente use StatefulSet.

`spec.hostAliases`

Adiciona entradas no /etc/hosts do Pod.

hostAliases:
  - ip: "10.0.0.10"
    hostnames:
      - "sistema.local"

Use apenas quando:

não há DNS adequado;
precisa compatibilidade temporária.

Evite como solução permanente.

Campos de agendamento

`spec.nodeSelector`

Seleciona nós por labels.

nodeSelector:
  kubernetes.io/os: linux

Uso:

rodar apenas em Linux;
rodar em nós com GPU;
rodar em nós de determinado perfil.

`spec.nodeName`

Força o Pod para um nó específico.

nodeName: node-01

Cuidado:

ignora parte do agendamento normal;
reduz flexibilidade;
pode causar Pod pendente se o nó não puder rodar;
normalmente prefira nodeSelector ou affinity.

`spec.affinity`

Define regras avançadas de afinidade.

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: minha-aplicacao
          topologyKey: kubernetes.io/hostname

Tipos:

Campo	Uso
`nodeAffinity`	escolher nós
`podAffinity`	aproximar Pods
`podAntiAffinity`	separar Pods

`spec.tolerations`

Permite que o Pod rode em nós com taints.

tolerations:
  - key: "dedicado"
    operator: "Equal"
    value: "gpu"
    effect: "NoSchedule"

Efeitos aceitos:

effect: NoSchedule
effect: PreferNoSchedule
effect: NoExecute

`spec.topologySpreadConstraints`

Distribui Pods entre domínios de topologia.

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app: minha-aplicacao

Valores de whenUnsatisfiable:

whenUnsatisfiable: DoNotSchedule
whenUnsatisfiable: ScheduleAnyway

Prioridade, runtime e recursos avançados

`spec.priorityClassName`

Define classe de prioridade do Pod.

priorityClassName: alta-prioridade

Use quando:

há classes de prioridade configuradas;
workloads críticos precisam preferência.

Cuidado:

prioridade pode causar preempção de Pods menos prioritários.

`spec.preemptionPolicy`

Controla preempção.

preemptionPolicy: PreemptLowerPriority

Valores aceitos:

preemptionPolicy: PreemptLowerPriority
preemptionPolicy: Never

`spec.runtimeClassName`

Escolhe runtime alternativo.

runtimeClassName: gvisor

Use quando:

cluster tem RuntimeClass configurado;
precisa de sandboxing;
precisa de runtime especial.

Normalmente fica ausente.

`spec.os`

Indica sistema operacional do Pod.

os:
  name: linux

Uso:

clusters com suporte a múltiplos sistemas;
diferenciar Linux/Windows.

`spec.resources`

Define recursos em nível de Pod, quando suportado pelo cluster.

resources:
  requests:
    cpu: "500m"
    memory: "512Mi"
  limits:
    cpu: "1"
    memory: "1Gi"

Cuidado:

em muitos manifestos comuns, resources são definidos no container;
confira suporte do cluster antes de depender desse campo.

`spec.readinessGates`

Adiciona condições extras para considerar o Pod pronto.

readinessGates:
  - conditionType: exemplo.com/pronto

Uso:

controladores externos definem condição de prontidão;
integração com sistemas que precisam validar algo além da readinessProbe.

Cuidado:

se a condição nunca for marcada como pronta, o Pod não fica Ready.

`spec.terminationGracePeriodSeconds`

Tempo para o Pod encerrar com elegância.

terminationGracePeriodSeconds: 30

Significado:

Kubernetes envia sinal de término;
aguarda esse tempo;
se o processo não encerrar, força finalização.

`status`

status mostra o estado atual do Pod.

Você normalmente não escreve status no YAML.

O Kubernetes preenche automaticamente.

No arquivo de referência aparecem campos como:

status:
  conditions
  containerStatuses
  initContainerStatuses
  ephemeralContainerStatuses
  hostIP
  hostIPs
  message
  nominatedNodeName
  observedGeneration
  phase
  podIP
  podIPs
  qosClass
  reason
  resize
  resourceClaimStatuses
  startTime

Use para diagnóstico:

kubectl get pod minha-aplicacao -n meu-projeto -o yaml
kubectl describe pod minha-aplicacao -n meu-projeto

`status.phase`

Mostra fase geral do Pod.

Valores comuns:

Pending
Running
Succeeded
Failed
Unknown

`Pending`

Pod aceito pelo cluster, mas ainda não está totalmente rodando.

Causas comuns:

aguardando agendamento;
imagem sendo baixada;
falta de recurso;
PVC pendente;
problema de taint/toleration.

`Running`

Pod foi associado a um nó e pelo menos um container está rodando ou em processo de iniciar/reiniciar.

`Succeeded`

Todos os containers terminaram com sucesso e não serão reiniciados.

`Failed`

Todos os containers terminaram, e pelo menos um terminou com falha.

`Unknown`

Estado do Pod não pôde ser obtido.

`status.containerStatuses`

Mostra estado dos containers principais.

Campos úteis:

Campo	Significado
`name`	nome do container
`ready`	se está pronto
`restartCount`	quantidade de reinícios
`state`	estado atual
`lastState`	estado anterior
`image`	imagem usada
`imageID`	ID real da imagem
`containerID`	ID do container

Estados possíveis:

running
waiting
terminated

`status.qosClass`

Classe de qualidade de serviço do Pod.

Valores:

Guaranteed
Burstable
BestEffort

Cuidado:

BestEffort é mais vulnerável em pressão de recursos;
em ambiente compartilhado, defina requests e limits.

Manifesto mínimo funcional

apiVersion: v1
kind: Pod
metadata:
  name: nginx-exemplo
  namespace: meu-projeto
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80

Aplicar:

kubectl apply -f pod.yml

Verificar:

kubectl get pods -n meu-projeto
kubectl describe pod nginx-exemplo -n meu-projeto

Manifesto recomendado para teste simples

apiVersion: v1
kind: Pod
metadata:
  name: teste-curl
  namespace: meu-projeto
  labels:
    app: teste-curl
spec:
  restartPolicy: Never
  containers:
    - name: curl
      image: curlimages/curl:latest
      command:
        - sh
        - -c
      args:
        - "sleep 3600"
      resources:
        requests:
          cpu: "50m"
          memory: "64Mi"
        limits:
          cpu: "200m"
          memory: "128Mi"

Uso:

entrar no Pod;
testar DNS;
testar Service;
testar conectividade.

Entrar:

kubectl exec -it teste-curl -n meu-projeto -- sh

Manifesto recomendado para aplicação web simples

Para aplicação contínua, prefira Deployment.

O Pod abaixo é útil como exemplo didático, mas em produção use Deployment.

apiVersion: v1
kind: Pod
metadata:
  name: app-web
  namespace: meu-projeto
  labels:
    app: app-web
spec:
  automountServiceAccountToken: false
  restartPolicy: Always
  containers:
    - name: app
      image: registry.exemplo.local/projeto/app-web:1.0.0
      imagePullPolicy: IfNotPresent
      ports:
        - name: http
          containerPort: 8080
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "500m"
          memory: "512Mi"
      readinessProbe:
        httpGet:
          path: /ready
          port: http
        initialDelaySeconds: 10
        periodSeconds: 10
      livenessProbe:
        httpGet:
          path: /health
          port: http
        initialDelaySeconds: 30
        periodSeconds: 20

Exemplo de Pod consumindo ConfigMap e Secret

apiVersion: v1
kind: Pod
metadata:
  name: app-configurado
  namespace: meu-projeto
spec:
  containers:
    - name: app
      image: registry.exemplo.local/projeto/app:1.0.0
      envFrom:
        - configMapRef:
            name: app-config
        - secretRef:
            name: app-secret
      volumeMounts:
        - name: config
          mountPath: /app/config
          readOnly: true
        - name: segredo
          mountPath: /app/secret
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: app-config
    - name: segredo
      secret:
        secretName: app-secret

Exemplo de Pod com initContainer

apiVersion: v1
kind: Pod
metadata:
  name: app-com-init
  namespace: meu-projeto
spec:
  initContainers:
    - name: preparar
      image: busybox:1.36
      command:
        - sh
        - -c
      args:
        - "echo preparando && sleep 5"
  containers:
    - name: app
      image: nginx:1.27

Comandos úteis

Aplicar

kubectl apply -f pod.yml

Ver Pods

kubectl get pods -n meu-projeto

Ver Pod específico

kubectl get pod minha-aplicacao -n meu-projeto

Ver detalhes

kubectl describe pod minha-aplicacao -n meu-projeto

Ver YAML real aplicado

kubectl get pod minha-aplicacao -n meu-projeto -o yaml

Ver logs

kubectl logs minha-aplicacao -n meu-projeto

Ver logs de container específico

kubectl logs minha-aplicacao -n meu-projeto -c app

Acompanhar logs

kubectl logs -f minha-aplicacao -n meu-projeto -c app

Entrar no container

kubectl exec -it minha-aplicacao -n meu-projeto -c app -- sh

Ver eventos do namespace

kubectl get events -n meu-projeto --sort-by=.lastTimestamp

Criar Pod temporário para DNS

kubectl run teste-dns -n meu-projeto --rm -it --image=busybox:1.36 --restart=Never -- sh

Criar Pod temporário com curl

kubectl run teste-curl -n meu-projeto --rm -it --image=curlimages/curl --restart=Never -- sh

Debug com container efêmero

kubectl debug -it pod/minha-aplicacao -n meu-projeto --image=busybox:1.36 --target=app

Apagar Pod

kubectl delete pod minha-aplicacao -n meu-projeto

Cuidado:

Se o Pod for gerenciado por Deployment, ReplicaSet, StatefulSet, DaemonSet ou Job, o controlador pode criar outro Pod novamente.

Relação com outros manifestos

Um Pod normalmente faz parte de um conjunto de manifestos.

Uso típico:

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

Pod + Deployment

Deployment cria e gerencia Pods.

Para aplicação contínua, normalmente use Deployment em vez de Pod direto.

Pod + Service

Service seleciona Pods por labels e fornece acesso estável.

Pod + ConfigMap

Pod consome ConfigMap como variável de ambiente ou volume.

Pod + Secret

Pod consome Secret como variável de ambiente ou volume.

Pod + ServiceAccount

Pod usa ServiceAccount como identidade para acessar a API Kubernetes.

Pod + PVC

Pod monta PersistentVolumeClaim para armazenamento persistente.

Pod + NetworkPolicy

NetworkPolicy controla tráfego permitido para Pods selecionados.

Pod + ResourceQuota/LimitRange

ResourceQuota e LimitRange controlam limites e padrões no namespace onde o Pod será criado.

Erros comuns

Criar Pod direto para aplicação que deveria ser Deployment

Problema:

Pod não tem rollout;
Pod não tem réplicas;
Pod não faz rollback;
se for apagado, não volta sozinho;
não é o modelo ideal para aplicação contínua.

Prefira:

Deployment

para aplicação web/API sem estado.

Esquecer resources

Evite:

resources: {}

Prefira:

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

Rodar como root sem necessidade

Evite quando possível:

securityContext:
  runAsUser: 0

Prefira:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000

Service não encontra o Pod

Sintoma:

kubectl get endpoints meu-service -n meu-projeto

Retorna vazio.

Causa comum:

labels do Pod não combinam com selector do Service.

Verificar:

kubectl get pods -n meu-projeto --show-labels
kubectl describe service meu-service -n meu-projeto

ImagePullBackOff

Sintoma:

ImagePullBackOff
ErrImagePull

Possíveis causas:

imagem não existe;
tag errada;
registry privado sem credencial;
imagePullSecrets ausente;
falha de rede até o registry.

Verificar:

kubectl describe pod minha-aplicacao -n meu-projeto

CrashLoopBackOff

Sintoma:

CrashLoopBackOff

Possíveis causas:

aplicação inicia e cai;
comando errado;
variável ausente;
Secret ou ConfigMap incorreto;
livenessProbe matando o container;
falta de permissão;
erro de configuração.

Verificar:

kubectl logs minha-aplicacao -n meu-projeto -c app --previous
kubectl describe pod minha-aplicacao -n meu-projeto

Pod preso em Pending

Possíveis causas:

falta de CPU/memória;
PVC pendente;
nodeSelector não bate com nenhum nó;
affinity restritiva;
taints sem tolerations;
imagem ainda sendo baixada;
scheduler não consegue agendar.

Verificar:

kubectl describe pod minha-aplicacao -n meu-projeto
kubectl get events -n meu-projeto --sort-by=.lastTimestamp

Pod não fica Ready

Possíveis causas:

readinessProbe falhando;
aplicação não escuta na porta esperada;
path de healthcheck errado;
dependência indisponível;
inicialização lenta.

Verificar:

kubectl describe pod minha-aplicacao -n meu-projeto
kubectl logs minha-aplicacao -n meu-projeto -c app

Usar hostNetwork/hostPID/privileged sem necessidade

Evite:

hostNetwork: true
hostPID: true

Evite:

securityContext:
  privileged: true

Esses recursos reduzem isolamento e aumentam risco.

Montar Secret ou ConfigMap no namespace errado

ConfigMap e Secret consumidos pelo Pod precisam estar no mesmo namespace do Pod.

Verificar:

kubectl get configmap -n meu-projeto
kubectl get secret -n meu-projeto

Checklist para uso em produção

Antes de aplicar um Pod em ambiente compartilhado:

Resumo

Use Pod para executar containers no Kubernetes.

O Pod controla:

containers principais;
initContainers;
containers efêmeros de debug;
volumes;
variáveis de ambiente;
consumo de ConfigMap e Secret;
probes de saúde;
resources;
segurança do Pod e dos containers;
DNS;
ServiceAccount;
política de reinício;
agendamento em nós;
tolerations, affinity e topology spread;
status de execução.

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

Namespace + Deployment + Service + Ingress

O Pod existe nesse fluxo, mas normalmente é criado pelo Deployment:

Deployment → ReplicaSet → Pod

Para ambiente institucional compartilhado, o conjunto recomendado é:

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

Manifestos Kubernetes

namespace.yml

deployment.yml

service.yml

Ingress.yml

configmap.yml

secret.yml

pod.yml

persistentvolumeclaim.yml

persistentvolume.yml

GitLab-managed Kubernetes resources

Helm

Tutorial — Acessar o cluster Kubernetes pelo seu PC

pod.yml

Quando usar Pod

Quando Pod não é o recurso indicado

Uso em cenário de universidade

Exemplo completo: pod.yml

Explicação linha por linha

apiVersion: v1

kind: Pod

metadata

metadata.name

metadata.namespace

metadata.labels

metadata.annotations

Campos de metadata normalmente gerenciados pelo Kubernetes

spec

spec.containers

containers[].name

containers[].image

containers[].imagePullPolicy

containers[].command

containers[].args

containers[].workingDir

containers[].ports

containers[].env

env.valueFrom.configMapKeyRef

env.valueFrom.secretKeyRef

env.valueFrom.fieldRef

env.valueFrom.resourceFieldRef

containers[].envFrom

containers[].resources

resources.requests

resources.limits

Probes

readinessProbe

livenessProbe

startupProbe

Tipos de probe

httpGet

tcpSocket

exec

grpc

Campos comuns das probes

containers[].lifecycle

preStop

postStart

containers[].securityContext

containers[].volumeMounts

containers[].volumeDevices

containers[].stdin, stdinOnce e tty

initContainers

ephemeralContainers

spec.restartPolicy

Always

OnFailure

Never

spec.activeDeadlineSeconds

spec.serviceAccountName

spec.automountServiceAccountToken

spec.imagePullSecrets

spec.securityContext

spec.volumes

Volume configMap

Volume secret

Volume emptyDir

Volume persistentVolumeClaim

Volume projected

Volume hostPath

`apiVersion: v1`

`kind: Pod`

`metadata`

`metadata.name`

`metadata.namespace`

`metadata.labels`

`metadata.annotations`

Campos de `metadata` normalmente gerenciados pelo Kubernetes

`spec`

`spec.containers`

`containers[].name`

`containers[].image`

`containers[].imagePullPolicy`

`containers[].command`

`containers[].args`

`containers[].workingDir`

`containers[].ports`

`containers[].env`

`env.valueFrom.configMapKeyRef`

`env.valueFrom.secretKeyRef`

`env.valueFrom.fieldRef`

`env.valueFrom.resourceFieldRef`

`containers[].envFrom`

`containers[].resources`

`resources.requests`

`resources.limits`

`readinessProbe`

`livenessProbe`

`startupProbe`

`httpGet`

`tcpSocket`

`exec`

`grpc`

`containers[].lifecycle`

`preStop`

`postStart`

`containers[].securityContext`

`containers[].volumeMounts`

`containers[].volumeDevices`

`containers[].stdin`, `stdinOnce` e `tty`

`initContainers`

`ephemeralContainers`

`spec.restartPolicy`

`Always`

`OnFailure`

`Never`

`spec.activeDeadlineSeconds`

`spec.serviceAccountName`

`spec.automountServiceAccountToken`

`spec.imagePullSecrets`

`spec.securityContext`

`spec.volumes`

Volume `configMap`

Volume `secret`

Volume `emptyDir`

Volume `persistentVolumeClaim`

Volume `projected`

Volume `hostPath`

`spec.dnsPolicy`

`spec.dnsConfig`

`spec.enableServiceLinks`

`spec.hostNetwork`

`spec.hostPID`

`spec.hostIPC`

`spec.hostname`, `subdomain` e `setHostnameAsFQDN`

`spec.hostAliases`

`spec.nodeSelector`

`spec.nodeName`

`spec.affinity`

`spec.tolerations`

`spec.topologySpreadConstraints`

`spec.priorityClassName`

`spec.preemptionPolicy`

`spec.runtimeClassName`

`spec.os`

`spec.resources`

`spec.readinessGates`

`spec.terminationGracePeriodSeconds`

`status`

`status.phase`