Skip to content

Kubernetes Folha de referência

Plataforma de orquestração de contêineres para automatizar deploy e escalonamento.

01

Primeiros passos

Básico do kubectl

kubectl é a CLI do Kubernetes. get lista recursos, create cria novos, expose cria services, scale muda a contagem de réplicas. describe dá informação detalhada sobre um recurso.

kubernetes
# cluster info
kubectl cluster-info

# list nodes
kubectl get nodes

# list pods (all namespaces)
kubectl get pods --all-namespaces

# create a deployment
kubectl create deployment nginx --image=nginx

# expose deployment as service
kubectl expose deployment nginx --port=80 --type=LoadBalancer

# scale deployment
kubectl scale deployment nginx --replicas=3

# get detailed info
kubectl describe pod <pod-name>

# view logs
kubectl logs <pod-name>

Formatação de saída

A flag -o controla a saída. yaml/json mostram a spec completa do recurso. jsonpath e custom-columns extraem campos específicos para scriptar. -w observa mudanças ao vivo. Use --no-headers em scripts para remover os nomes das colunas.

kubernetes
# wide format (more columns)
kubectl get pods -o wide

# YAML output
kubectl get pod nginx -o yaml

# JSON output
kubectl get pod nginx -o json

# jsonpath (extract specific fields)
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

# show labels
kubectl get pods --show-labels

# watch for changes
kubectl get pods -w

Context e configuração

Um context agrupa endereço do cluster, credenciais de usuário e namespace. Arquivos kubeconfig (padrão ~/.kube/config) guardam isso. Múltiplos arquivos podem ser combinados via a variável de ambiente KUBECONFIG para gerenciar muitos clusters.

kubernetes
# view current config
kubectl config view

# list contexts
kubectl config get-contexts

# switch context
kubectl config use-context my-cluster

# set default namespace for current context
kubectl config set-context --current --namespace=dev

# show current context
kubectl config current-context

# KUBECONFIG with multiple files
export KUBECONFIG=~/.kube/config:~/.kube/prod-config

Explain e API resources

api-resources lista o que o cluster suporta. explain mostra o schema OpenAPI de qualquer recurso — valioso para escrever YAML sem sair do terminal. Use --recursive para despejar toda a estrutura aninhada.

kubernetes
# list all resource types
kubectl api-resources

# list namespaced vs cluster-scoped
kubectl api-resources --namespaced=true
kubectl api-resources --namespaced=false

# explain a resource's fields
kubectl explain pod
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy

# explain with recursion (all nested fields)
kubectl explain pod --recursive

# include description
kubectl explain pod.spec.containers.resources --api-version=apps/v1

Dry run e geração de YAML

--dry-run=client -o yaml é a forma padrão de criar esqueletos de manifests a partir de comandos imperativos. --dry-run=server valida contra o apiserver real (admission webhooks, schema) sem persistir. Ótimo para inicializar YAML declarativo.

kubernetes
# generate YAML without applying
kubectl create deployment nginx --image=nginx --dry-run=client -o yaml

# pipe generated YAML straight to a file
kubectl create deployment nginx --image=nginx --dry-run=client -o yaml > nginx.yaml

# apply the generated manifest
kubectl apply -f nginx.yaml

# dry-run against the server (validates with apiserver)
kubectl apply -f nginx.yaml --dry-run=server

# generate a service from a deployment
kubectl create service clusterip my-svc --tcp=80:80 --dry-run=client -o yaml

Ajuda e autocomplete

Cada comando kubectl suporta --help com exemplos. O completion do shell economiza digitação enorme e expõe subcomandos. O alias k=kubectl é quase universal entre praticantes — combine com completion para a melhor experiência.

kubernetes
# top-level help
kubectl --help

# subcommand help
kubectl create --help
kubectl explain --help

# generate bash completion
kubectl completion bash > /etc/bash_completion.d/kubectl

# zsh completion
source <(kubectl completion zsh)

# alias k=kubectl with completion
alias k=kubectl
complete -o default -F __start_kubectl k

# shorthand: kubectl -> k
echo 'alias k=kubectl' >> ~/.bashrc
02

Pod

Manifest de Pod

Um Pod é a menor unidade implantável, guardando um ou mais contêineres que compartilham rede e armazenamento. Contêineres num pod são sempre co-agendados no mesmo nó. Você raramente cria pods diretamente — use um Deployment ou Job.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 200m
          memory: 256Mi
  restartPolicy: Always

Pod multi-contêiner (sidecar)

Pods multi-contêiner compartilham rede (mesmo IP, espaço de portas) e volumes. Padrões comuns: sidecar (auxiliar), adapter (transforma saída), ambassador (proxy). O volume emptyDir compartilhado permite que o sidecar leia os logs que o contêiner principal escreve.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: web-with-logs
spec:
  containers:
    - name: app
      image: nginx
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
    - name: log-shipper
      image: busybox
      command: ["sh", "-c", "tail -f /var/log/nginx/access.log"]
      volumeMounts:
        - name: shared-logs
          mountPath: /var/log/nginx
          readOnly: true
  volumes:
    - name: shared-logs
      emptyDir: {}

Ciclo de vida e fases do pod

A fase de um pod é de alto nível (Pending, Running, Succeeded, Failed). Os estados dos contêineres (Waiting/Running/Terminated) dão o detalhe real — por exemplo, CrashLoopBackOff significa que o contêiner continua saindo. Verifique a contagem de reinícios e os eventos para diagnosticar.

kubernetes
# pod phases: Pending | Running | Succeeded | Failed | Unknown
kubectl get pod nginx

# show status including container states
kubectl get pod nginx -o jsonpath='{.status}'

# container states: Waiting | Running | Terminated
kubectl describe pod nginx

# common Waiting reasons: ImagePullBackOff, CrashLoopBackOff, CreateContainerConfigError
kubectl get pods --field-selector=status.phase=Pending

# restart count reveals crash loops
kubectl get pods -o jsonpath='{.items[*].status.containerStatuses[*].restartCount}'

Status e eventos do pod

Eventos são o log de auditoria do cluster para um recurso — agendamento, pull, erros de pull, falhas de liveness. Expiram (~1 hora por padrão), então capture-os enquanto depura. describe agrupa os eventos com a spec do recurso para triagem rápida.

kubernetes
# full describe (includes Events at the bottom)
kubectl describe pod nginx

# list cluster events sorted by time
kubectl get events --sort-by=.lastTimestamp

# events for a specific namespace
kubectl get events -n default

# watch events live
kubectl get events -w

# filter events by type
kubectl get events --field-selector type=Warning

# events for a specific pod
kubectl get events --field-selector involvedObject.name=nginx

Exec e port-forward

exec roda comandos dentro de um contêiner; -it aloca um TTY para shells. port-forward faz túnel de uma porta local a um pod/service sem expô-lo publicamente — essencial para depurar bancos de dados ou UIs web a partir do seu notebook.

kubernetes
# open an interactive shell
kubectl exec -it nginx -- sh

# run a one-off command
kubectl exec nginx -- ls /etc/nginx

# specify container in a multi-container pod
kubectl exec -it web-with-logs -c log-shipper -- sh

# forward a local port to a pod port
kubectl port-forward pod/nginx 8080:80

# forward to a service / deployment
kubectl port-forward svc/nginx 8080:80
kubectl port-forward deployment/nginx 8080:80

# forward to a random local port
kubectl port-forward pod/nginx :80

Delete e force

Excluir um pod controlado por um Deployment/StatefulSet causa substituição imediata. --force --grace-period=0 pula o período de carência do sinal TERM e pode deixar recursos obsoletos — use com parcimônia. Pods presos em terminating frequentemente precisam de remoção de finalizer.

kubernetes
# delete a pod (controller will recreate it)
kubectl delete pod nginx

# force delete immediately (bypasses graceful shutdown)
kubectl delete pod nginx --grace-period=0 --force

# delete by label
kubectl delete pods -l app=nginx

# delete all pods in a namespace
kubectl delete pods --all -n default

# delete a pod and wait for it to be gone
kubectl delete pod nginx --wait

# delete with a timeout
kubectl delete pod nginx --timeout=30s
03

Deployment

Manifest de Deployment

Um Deployment gerencia ReplicaSets e fornece rolling updates e rollbacks declarativos. spec.selector deve corresponder a spec.template.metadata.labels. O template define a spec de pod que será lançada.

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

Estratégia de rolling update

RollingUpdate (padrão) substitui pods gradualmente para zero downtime. maxSurge/maxUnavailable controlam a velocidade do rollout e a disponibilidade. Recreate mata os pods antes de criar novos — usado quando a app não pode rodar duas versões ao mesmo tempo (por exemplo, escritores de volume único).

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%        # extra pods above replicas during update
      maxUnavailable: 25%  # pods allowed down during update
  # alternative: recreate (kills all, then starts new)
  # strategy:
  #   type: Recreate
  selector:
    matchLabels:
      app: nginx
  template:

Rollback

Cada mudança no template de pod cria uma revisão de ReplicaSet. undo devolve o tráfego a um ReplicaSet anterior. pause permite fazer múltiplas correções entre incrementos canary. Use --record (descontinuado) ou annotations para rastrear as causas das mudanças.

kubernetes
# view rollout history
kubectl rollout history deployment/nginx

# see details of a specific revision
kubectl rollout history deployment/nginx --revision=2

# undo to the previous revision
kubectl rollout undo deployment/nginx

# undo to a specific revision
kubectl rollout undo deployment/nginx --to-revision=2

# pause/resume a rollout (for canary pauses)
kubectl rollout pause deployment/nginx
kubectl rollout resume deployment/nginx

# check rollout status
kubectl rollout status deployment/nginx

Scale e HPA

HPA escala réplicas com base em CPU/memória ou métricas personalizadas. Requer metrics-server para CPU/memória. minReplicas e maxReplicas delimitam o escalonamento. A API v2 suporta múltiplas métricas e comportamentos (estabilização na redução).

kubernetes
# scale manually
kubectl scale deployment/nginx --replicas=5

# horizontal pod autoscaler (CPU target)
kubectl autoscale deployment nginx --min=2 --max=10 --cpu-percent=80

# list HPA
kubectl get hpa

# HPA manifest (v2 with custom metrics)
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 80

Atualizando imagem e reinício

set image dispara um novo ReplicaSet e um rolling update. rollout restart é a forma mais limpa de puxar a imagem mais recente ou renovar a config — cria um novo ReplicaSet com a mesma spec. edit abre seu $EDITOR para correções ad-hoc.

kubernetes
# update container image
kubectl set image deployment/nginx nginx=nginx:1.26

# update from a specific container
kubectl set image deployment/nginx container=nginx:1.26 --record

# trigger a rollout restart (same image, recreate pods)
kubectl rollout restart deployment/nginx

# edit a deployment in editor
kubectl edit deployment/nginx

# patch a single field
kubectl patch deployment/nginx -p '{"spec":{"replicas":5}}'

# apply a manifest change
kubectl apply -f nginx-deployment.yaml

Status do Deployment

Um Deployment possui ReplicaSets; só um está ativo (replicas>0). ReplicaSets antigos escalam para zero, para rollback. O label pod-template-hash marca cada pod com sua revisão. Verifique status.conditions para sinais de Available, Progressing e ReplicaFailure.

kubernetes
# deployment status
kubectl get deployment nginx

# watch rollout
kubectl rollout status deployment/nginx

# show ReplicaSets owned by the deployment
kubectl get rs -l app=nginx

# show pods across all revisions
kubectl get pods -l app=nginx --show-labels

# pod-template-hash label distinguishes revisions
# kubectl get pods -l app=nginx,pod-template-hash=xxxx

# conditions: Available, Progressing, ReplicaFailure
kubectl get deployment nginx -o jsonpath='{.status.conditions}'
04

Service

Tipos de Service

Um Service fornece um IP/DNS estável que balanceia carga sobre um conjunto de pods. ClusterIP é o padrão (só dentro do cluster). NodePort e LoadBalancer expõem externamente. ExternalName é um alias de DNS, não um proxy.

kubernetes
# four service types:
# - ClusterIP (default): reachable inside the cluster
# - NodePort: exposed on each node's IP at a static port
# - LoadBalancer: cloud-provisioned external LB
# - ExternalName: DNS CNAME to an external host

# quick create
kubectl expose deployment nginx --port=80 --type=ClusterIP
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl expose deployment nginx --port=80 --type=LoadBalancer

# external name (no proxying, pure DNS)
kubectl create service externalname my-svc --external-name=db.example.com

Service ClusterIP

ClusterIP dá um IP virtual estável e um nome DNS dentro do cluster. O selector casa com os labels dos pods; o kube-proxy programa iptables/IPVS para balancear carga entre endpoints. Resolva via <svc>.<ns>.svc.cluster.local ou apenas <svc>.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
    - name: http
      port: 80          # service port
      targetPort: 80    # container port
      protocol: TCP
# DNS: nginx.default.svc.cluster.local
# short names also work: nginx, nginx.default
# kube-dns / CoreDNS resolves the service VIP

Service NodePort

NodePort abre a mesma porta estática (30000-32767) em cada nó. Tráfego para qualquer nó:nodePort alcança um pod (o kube-proxy pode redirecionar a um pod em outro nó). Útil quando você não pode provisionar um LB na nuvem; pareie com um LB externo para HA.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30080   # optional, 30000-32767 range
# reachable at <any-node-ip>:30080
# also still reachable via clusterIP:80

# get assigned nodePort
kubectl get svc nginx -o jsonpath='{.spec.ports[*].nodePort}'

Service LoadBalancer

LoadBalancer pede ao provedor de nuvem para provisionar um balanceador externo apontando para os nós. externalTrafficPolicy: Local preserva o IP de origem do cliente (sem SNAT), mas pula o balanceamento entre nós. STATUS mostra o IP externo atribuído quando pronto.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: LoadBalancer
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
  # cloud-specific annotations
  # annotations:
  #   service.beta.kubernetes.io/aws-load-balancer-type: nlb
  #   service.beta.kubernetes.io/azure-load-balancer-internal: "true"
  # externalTrafficPolicy: Local preserves client IP
  externalTrafficPolicy: Local
# status.ingress shows the external IP/hostname

Service headless

Um service headless (clusterIP: None) não tem VIP — o DNS retorna os IPs dos pods diretamente. Exigido pelo StatefulSet para que cada pod ganhe um nome DNS estável (pod-0.svc, pod-1.svc). Também usado por clientes que querem descobrir os backends por conta própria.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: nginx-headless
spec:
  clusterIP: None       # makes it headless
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
# DNS returns pod IPs directly (not a VIP)
# A records: nginx-headless.default.svc.cluster.local
#   -> 10.1.0.5, 10.1.0.6, 10.1.0.7
# used by StatefulSet for stable pod DNS:
#   <pod-name>.<svc-name>.default.svc.cluster.local

Endpoints e EndpointSlices

Endpoints/EndpointSlices listam os IPs dos pods que de fato recebem tráfego — só pods Ready aparecem. Se um service não tem endpoints, os pods não estão casando com o selector ou não estão Ready. EndpointSlices (v1) escalam melhor para services enormes e são o padrão.

kubernetes
# view endpoints backing a service
kubectl get endpoints nginx

# endpoint slices (newer, more scalable)
kubectl get endpointslices -l kubernetes.io/service-name=nginx

# endpoints track pods that match the selector
# AND pass readiness checks
kubectl describe endpoints nginx

# a service with no ready pods has no endpoints
# - check pod readiness if traffic is refused
# - EndpointSlices are grouped by address type (IPv4/IPv6)

# manually managed endpoints (selector-less service)
05

ConfigMap

Criando ConfigMap

ConfigMaps armazenam configuração não sensível como pares chave-valor. --from-literal para valores inline, --from-file para embutir arquivos inteiros (o nome do arquivo vira a chave). Útil para desacoplar config das imagens sem rebuild.

kubernetes
# from literal values
kubectl create configmap app-config \
  --from-literal=LOG_LEVEL=debug \
  --from-literal=ENABLE_FEATURE=true

# from a file (key = filename, value = contents)
kubectl create configmap app-config --from-file=app.properties

# from a directory (one key per file)
kubectl create configmap app-config --from-file=configs/

# from an env file
kubectl create configmap app-config --from-env-file=app.env

# from a file with a custom key
kubectl create configmap app-config --from-file=custom-key=app.properties

Manifest de ConfigMap

data guarda valores em string (cada chave vira uma env var ou um arquivo quando montado). Strings multilinha usam block scalars YAML (|). binaryData aceita base64 para blobs binários. O limite total é 1 MiB por ConfigMap.

kubernetes
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: "debug"
  ENABLE_FEATURE: "true"
  application.yml: |
    server:
      port: 8080
    logging:
      level: debug
binaryData:
  # base64-encoded binary values
  logo.png: iVBORw0KGgoAAAANSUhEUg...

Consumindo como variáveis de ambiente

envFrom injeta toda chave do ConfigMap como env var de uma vez. env com configMapKeyRef escolhe chaves individuais. optional: true permite que o pod inicie mesmo se o ConfigMap não existir. Atualizações no ConfigMap NÃO atualizam as env vars em pods em execução.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      env:
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: LOG_LEVEL
      envFrom:
        - configMapRef:
            name: app-config      # injects all keys as env vars
              optional: true      # pod starts even if CM missing

Consumindo como volume

Montar um ConfigMap como volume projeta cada chave como arquivo. Atualizações no ConfigMap eventualmente refletem nos arquivos montados (configurado pelo período de sync do kubelet) — mas as apps precisam reler. Mounts com subPath fixam uma única chave e NÃO atualizam.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      volumeMounts:
        - name: config
          mountPath: /etc/config
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: app-config
        items:                       # optional: pick subset
          - key: application.yml
            path: app.yml            # rename file
        defaultMode: 0644
# each ConfigMap key becomes a file under /etc/config

Atualização e reload

Arquivos de ConfigMap montados se renovam automaticamente (após o sync do kubelet), mas env vars são imutáveis pela vida do pod — reinicie os pods para capturar mudanças de env. rollout restart é a forma mais limpa de propagar atualizações de config a um Deployment.

kubernetes
# edit the configmap
kubectl edit configmap app-config

# patch a single key
kubectl patch configmap app-config \
  --type merge -p '{"data":{"LOG_LEVEL":"info"}}'

# mounted files update within ~kubelet sync period (default 60s)
# but env vars do NOT update in running pods

# force pods to pick up new config by rolling them
kubectl rollout restart deployment/app

# verify the new value on a pod
kubectl exec app -- printenv LOG_LEVEL

ConfigMap imutável

Definir immutable: true congela o ConfigMap — qualquer mudança exige delete + recriação. Isso reduz drasticamente o tráfego de watch kubelet-apiserver para configs grandes e estáveis (uma grande vitória de escalabilidade). Comum em produção para configs de app versionadas junto com a imagem.

kubernetes
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
immutable: true
data:
  LOG_LEVEL: "debug"
# once immutable, the only change allowed is delete + recreate
# benefits: kubelet does not watch it, lower apiserver load
# useful for large, stable configs in production

# make it mutable again
kubectl patch configmap app-config -p '{"immutable":false}'
# (this fails if currently immutable — must delete instead)
06

Secret

Criando Secret

Secrets armazenam dados sensíveis codificados em base64 (NÃO criptografados em repouso por padrão — habilite encryption at rest para produção). Use generic/Opaque para dados arbitrários, docker-registry para pulls de imagem, tls para TLS de Ingress. Nunca commite YAML de Secret no git.

kubernetes
# generic (opaque) from literals
kubectl create secret generic db-creds \
  --from-literal=username=admin \
  --from-literal=password='S3cur3!'

# from a file (e.g. SSH key, certificate)
kubectl create secret generic ssh-key --from-file=ssh-privatekey=~/.ssh/id_rsa

# docker registry secret (for private image registries)
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass \
  [email protected]

# TLS secret from cert/key files
kubectl create secret tls my-tls \
  --cert=fullchain.pem \
  --key=privkey.pem

Manifest de Secret

Valores de data devem estar codificados em base64 (echo -n 'value' | base64). stringData é uma conveniência que aceita texto puro e é mesclada em data no apply. O type Opaque é o padrão; tipos especializados (kubernetes.io/tls, kubernetes.io/dockerconfigjson) validam as chaves.

kubernetes
apiVersion: v1
kind: Secret
metadata:
  name: db-creds
type: Opaque
data:
  username: YWRtaW4=         # base64 of "admin"
  password: UzNjdXIzIQ==     # base64 of "S3cur3!"
# stringData accepts plaintext (auto-encoded on apply)
stringData:
  api-key: "live-key-xyz"
# encode on the command line:
# echo -n 'admin' | base64
# decode:
# echo 'YWRtaW4=' | base64 -d

Usando Secret como variável de ambiente

Consumir secrets como env vars é idêntico aos ConfigMaps, mas usa secretKeyRef/secretRef. Note que env vars são visíveis via /proc/1/environ e para qualquer processo no contêiner — prefira mounts de volume para dados altamente sensíveis.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-creds
              key: password
      envFrom:
        - secretRef:
            name: db-creds      # injects all keys
              optional: true

Usando Secret como volume

Secrets montados são projetados como arquivos num volume tmpfs (memória) — nunca escritos no disco do nó. defaultMode 0400 restringe o acesso. Secrets montados SIM atualizam quando o Secret muda (após o sync do kubelet), diferente de secrets em env vars.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      volumeMounts:
        - name: secrets
          mountPath: /etc/secrets
          readOnly: true
  volumes:
    - name: secrets
      secret:
        secretName: db-creds
        defaultMode: 0400       # restrict permissions
        items:
          - key: password
            path: db-password   # written to /etc/secrets/db-password
# memory-backed tmpfs, never written to disk on the node

ImagePullSecret

imagePullSecrets autenticam em registries privados ao puxar imagens. Anexar a um ServiceAccount aplica a cada pod que usa aquele SA — o padrão preferido. O tipo de secret docker-registry produz o payload .dockerconfigjson correto automaticamente.

kubernetes
# attach to a pod
apiVersion: v1
kind: Pod
metadata:
  name: private-app
spec:
  imagePullSecrets:
    - name: regcred
  containers:
    - name: app
      image: registry.example.com/myapp:1.0

# attach to a service account (auto-applied to all pods using it)
kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

# verify
kubectl get sa default -o jsonpath='{.imagePullSecrets}'

Tipos de Secret

Tipos de secret especializados habilitam validação e integração: tls para Ingress, dockerconfigjson para pulls de imagem, service-account-token montado automaticamente nos pods. Usar o tipo certo garante que as chaves sejam validadas e consumidas pelos controllers corretos.

kubernetes
# Opaque (default) — arbitrary key-value
type: Opaque

# kubernetes.io/service-account-token — auto for SAs
type: kubernetes.io/service-account-token

# kubernetes.io/dockerconfigjson — registry auth
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64>

# kubernetes.io/tls — for Ingress TLS
type: kubernetes.io/tls
data:
  tls.crt: <base64>
  tls.key: <base64>

# kubernetes.io/basic-auth
type: kubernetes.io/basic-auth
stringData:
  username: admin
  password: pass
07

Namespace

Criando Namespace

Namespaces particionam um cluster para múltiplas equipes ou ambientes (dev/stage/prod). Nomes de recursos devem ser únicos dentro de um namespace. Alguns recursos (Nodes, PVs, StorageClasses) têm escopo de cluster e não são namespaced.

kubernetes
# imperative
kubectl create namespace dev

# declarative
apiVersion: v1
kind: Namespace
metadata:
  name: dev
  labels:
    environment: development
    team: platform

# apply
kubectl apply -f namespace.yaml

# list namespaces
kubectl get namespaces

# set default namespace for current context
kubectl config set-context --current --namespace=dev

ResourceQuota

ResourceQuota limita o uso agregado de recursos num namespace — requests/limits totais de CPU/memória, contagens de objetos (pods, PVCs, services, deployments). Essencial em clusters multi-tenant para impedir que uma equipe mate os outros. Pods sem requests explícitos são rejeitados quando a quota está definida.

kubernetes
apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-quota
  namespace: dev
spec:
  hard:
    requests.cpu: "10"
    requests.memory: 20Gi
    limits.cpu: "20"
    limits.memory: 40Gi
    pods: "50"
    services.loadbalancers: "2"
    persistentvolumeclaims: "10"
    count/deployments.apps: "5"
# limits total aggregate resource use in the namespace

LimitRange

LimitRange define defaults e limites por recurso: requests/limits padrão para pods que não os especificam, mais min/max para conter valores absurdos. Combina com ResourceQuota — sem requests padrão, a quota rejeitaria cada pod que esquecesse de defini-los.

kubernetes
apiVersion: v1
kind: LimitRange
metadata:
  name: default-limits
  namespace: dev
spec:
  limits:
    - type: Container
      default:               # default limits (if unset)
        cpu: 500m
        memory: 512Mi
      defaultRequest:        # default requests (if unset)
        cpu: 100m
        memory: 128Mi
      max:                   # max allowed limits
        cpu: "2"
        memory: 2Gi
      min:                   # min allowed requests
        cpu: 50m
        memory: 64Mi
    - type: PersistentVolumeClaim
      max:
        storage: 100Gi
      min:
        storage: 1Gi

Excluindo namespace e finalizers

Excluir um namespace faz cascata nos seus recursos. Um namespace preso em Terminating geralmente tem um finalizer que não consegue completar — um APIService indisponível (por exemplo, metrics-server) ou um CRD cujo controller se foi. Remover o finalizer força a conclusão, mas pode vazar recursos externos.

kubernetes
# delete a namespace (cascades all resources in it)
kubectl delete namespace dev

# if stuck in Terminating, inspect finalizers
kubectl get namespace dev -o yaml

# remove finalizer to force completion (DANGEROUS)
kubectl patch namespace dev -p '{"metadata":{"finalizers":null}}'

# resources that block deletion:
# - APIService unavailable (metrics-server removed)
# - custom resources whose CRD is gone
# - PVCs with attached PVs

# check what's still in the namespace
kubectl api-resources --verbs=list --namespaced -o name \
  | xargs -n 1 kubectl get -n dev --ignore-not-found

Namespaces padrão

kube-system roda o control plane e os add-ons (DNS, kube-proxy, CNI). kube-public guarda dados de bootstrap legíveis por usuários não autenticados. kube-node-lease armazena heartbeats de nós como objetos Lease, por desempenho. default é onde seus workloads caem se você não especificar um namespace.

kubernetes
# built-in namespaces
kubectl get namespaces
# NAME              STATUS   AGE
# default           Active   30d   <- user workloads land here
# kube-system       Active   30d   <- control plane / addons
# kube-public       Active   30d   <- publicly readable (bootstrap)
# kube-node-lease   Active   30d   <- node heartbeats (leases)

# kube-system holds:
# - kube-dns / CoreDNS
# - kube-proxy
# - metrics-server
# - CNI, CSI, cloud provider controllers

# kube-public is readable by all (used for cluster info discovery)

Namespaced vs cluster-scoped

A maioria dos recursos de workload é namespaced; infraestrutura (nodes, PVs, StorageClasses, ClusterRoles) tem escopo de cluster. Um Service só pode mirar pods no próprio namespace. -A é a abreviação de --all-namespaces — essencial para visibilidade em o cluster.

kubernetes
# which resources are namespaced?
kubectl api-resources --namespaced=true
kubectl api-resources --namespaced=false

# namespaced: pods, services, deployments, configmaps, secrets
# cluster-scoped: nodes, namespaces, PVs, StorageClasses, ClusterRoles

# access across namespaces:
# - a Service selector only matches pods in the SAME namespace
# - cross-namespace refs require special controllers (e.g. external-dns)

# list resources across all namespaces
kubectl get pods --all-namespaces
kubectl get pods -A   # shorthand
08

Labels e selectors

Sintaxe de labels

Labels são pares chave-valor usados para identificar e agrupar recursos. Chaves podem ter um prefixo opcional (um subdomínio DNS, por exemplo, app.kubernetes.io/). Labels servem para consultar/filtrar, diferente de annotations, que são para metadados arbitrários não identificadores.

kubernetes
# labels are key=value pairs
# key: prefix (optional DNS subdomain) + name
# value: string, up to 63 chars

metadata:
  labels:
    app: nginx
    tier: frontend
    env: prod
    app.kubernetes.io/name: nginx
    app.kubernetes.io/version: "1.25"

# view labels
kubectl get pods --show-labels

# add/overwrite a label
kubectl label pod nginx env=prod
kubectl label pod nginx env=staging --overwrite

# remove a label (trailing dash)
kubectl label pod nginx env-

Selectors de igualdade e conjunto

Dois sabores de selector: baseado em igualdade (=, ==, !=) e baseado em conjunto (in, notin, exists, !exists). Múltiplas condições separadas por vírgula são combinadas com AND. Services e Deployments usam selectors de igualdade no YAML; kubectl -l suporta ambos.

kubernetes
# equality-based: = == !=
kubectl get pods -l app=nginx
kubectl get pods -l env!=dev
kubectl get pods -l 'app=nginx,env=prod'   # AND of conditions

# set-based: in, notin, exists
kubectl get pods -l 'env in (prod,staging)'
kubectl get pods -l 'env notin (dev)'
kubectl get pods -l 'tier'                 # key exists
kubectl get pods -l '!canary'              # key does not exist

# combine equality and set-based
kubectl get pods -l 'app=nginx,env in (prod,staging)'

Rotulando recursos

label muta metadados identificadores — use para qualquer coisa que selectors devam casar. annotate é para metadados não identificadores (owner, ticket, descrição, dicas de ferramentas). Nós costumam ser rotulados com dicas de topologia ou hardware para dirigir o agendamento.

kubernetes
# label a pod
kubectl label pod nginx app=nginx tier=web

# label all pods matching a selector
kubectl label pods -l app=oldapp app=newapp --overwrite

# label a node (for scheduling hints)
kubectl label node node-1 disktype=ssd

# remove a node label
kubectl label node node-1 disktype-

# list nodes by label
kubectl get nodes -l disktype=ssd

# annotate (non-identifying metadata)
kubectl annotate pod nginx owner=alice
kubectl annotate pod nginx description="web server"

Selectors em manifests

No YAML, selectors usam matchLabels (igualdade) e matchExpressions (baseado em conjunto, com In/NotIn/Exists/DoesNotExist). Para Deployments, o selector é imutável após a criação — e os labels do template de pod devem casar com ele. Services só suportam matchLabels.

kubernetes
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:            # equality-based
      app: nginx
    matchExpressions:       # set-based (optional)
      - key: env
        operator: In
        values: [prod, staging]
      - key: tier
        operator: Exists
  template:
    metadata:
      labels:
        app: nginx          # MUST match selector
        env: prod
        tier: web

Annotations

Annotations guardam metadados não identificadores usados por ferramentas — o kubectl apply armazena a config last-applied, o cert-manager lê dicas de issuer, o Prometheus lê a config de scrape, controllers guardam estado de rollout. Diferente de labels, os valores de annotations podem ser blobs JSON grandes.

kubernetes
metadata:
  annotations:
    kubernetes.io/change-cause: "bump nginx to 1.26"
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1",...}
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

# view annotations
kubectl get pod nginx -o jsonpath='{.metadata.annotations}'

# annotate
kubectl annotate pod nginx owner=team-platform

# remove an annotation (trailing dash)
kubectl annotate pod nginx owner-

Labels recomendados

Os labels app.kubernetes.io/* são um vocabulário compartilhado para que ferramentas (Helm, operators, dashboards) agrupem os recursos de uma aplicação. name+instance identificam unicamente uma release; component/part-of descrevem a hierarquia; managed-by/created-by rastreiam a propriedade.

kubernetes
# shared recommended labels (app.kubernetes.io/*)
metadata:
  labels:
    app.kubernetes.io/name: nginx
    app.kubernetes.io/instance: nginx-prod
    app.kubernetes.io/version: "1.25"
    app.kubernetes.io/component: web
    app.kubernetes.io/part-of: storefront
    app.kubernetes.io/managed-by: helm
    app.kubernetes.io/created-by: controller-manager

# Helm applies these automatically; kubectl doesn't.
# They unify how tooling identifies an application's resources
# across Deployments, Services, Ingresses, ConfigMaps, etc.
09

ReplicaSet

Manifest de ReplicaSet

Um ReplicaSet mantém um conjunto estável de pods réplica que casam com um selector — recria pods quando são excluídos ou falham. Você quase sempre usa um Deployment em vez disso, que envolve um ReplicaSet e adiciona rolling updates e rollbacks.

kubernetes
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
# kubectl get rs
# kubectl describe rs nginx

Como o ReplicaSet funciona

O controller do ReplicaSet reconcilia a contagem desejada vs real de pods usando o selector. Cada pod recebe um ownerReference apontando ao RS — é por isso que kubectl get pod mostra 'Owned by ReplicaSet/nginx'. Escalar só muda a contagem desejada.

kubernetes
# the controller loop:
# 1. count pods matching selector
# 2. if fewer than replicas -> create from template
# 3. if more than replicas -> delete excess (arbitrary order)

# owned-by reference on each pod
kubectl get pod -l app=nginx -o jsonpath='{.items[*].metadata.ownerReferences}'

# if you delete a pod, the RS creates a new one immediately
kubectl delete pod <pod-name>
kubectl get pods -l app=nginx

# scale by editing replicas
kubectl scale rs nginx --replicas=5

ReplicaSet vs ReplicationController

ReplicationController (a primitiva v1 original) só suporta selectors de igualdade e está descontinuado. ReplicaSet (apps/v1) adiciona selectors baseados em conjunto. Na prática, use Deployment — ele gerencia ReplicaSets para você e fornece rolling updates/rollbacks.

kubernetes
# ReplicationController (v1, legacy): equality-only selectors
# ReplicaSet (apps/v1, modern): set-based selectors (in, notin, exists)

# ReplicationController is deprecated; do not use.
apiVersion: v1
kind: ReplicationController      # legacy
# ...
# ReplicaSet is the successor:
apiVersion: apps/v1
kind: ReplicaSet                 # modern
# ...
# Deployment wraps ReplicaSet and is the recommended primitive:
apiVersion: apps/v1
kind: Deployment                 # use this in practice

Escalonamento manual

kubectl scale muda o campo replicas. Se um HPA mirar o mesmo recurso, ele sobrescreverá o escalonamento manual na próxima reconciliação. Prefira kubectl scale para casos pontuais e HPA para workloads elásticos contínuos.

kubernetes
# scale a replicaset directly
kubectl scale rs nginx --replicas=5

# scale via patch
kubectl patch rs nginx -p '{"spec":{"replicas":5}}'

# scale multiple resources at once
kubectl scale deployment nginx deployment web --replicas=3

# scale by referencing a file
kubectl scale --replicas=5 -f nginx.yaml

# the autoscaler (HPA) will override manual scaling
# if it targets the same resource

Mudanças de template e adoção

Diferente de um Deployment, um ReplicaSet puro não lança mudanças no template de pod — só pods recém-criados (após delete/scale-up) recebem a spec nova. Um ReplicaSet adotará qualquer pod órfão que case com seu selector, o que pode causar comportamento surpreendente.

kubernetes
# changing the pod template does NOT update existing pods
# (unlike a Deployment, a bare ReplicaSet won't roll out)
kubectl edit rs nginx   # change image -> new pods use it, old ones don't

# delete old pods to force them onto the new template
kubectl delete pods -l app=nginx

# a ReplicaSet will ADOPT existing pods that match its selector
# even pods created independently — useful (and dangerous)

# orphaned pods (no owner) matching the selector are taken over
kubectl get pods -l app=nginx --show-kind

Removendo pods de um ReplicaSet

Para remover um pod sem que o ReplicaSet o recrie, escale o RS para 0 primeiro, ou remova os ownerReferences do pod para que o RS não o possua mais. Útil para depurar uma instância específica ou extrair logs antes da limpeza.

kubernetes
# detaching a pod from its ReplicaSet (so it isn't replaced)
kubectl patch pod <pod-name> \
  -p '{"metadata":{"ownerReferences":[]}}'

# now deleting this pod won't trigger a replacement,
# because the RS no longer owns it

# or scale the RS to 0 first, then delete
kubectl scale rs nginx --replicas=0
kubectl delete pod <pod-name>

# useful for debugging a specific failing pod instance
# without the RS immediately recreating it
10

StatefulSet

Manifest de StatefulSet

StatefulSet dá aos pods uma identidade estável (nome, hostname, armazenamento) e deploy/escala ordenados. Exige um serviceName headless. volumeClaimTemplates cria um PVC dedicado por pod — então, mesmo que pod-0 seja remarcado, ele reanexa o mesmo volume.

kubernetes
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
spec:
  serviceName: mysql          # required: headless service
  replicas: 3
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:8
          ports:
            - containerPort: 3306
          volumeMounts:
            - name: data
              mountPath: /var/lib/mysql
  volumeClaimTemplates:       # one PVC per pod
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Identidade estável

Cada pod ganha um nome ordinal estável (mysql-0, mysql-1, …) e um nome DNS estável via o service headless. Quando um nó falha, pod-0 é remarcado em outro lugar, mas mantém seu nome e reanexa seu volume — crítico para bancos de dados clusterizados que dependem de associação estável.

kubernetes
# pods are named <statefulset-name>-<ordinal>
# mysql-0, mysql-1, mysql-2
kubectl get pods -l app=mysql

# each pod has stable DNS (via the headless service):
#   mysql-0.mysql.default.svc.cluster.local
#   mysql-1.mysql.default.svc.cluster.local

# stable hostname inside the pod:
kubectl exec mysql-0 -- hostname
# -> mysql-0

# ordinal index also exposed:
kubectl exec mysql-0 -- sh -c 'echo $HOSTNAME'
# -> mysql-0

# pod identity persists across reschedules

Armazenamento estável

volumeClaimTemplates gera um PVC por pod com nome previsível (data-mysql-0, …). PVCs sobrevivem à exclusão do pod e do StatefulSet — isso evita perda de dados, mas significa que você deve excluir PVCs explicitamente para liberar armazenamento. O mesmo volume sempre reanexa ao mesmo pod ordinal.

kubernetes
# one PVC per pod, named <volumeClaimTemplate-name>-<pod-name>
kubectl get pvc
# NAME        STATUS   VOLUME       CAPACITY   ...
# data-mysql-0   Bound   pvc-aaa      10Gi
# data-mysql-1   Bound   pvc-bbb      10Gi
# data-mysql-2   Bound   pvc-ccc      10Gi

# when pod-0 is rescheduled, it re-binds data-mysql-0
# deleting the StatefulSet does NOT delete PVCs by default
# (protects from accidental data loss)

# to actually delete the data:
kubectl delete pvc data-mysql-0 data-mysql-1 data-mysql-2

Deploy ordenado e gerenciamento de pods

OrderedReady (padrão) cria pods estritamente na ordem 0→1→2 e exclui na ordem inversa — exigido por sistemas que precisam de um primário para bootstrap antes das réplicas. Parallel cria/exclui os pods simultaneamente — mais rápido para stores simétricos fragmentados (Cassandra, Elasticsearch).

kubernetes
spec:
  podManagementPolicy: OrderedReady   # default: strict order
  # podManagementPolicy: Parallel      # create/delete all at once

  replicas: 3
  # OrderedReady: create pod-0, then pod-1, then pod-2 (each waits for Ready)
  # deletion is reverse: pod-2, pod-1, pod-0

  # Parallel: all pods created/deleted simultaneously
  # identity and storage remain stable either way

# check policy
kubectl get statefulset mysql -o jsonpath='{.spec.podManagementPolicy}'

# parallel is great for sharded stores that don't need bootstrap order

Rolling updates

Rolling updates do StatefulSet vão na ordem ordinal inversa (N-1 até 0). partition permite canary nos pods de ordinal mais alto primeiro. OnDelete pausa as atualizações até você excluir manualmente um pod — útil para migrações controladas. Rollouts são mais lentos que Deployments devido à ordenação.

kubernetes
spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 2          # only pods with ordinal >= 2 update
      maxUnavailable: 1     # (default 1) allowed down
  # type: OnDelete  -> only update when pod is manually deleted

# partition enables canaries: set partition=N to update
# only the top N pods; lower to 0 to roll out to all.

kubectl rollout status statefulset/mysql
# waits for all pods to be updated

# StatefulSets also support rollout history/undo,
# but only when the change is in the pod template

Associação ao service headless

O service headless (clusterIP: None) referenciado por spec.serviceName é o que faz o DNS estável por pod funcionar. Sem ele, o StatefulSet não cria pods. Clientes resolvem o nome do service para round-robin, ou pod-0.svc para fixar um primário. Não esqueça de criar o Service.

kubernetes
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  clusterIP: None         # headless
  selector:
    app: mysql
  ports:
    - port: 3306
---
# StatefulSet references this service via spec.serviceName
# this gives each pod a stable DNS:
#   mysql-0.mysql.default.svc.cluster.local

# clients can:
# - resolve mysql -> any pod IP (load-balanced by DNS round-robin)
# - resolve mysql-0.mysql -> pod-0's IP (pin to a specific replica)

# required: serviceName MUST match the headless service name
11

DaemonSet

Manifest de DaemonSet

Um DaemonSet roda exatamente um pod por nó (respeitando suas restrições de agendamento). Perfeito para agentes no nível do nó: coletores de log, monitoramento, armazenamento, CNI, ingress controllers. Nós novos recebem um pod automaticamente; nós excluídos têm os seus coletados por garbage collection.

kubernetes
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: log-agent
  namespace: kube-system
  labels:
    app: log-agent
spec:
  selector:
    matchLabels:
      app: log-agent
  template:
    metadata:
      labels:
        app: log-agent
    spec:
      containers:
        - name: agent
          image: fluent-bit:2.2
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
      # one pod per (matching) node automatically

Agendamento por nó

nodeSelector é a restrição mais simples (os pares chave=valor devem casar). nodeAffinity adiciona operadores In/NotIn/Exists e regras preferred/required. DaemonSets respeitam isso como qualquer pod — combinado com tolerations você pode rodar agentes também em nós de control-plane com taint.

kubernetes
spec:
  template:
    spec:
      nodeSelector:                # simplest: must match all
        disktype: ssd

      # more flexible affinity
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: kubernetes.io/os
                    operator: In
                    values: [linux]

      # only run on nodes labeled role=logging
      nodeSelector:
        role: logging

      tolerations:                 # tolerate tainted nodes
        - key: node-role.kubernetes.io/control-plane
          operator: Exists

Estratégia de atualização

RollingUpdate (padrão) atualiza os pods nó por nó, limitado por maxUnavailable (pode ser número ou %). OnDelete pausa as atualizações até você excluir manualmente cada pod — útil quando o controle nó a nó é exigido. maxSurge assume 0 por padrão (DaemonSets raramente querem pods extras).

kubernetes
spec:
  updateStrategy:
    type: RollingUpdate           # default
    rollingUpdate:
      maxUnavailable: 1           # how many nodes update at once
      maxSurge: 0                 # (default 0) no extra pods
  # type: OnDelete               # only update when old pod is deleted

# trigger an update (e.g. new image)
kubectl set image daemonset/log-agent agent=fluent-bit:2.3

# watch rollout
kubectl rollout status daemonset/log-agent -n kube-system

# rollout restart (recreate pods on every node)
kubectl rollout restart daemonset/log-agent -n kube-system

Taints e tolerations

Taints repelem pods; tolerations permitem que pods específicos ignorem um taint. Nós de control-plane têm o taint NoSchedule para que workloads de usuário não caiam lá — agentes no nível do nó toleram isso para rodar em toda parte. NoExecute também expulsa pods não tolerantes já em execução.

kubernetes
# inspect a node's taints
kubectl describe node node-1 | grep Taints
# Taints: node-role.kubernetes.io/control-plane:NoSchedule

# tolerate control-plane so the agent runs there too
spec:
  template:
    spec:
      tolerations:
        - key: node-role.kubernetes.io/control-plane
          operator: Exists
          effect: NoSchedule
        - key: node.kubernetes.io/disk-pressure
          operator: Exists
          effect: NoExecute

# taint effects: NoSchedule | NoExecute | PreferNoSchedule

Casos de uso de DaemonSet

DaemonSets são a forma de deploy padrão para infraestrutura no nível do nó. Frequentemente precisam de acesso privilegiado (hostNetwork, hostPID, hostPath) para fazer seu trabalho — conceda isso deliberadamente e só a imagens confiáveis. Nunca use um DaemonSet para workloads de app que devem escalar horizontalmente.

kubernetes
# classic DaemonSet workloads (node-level agents):
# - log collection:        fluent-bit, filebeat, promtail
# - monitoring:            node-exporter, datadog-agent
# - networking:            kube-proxy, CNI plugins, ingress controllers
# - storage:               CSI node plugins, Rook/Ceph
# - security:              Falco, Tetragon, runtime security
# - GPU/FPGA drivers:      nvidia-device-plugin

# storage / device plugins often need:
spec:
  template:
    spec:
      hostNetwork: true        # use node network namespace
      hostPID: true            # see node processes
      hostPath:                # mount node paths
        - path: /var/log
        - path: /var/lib/docker/containers

Status do DaemonSet

DESIRED iguala ao número de nós que casam com as restrições de agendamento; CURRENT/READY mostram quantos pods existem e estão passando no readiness. -o wide é a forma mais fácil de ver em que nó cada pod caiu. DaemonSets suportam histórico/undo de rollout como os Deployments.

kubernetes
# desired = number of matching nodes
kubectl get daemonset log-agent -n kube-system
# NAME         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE
# log-agent    5         5         5       5            5

# show which nodes a DaemonSet pod landed on
kubectl get pods -n kube-system -l app=log-agent -o wide

# rollout history
kubectl rollout history daemonset/log-agent -n kube-system

# rollback
kubectl rollout undo daemonset/log-agent -n kube-system

# check a per-node pod's logs
kubectl logs -n kube-system log-agent-abcde
12

Job e CronJob

Manifest de Job

Um Job roda pods até que um número especificado deles complete com sucesso (completions). restartPolicy deve ser Never ou OnFailure (não Always — isso é para workloads de longa duração). backoffLimit limita as retentativas; activeDeadlineSeconds limita o tempo total de execução.

kubernetes
apiVersion: batch/v1
kind: Job
metadata:
  name: pi
spec:
  completions: 1              # how many successful pods needed
  parallelism: 1              # how many run concurrently
  backoffLimit: 6             # retries before marking Failed
  activeDeadlineSeconds: 600  # hard timeout
  template:
    spec:
      restartPolicy: Never    # OnFailure | Never
      containers:
        - name: pi
          image: perl
          command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
# kubectl get jobs
# kubectl logs job/pi

Completions e paralelismo do Job

completions = quantos pods bem-sucedidos satisfazem o Job; parallelism = quantos rodam concorrentemente. Jobs indexados atribuem a cada pod um ordinal (env var JOB_COMPLETION_INDEX) — ótimo para processamento em lote fragmentado em que cada pod possui uma fatia. NonIndexed (padrão) só precisa de N sucessos de qualquer origem.

kubernetes
spec:
  completions: 5         # 5 successful pods total
  parallelism: 2         # 2 pods run at a time
  backoffLimit: 4
  # default completionMode: NonIndexed (any 5 successes)
  completionMode: Indexed
  # Indexed: pods get 0..N-1 in JOB_COMPLETION_INDEX env,
  # useful for sharded work (each pod handles one shard)

  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: worker
          image: worker:1.0

# set via kubectl
kubectl create job pi --image=perl -- perl -Mbignum=bpi -wle "print bpi(2000)"

Backoff e timeouts do Job

backoffLimit retenta pods que falharam (backoff exponencial). activeDeadlineSeconds é o teto rígido — se atingido, o Job é marcado como Failed mesmo com retentativas restantes. ttlSecondsAfterFinished limpa automaticamente Jobs concluídos. podFailurePolicy (1.31+) permite falhar rápido em certos códigos de saída ou ignorar expulsões voluntárias.

kubernetes
spec:
  backoffLimit: 6            # default 6, retries on failure
  activeDeadlineSeconds: 3600  # hard wall, even if retries remain
  ttlSecondsAfterFinished: 86400  # auto-delete Job 1 day after done
  startingDeadlineSeconds: 300  # (CronJob only) miss window

  # pod failure handling (v1.31+):
  podFailurePolicy:
    rules:
      - action: FailJob
        onExitCodes:
          operator: In
          values: [42]      # exit 42 -> don't retry, fail fast
      - action: Count
        onPodConditions:
          - type: DisruptionTarget   # don't count voluntary evictions

  template:

Manifest de CronJob

Um CronJob cria Jobs num cronograma cron (5 campos: minuto hora dia mês dia-da-semana). concurrencyPolicy controla execuções sobrepostas: Forbid pula uma nova execução se a anterior ainda está em andamento; Replace mata a antiga e inicia a nova. timeZone (1.27+) elimina a necessidade de aritmética UTC.

kubernetes
apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup
spec:
  schedule: "0 2 * * *"          # 5-field cron: 02:00 daily
  timeZone: "Asia/Shanghai"
  concurrencyPolicy: Forbid      # Allow | Forbid | Replace
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  startingDeadlineSeconds: 200
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backup
              image: backup:1.0
# kubectl get cronjob
# kubectl get jobs

Suspend e histórico do CronJob

suspend: true pausa um CronJob sem excluí-lo — prático durante incidentes. Limites de histórico mantêm a lista de Jobs manejável (padrão 3 sucessos / 1 falha). kubectl create job --from=cronjob/X roda o template imediatamente, perfeito para gatilhos manuais ou preencher execuções perdidas.

kubernetes
spec:
  schedule: "*/5 * * * *"
  suspend: true                # pause without deleting the CronJob
  successfulJobsHistoryLimit: 3   # default 3
  failedJobsHistoryLimit: 1       # default 1

# toggle suspend
kubectl patch cronjob backup -p '{"spec":{"suspend":true}}'
kubectl patch cronjob backup -p '{"spec":{"suspend":false}}'

# trigger a one-off run immediately
kubectl create job --from=cronjob/backup manual-backup

# clean up old jobs manually
kubectl delete jobs -l job-name=backup

Cronograma e casos extremos do CronJob

Cron padrão de 5 campos. Quando tanto o dia-do-mês quanto o dia-da-semana estão restritos, o cron dispara em QUALQUER correspondência (semântica OU) — uma pegadinha clássica. Se o horário agendado de um CronJob for perdido além de startingDeadlineSeconds, aquela execução é pulada em vez de preenchida.

kubernetes
# cron syntax (5 fields):
# ┌───────────── minute (0-59)
# │ ┌───────────── hour (0-23)
# │ │ ┌───────────── day of month (1-31)
# │ │ │ ┌───────────── month (1-12)
# │ │ │ │ ┌───────────── day of week (0-6, Sun=0)
# "*/5 * * * *"      every 5 minutes
# "0 2 * * *"        daily at 02:00
# "0 0 * * 0"        weekly Sunday midnight
# "0 0 1 * *"        monthly on the 1st
# "30 3-5 * * *"     03:30, 04:30, 05:30

# gotchas:
# - day-of-month AND day-of-week both set => OR (not AND)
# - if startingDeadlineSeconds is missed, the run is skipped
# - control-plane restart can skip a tick if the schedule is missed
# - cron interprets literal fields; prefer timeZone over UTC math
13

Ingress

Manifest de Ingress

Ingress expõe rotas HTTP/HTTPS de fora do cluster para Services, gerenciadas por um Ingress controller (nginx, traefik, ALB, …). ingressClassName seleciona qual controller o trata. Cada regra mapeia um host + path para um backend service+porta.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api
                port:
                  number: 8080

Ingress com TLS

Entradas tls vinculam um secret TLS (type kubernetes.io/tls, contendo tls.crt + tls.key) a um ou mais hosts. O Ingress controller termina o TLS e faz proxy de HTTP puro para o backend. O cert-manager pode emitir e rotacionar certificados Let's Encrypt automaticamente com base na annotation cluster-issuer.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-tls
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - app.example.com
        - www.example.com
      secretName: web-tls-secret   # kubernetes.io/tls secret
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

# auto-issue certs with cert-manager:
# annotations:
#   cert-manager.io/cluster-issuer: letsencrypt-prod

Regras de Ingress e default backend

defaultBackend trata o tráfego que não casa com nenhuma regra (sem host ou path não correspondido). Múltiplas regras permitem que um Ingress roteie muitos virtual hosts. Cada regra pode ter múltiplos backends de path — um único Ingress pode servir toda a topologia de roteamento de uma aplicação.

kubernetes
spec:
  ingressClassName: nginx
  defaultBackend:                # catch-all for unmatched traffic
    service:
      name: default-svc
      port:
        number: 80
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service: { name: api, port: { number: 8080 } }
    - host: blog.example.com     # different host -> different svc
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: { name: blog, port: { number: 80 } }

IngressClass

Um IngressClass declara um controller (por exemplo, k8s.io/ingress-nginx). Ingresses referenciam-no via spec.ingressClassName para que múltiplos controllers possam coexistir. Exatamente uma classe pode ser marcada como padrão com a annotation is-default-class — Ingresses novos sem classe explícita a usam.

kubernetes
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/ingress-nginx

# an Ingress picks a class via spec.ingressClassName
# (replaces the deprecated kubernetes.io/ingress.class annotation)

# multiple IngressClasses in one cluster:
# - nginx    (community ingress-nginx)
# - traefik  (Traefik controller)
# - alb      (AWS ALB)
# only one IngressClass can be marked default

Tipos de path

Exact casa o path verbatim; Prefix casa segmentos inteiros de path (/api casa /api e /api/foo, mas não /apix). ImplementationSpecific delega ao controller — por exemplo, regex do nginx. Sempre prefira Prefix ou Exact para comportamento portátil; ImplementationSpecific prende você a um controller.

kubernetes
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /api/v1
            pathType: Exact        # only /api/v1 (exact match)
            backend: ...
          - path: /api
            pathType: Prefix       # /api, /api/, /api/x (prefix match)
            backend: ...
          - path: /old
            pathType: ImplementationSpecific  # controller decides
            backend: ...

# Prefix matches path segments, not raw string prefix:
# /api   matches /api, /api/, /api/x  but NOT /apix
# Exact  matches the path verbatim
# ImplementationSpecific defers to the controller

Annotations (Nginx Controller)

Annotations específicas de controller configuram comportamento além da spec padrão de Ingress. ingress-nginx tem dezenas: rewrite-target, ssl-redirect, body-size, timeouts, CORS, basic auth, snippets de configuração. São específicas do controller — portar para outro controller exige reescrevê-las.

kubernetes
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  annotations:
    kubernetes.io/ingress.class: nginx          # legacy form
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.example.com"
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "X-Frame-Options: DENY";
spec:
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /v1(/|$)(.*)
            pathType: ImplementationSpecific
            backend:
              service: { name: api, port: { number: 8080 } }
14

Volume (PV/PVC)

Manifest de PersistentVolume

Um PersistentVolume (PV) é uma peça de armazenamento de escopo de cluster, provisionada por um admin ou dinamicamente por um StorageClass. accessModes descrevem como pode ser montado. reclaimPolicy controla o que acontece com o armazenamento quando o PVC é liberado.

kubernetes
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-1
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce        # RWO: one node R/W
  persistentVolumeReclaimPolicy: Retain   # Retain | Delete | Recycle
  storageClassName: manual
  hostPath:                # for dev only (single node)
    path: /mnt/data
  # nfs:
  #   server: 10.0.0.1
  #   path: /export/data
  # csi:
  #   driver: ebs.csi.aws.com
  #   volumeHandle: vol-xxxx

Manifest de PersistentVolumeClaim

Um PersistentVolumeClaim (PVC) é uma requisição namespaced de armazenamento. O controller o vincula a um PV correspondente (accessModes, capacidade suficiente, mesmo StorageClass). Com um StorageClass padrão, deixar storageClassName vazio dispara provisionamento dinâmico.

kubernetes
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-claim
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 5Gi
  volumeMode: Filesystem     # Filesystem | Block
  selector:                  # optional: filter PVs by labels
    matchLabels:
      disktype: ssd
# kubectl get pvc
# STATUS: Pending -> Bound once a matching PV is found

Modos de acesso

AccessModes descrevem a semântica de montagem — mas o suporte real depende do backend de armazenamento. EBS/GCE PD/Azure Disk são só RWO. RWX (leitura/escrita multi-nó) precisa de NFS, CephFS ou um filesystem distribuído. RWOP (1.27+) restringe a um pod, mesmo no mesmo nó.

kubernetes
# four access modes (support is driver-specific):
# - ReadWriteOnce  (RWO):  mounted R/W by ONE node
# - ReadOnlyMany   (ROX):  mounted R/O by MANY nodes
# - ReadWriteMany  (RWX):  mounted R/W by MANY nodes
# - ReadWriteOncePod (RWOP): mounted R/W by ONE pod (1.27+)

# examples by backend:
# AWS EBS, GCE PD, Azure Disk:  RWO only
# NFS:                          RWO, ROX, RWX
# CephFS, Portworx:             RWO, RWX
# Block volumes:                RWO

# RWX is required for pods on different nodes
# to share the same volume (e.g. read-only assets)

Política de reclaim

Retain mantém os dados por segurança — você precisa apagar manualmente e re-vincular o PV. Delete (padrão para provisionamento dinâmico) apaga tanto o PV quanto o armazenamento subjacente quando o PVC vai embora. Recycle está descontinuado. Um PV Released com Retain precisa do claimRef limpo antes de re-vincular.

kubernetes
# what happens when a PVC is deleted:
# - Retain:   PV stays, data preserved; PV must be manually
#             reclaimed (delete data, then delete PV) before reuse
# - Delete:   PV and the underlying storage are deleted (dynamic only)
# - Recycle:  deprecated; ran scrub on the volume

# change policy on an existing PV
kubectl patch pv pv-1 -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# a released PV (PVC deleted, policy Retain) is stuck:
#   phase=Released, claimRef still set
# to reuse: clear claimRef
kubectl patch pv pv-1 --type json -p '[{"op":"remove","path":"/spec/claimRef"}]'

PVC num Pod

Monte um PVC como qualquer volume via persistentVolumeClaim.claimName. subPath monta um subdiretório — prático para compartilhar um volume entre pods/paths. Volumes RWO podem ser montados por múltiplos pods, mas só no mesmo nó; montagem cross-node causa erros de multi-attach.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: db
spec:
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: data-claim
  containers:
    - name: db
      image: postgres:16
      volumeMounts:
        - name: data
          mountPath: /var/lib/postgresql/data
          subPath: pgdata       # mount a subdirectory of the volume

# a PVC is namespaced and bound to ONE PV
# RWO PVCs can be mounted by multiple pods on the SAME node
# (e.g. one writer, several readers on that node)

Provisionamento estático vs dinâmico

Provisionamento estático exige que admins pré-criem PVs — serve para NFS, mas é doloroso em escala. Provisionamento dinâmico permite que um PVC dispare a criação de volume sob demanda via o provisioner de um StorageClass. Clusters modernos quase sempre usam provisionamento dinâmico; estático fica reservado para armazenamento compartilhado/legado.

kubernetes
# STATIC: admin pre-creates PVs; PVCs bind to them.
#   Good for: pre-existing NFS exports, manual capacity planning.

# DYNAMIC: PVC requests storage; StorageClass provisions a PV
#   automatically (AWS EBS, GCE PD, Ceph, local-path, etc.)

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: dynamic-claim
spec:
  storageClassName: ebs-sc      # triggers dynamic provisioning
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 20Gi

# no PV exists -> provisioner creates one -> binds to PVC
# kubectl get pvc dynamic-claim -> Bound
# kubectl get pv -> shows the dynamically-created PV
15

StorageClass

Manifest de StorageClass

Um StorageClass descreve um 'sabor' de armazenamento provisionado dinamicamente: o provisioner (driver CSI), parâmetros (tipo de disco, criptografia, fsType) e políticas. PVCs o referenciam via spec.storageClassName. Um cluster tipicamente tem várias classes (SSD rápido, HDD em massa, NFS, …).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-sc
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
  encrypted: "true"
reclaimPolicy: Delete            # Retain | Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
mountOptions:
  - noatime
# kubectl get storageclass

StorageClass padrão

Exatamente um StorageClass pode ser o padrão (annotation is-default-class: true). PVCs que omitem storageClassName o usam automaticamente — conveniente para usuários que não se importam com qual backend recebem. Use kubectl get sc para ver qual classe está marcada como (default).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

# a PVC with no storageClassName uses the default
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: auto
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 5Gi
# (no storageClassName set -> uses 'standard')

Provisioners

kubernetes.io/no-provisioner significa só vínculo estático (sem criação dinâmica). Qualquer provisionamento dinâmico real usa drivers CSI — provedores de nuvem trazem os seus (ebs.csi.aws.com etc.), e opções self-hosted (Longhorn, Rook/Ceph, local-path) cobrem bare metal. Os parâmetros são inteiramente específicos do provisioner.

kubernetes
# built-in (no external driver): only static binding
provisioner: kubernetes.io/no-provisioner

# cloud CSI drivers (dynamic):
provisioner: ebs.csi.aws.com          # AWS EBS
provisioner: pd.csi.storage.gke.io    # GCE PD
provisioner: disk.csi.azure.com       # Azure Disk
provisioner: nfs.csi.k8s.io           # NFS

# popular self-hosted:
provisioner: driver.longhorn.io       # Longhorn
provisioner: rook-ceph.ceph.com       # Rook/Ceph
provisioner: rancher.io/local-path    # local-path (dev)

# parameters are provisioner-specific
# (e.g. AWS: type=gp3|iops=3000|encrypted=true)

Modo de vínculo de volume

Immediate vincula o PVC no momento da criação — arriscado para discos zonais, porque o pod pode cair numa zona diferente. WaitForFirstConsumer adia o vínculo até um pod realmente consumir o PVC, para que o volume caia na zona certa. Sempre use WaitForFirstConsumer para discos zonais na nuvem.

kubernetes
spec:
  volumeBindingMode: WaitForFirstConsumer
  # ^ default for many CSI drivers
  # alternatives:
  # volumeBindingMode: Immediate

# Immediate: PVC binds/provisions as soon as created
#   risk: volume created in zone A, pod scheduled in zone B
#   -> multi-attach / cross-zone latency issues

# WaitForFirstConsumer: delays binding until a pod using the PVC
#   is scheduled. The PV is then created in the pod's zone.
#   REQUIRED for topology-constrained backends (EBS, etc.)

# topology constraints come from the CSI driver via
# AllowedTopologies

Política de reclaim por StorageClass

StorageClass.reclaimPolicy define a política de cada PV que provisiona dinamicamente. Delete (padrão) destrói o volume quando o PVC é excluído — eficiente, mas perigoso para dados de produção. Para salvar dados, mude o PV para Retain antes de excluir o PVC, ou use uma classe Retain desde o início.

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-temp
provisioner: ebs.csi.aws.com
reclaimPolicy: Delete            # default for dynamic volumes
# reclaimPolicy: Retain          # keep data after PVC delete

# the StorageClass policy becomes the PV's policy
# when a PV is dynamically provisioned

# to preserve data, either:
# 1. use a Retain StorageClass
# 2. patch the dynamically-created PV to Retain before deleting PVC:
kubectl patch pv pvc-xxxx -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# then delete PVC safely; data survives

Expansão de volume

Definir allowVolumeExpansion: true permite aos usuários crescer um PVC editando spec.resources.requests.storage. O driver CSI expande o volume subjacente, e o kubelet expande o filesystem no próximo mount. Encolher nunca é suportado. A maioria dos drivers CSI de nuvem suporta expansão online (sem unmount).

kubernetes
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: ebs-sc
provisioner: ebs.csi.aws.com
allowVolumeExpansion: true       # must be true to resize

# then resize by editing the PVC's requested size
kubectl patch pvc data-claim -p '{"spec":{"resources":{"requests":{"storage":"50Gi"}}}}'

# status.conditions shows Resizing / FileSystemResizePending
kubectl describe pvc data-claim

# requirements:
# - StorageClass.allowVolumeExpansion = true
# - driver supports online expansion (most CSI drivers do)
# - shrinking is NOT supported (only grow)
# - FilesystemResize happens after the PV is expanded
16

Helm

Install e release do Helm

Helm empacota manifests do Kubernetes como um 'chart' e os gerencia como uma 'release'. install cria uma release; upgrade aplica mudanças; upgrade --install é idempotente. Releases são rastreadas por um Secret/ConfigMap no namespace — é assim que o rollback funciona.

kubernetes
# add and update a chart repo
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# search for charts
helm search repo nginx
helm search hub wordpress   # searches Artifact Hub

# install a chart (creates a release)
helm install my-nginx bitnami/nginx --namespace web --create-namespace

# upgrade an existing release
helm upgrade my-nginx bitnami/nginx --set replicaCount=3

# upgrade + install in one idempotent command
helm upgrade --install my-nginx bitnami/nginx -f values.yaml

# uninstall
helm uninstall my-nginx -n web

# list releases
helm list -n web
helm list --all-namespaces

Estrutura de chart

Um chart é um diretório de YAML com templates mais defaults. Chart.yaml guarda metadados; values.yaml guarda defaults; templates/ guarda Go templates renderizados com esses valores. helm create cria a estrutura de um chart funcional. helm lint captura erros de schema/template antes de publicar.

kubernetes
my-chart/
├── Chart.yaml          # chart metadata (name, version, apiVersion)
├── values.yaml         # default values (overridable)
├── charts/             # chart dependencies (subcharts)
├── templates/          # Go-templated YAML
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── _helpers.tpl    # named templates (partials)
│   └── NOTES.txt       # post-install notes
├── templates.yaml      # (optional) CRDs to install before templates
└── README.md

# create a new chart skeleton
helm create my-chart

# lint a chart
helm lint my-chart

# package into a .tgz
helm package my-chart

Values e overrides

values.yaml guarda os defaults do chart. Sobrescreva com --set (para escalares) ou -f (para arquivos inteiros). helm show values lista toda chave que um chart aceita. helm template renderiza manifests sem tocar no cluster — essencial para ver o diff do que uma release realmente aplicará.

kubernetes
# values.yaml (chart defaults)
image:
  repository: nginx
  tag: "1.25"
replicaCount: 2
service:
  type: ClusterIP
  port: 80

# override on the command line
helm upgrade --install web my-chart \
  --set replicaCount=5 \
  --set image.tag=1.26 \
  --set service.type=LoadBalancer

# override from a file
helm upgrade --install web my-chart -f prod-values.yaml

# see all values a chart supports
helm show values bitnami/nginx

# rendered output (debug, no install)
helm template web my-chart -f prod-values.yaml

Templates e objetos embutidos

Templates usam sintaxe de Go template com funções Sprig. .Release.Name torna cada instalação única; .Values expõe os valores do chart; .Chart puxa de Chart.yaml. A função default fornece fallbacks. Nomes render-safe via .Release.Name permitem que um chart rode muitas releases no mesmo namespace.

kubernetes
# built-in template objects:
#   .Values         chart values (after overrides)
#   .Release        release metadata (Name, Namespace, Service, Revision, IsInstall, IsUpgrade)
#   .Chart          Chart.yaml contents
#   .Files          files in the chart
#   .Capabilities   cluster capabilities (KubeVersion, APIVersions)
#   .Template       current template info

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-app
  labels:
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
spec:
  replicas: {{ .Values.replicaCount | default 1 }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}

Repositório Helm

Helm 3 suporta tanto repositórios de chart HTTP clássicos quanto registries OCI (helm push/pull oci://…). OCI é o caminho moderno, amigável à assinatura. helm repo update atualiza os índices; sempre rode antes do upgrade para pegar as versões mais recentes dos charts. Artifact Hub (helm search hub) indexa charts públicos.

kubernetes
# add a chart repository
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add jetstack https://charts.jetstack.io

# list configured repos
helm repo list

# update repo indexes
helm repo update

# remove a repo
helm repo remove bitnami

# push to OCI registry (Helm 3+)
helm registry login registry.example.com
helm package my-chart
helm push my-chart-0.1.0.tgz oci://registry.example.com/charts

# pull an OCI chart
helm pull oci://registry.example.com/charts/my-chart --version 0.1.0

Rollback e histórico

Cada install/upgrade cria uma revisão numerada armazenada como Secret. helm rollback volta a uma revisão anterior instantaneamente — o recurso matador do Helm em relação ao kubectl apply puro. helm get values mostra o que foi de fato implantado, valioso para depurar estado que desviou.

kubernetes
# view release history
helm history my-nginx -n web

# rollback to a previous revision
helm rollback my-nginx 1 -n web

# get rendered manifests of a deployed release
helm get manifest my-nginx -n web

# get the values used at install/upgrade
helm get values my-nginx -n web
helm get values my-nginx -n web --all   # incl. chart defaults

# get all info (hooks, manifest, values, notes)
helm get all my-nginx -n web

# wait for resources to be ready on install/upgrade
helm upgrade --install my-nginx bitnami/nginx --wait --timeout 5m
17

NetworkPolicy

Manifest de NetworkPolicy

Uma NetworkPolicy é uma regra de firewall para pods. Um podSelector vazio seleciona os pods do namespace; uma lista de regras vazia nega o tráfego daquele tipo. NetworkPolicies são aditivas — um pod é permitido se QUALQUER política o permitir. Exigem um CNI que as suporte; flannel puro as ignora.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny
  namespace: prod
spec:
  podSelector: {}             # selects ALL pods in the namespace
  policyTypes:
    - Ingress
    - Egress
  # no ingress/egress rules => deny all traffic of that type
# effect: pods in 'prod' can't send or receive ANY traffic
# until another policy explicitly allows it

# REQUIRES a CNI that supports NetworkPolicy
# (Calico, Cilium, Weave, kube-router; NOT flannel alone)

Regras de ingress

Regras de ingress permitem tráfego PARA os pods selecionados. Entradas from são combinadas com OU; portas também. podSelector casa com pods do mesmo namespace; namespaceSelector casa com namespaces inteiros (use o label kubernetes.io/metadata.name adicionado automaticamente). Combinar ambos num mesmo item faz AND entre eles.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-web
  namespace: prod
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:               # pods in same namespace
            matchLabels:
              app: gateway
        - namespaceSelector:         # whole other namespace
            matchLabels:
              kubernetes.io/metadata.name: monitoring
        - ipBlock:                   # external CIDR
            cidr: 10.0.0.0/8
      ports:
        - protocol: TCP
          port: 8080

Regras de egress

Regras de egress controlam COM O QUE os pods selecionados podem falar. Uma pegadinha comum: um egress default-deny quebra a resolução DNS e os pods não alcançam o kube-dns. Sempre permita UDP/TCP 53 ao namespace kube-system antes de negar o resto. ipBlock.except recorta exceções.

kubernetes
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-egress-dns
  namespace: prod
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector: {}     # any namespace (kube-dns)
      ports:
        - protocol: UDP
          port: 53
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8          # allow internet, deny internal
      ports:
        - protocol: TCP
          port: 443

# WARNING: egress deny-all blocks DNS and breaks pods.
# Always allow kube-dns first.

Selectors e seleção de namespace

Um podSelector puro casa com pods do próprio namespace da política. Um namespaceSelector casa com namespaces inteiros. Especificar AMBOS podSelector E namespaceSelector num item faz AND (pods com label X no namespace Y) — colocá-los como itens separados faz OU. ipBlock casa com IPs externos.

kubernetes
spec:
  podSelector:                       # selects pods in THIS namespace
    matchLabels:
      app: web
  ingress:
    - from:
        # SAME namespace, matching pods
        - podSelector:
            matchLabels:
              app: gateway

        # DIFFERENT namespace (whole namespace)
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: monitoring

        # BOTH: pods in another namespace with specific labels
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: backend
          podSelector:
            matchLabels:
              app: api

        # external IP range
        - ipBlock:
            cidr: 192.168.1.0/24

Políticas padrão (deny/allow all)

Políticas default-deny (regras vazias) travam um namespace, de modo que só allow-lists explícitas abram buracos. Aplique deny-all ingress + deny-all egress como base, e depois adicione políticas de permissão direcionadas. Uma entrada ingress: [{}] vazia permite qualquer ingress — a válvula de escape para optar por fora.

kubernetes
# --- DEFAULT DENY INGRESS (in a namespace) ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-ingress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Ingress]
---
# --- DEFAULT DENY EGRESS ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-egress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Egress]
---
# --- ALLOW ALL INGRESS (whitelist opt-out) ---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-all-ingress
  namespace: prod
spec:
  podSelector: {}
  policyTypes: [Ingress]
  ingress:
    - {}      # allow from anywhere

Tipos de política e comportamento padrão

NetworkPolicies são aditivas — uma vez que qualquer política selecione um pod, aquele tipo de tráfego vira default-deny para o pod, a menos que uma regra explícita permita. Sem nenhuma política, tudo está aberto. Liste as políticas que casam com os labels de um pod para ver o que governa seu tráfego.

kubernetes
spec:
  policyTypes:
    - Ingress
    - Egress
  # if omitted, defaults are inferred:
  #   - Ingress is always present (a policy always affects ingress)
  #   - Egress is implied if any egress rule exists

# key behaviors:
# - policies are ADDITIVE: a pod is allowed if ANY matching
#   policy permits the traffic
# - if NO policy selects a pod => all traffic allowed (default open)
# - if at least one policy selects a pod => default deny for that type
#   unless an explicit rule allows it

# inspect effective policies for a pod
kubectl get networkpolicy -n prod -l app=web
18

RBAC

Role (namespaced)

Uma Role concede permissões sobre recursos namespaced dentro de um único namespace. rules lista apiGroups, resources e verbs. pods/log é um subresource; pods/exec exige o verbo create (porque exec cria um subresource). Use '*' como curinga para qualquer valor.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: dev
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/exec"]
    verbs: ["create"]
# a Role grants permissions WITHIN one namespace
# verbs: get, list, watch, create, update, patch, delete, deletecollection, "*"
# apiGroups: "" (core), "apps", "batch", "rbac.authorization.k8s.io", ...

RoleBinding

Um RoleBinding concede uma Role (ou um ClusterRole, delimitado a um namespace) a sujeitos: Users, Groups ou ServiceAccounts. O binding vive no namespace em que as permissões se aplicam. roleRef é imutável — para mudar a Role referenciada, exclua e recrie o binding.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: dev
subjects:
  - kind: User
    name: alice
    apiGroup: rbac.authorization.k8s.io
  - kind: ServiceAccount
    name: my-sa
    namespace: dev
  - kind: Group
    name: dev-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io
# binds the Role to users, groups, or service accounts
# RoleBinding can also reference a ClusterRole (scoped to its namespace)

ClusterRole e ClusterRoleBinding

Uma ClusterRole concede permissões sobre recursos de escopo de cluster (nodes, namespaces, PVs) — Roles não podem tocar neles. ClusterRoles também podem ser vinculadas em qualquer namespace via um RoleBinding, para reuso (defina uma vez, vincule muitas). ClusterRoleBinding concede uma ClusterRole em o cluster.

kubernetes
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-reader
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-nodes
subjects:
  - kind: ServiceAccount
    name: monitor
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: node-reader
  apiGroup: rbac.authorization.k8s.io
# ClusterRole grants cluster-scoped resources (nodes, PVs, namespaces)
# or can be reused across namespaces via a RoleBinding

Verbs, resources e API groups

apiGroups agrupam recursos — core é '' (string vazia); apps tem Deployments/StatefulSets; batch tem Jobs/CronJobs. Subresources (pods/log, pods/exec, pods/portforward) são permissões separadas. resourceNames restringe uma regra a instâncias específicas. nonResourceURLs cobre /healthz, /metrics etc.

kubernetes
rules:
  - apiGroups: [""]                        # core API group
    resources: ["pods", "services", "configmaps", "secrets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets"]
    verbs: ["*"]
  - apiGroups: ["batch"]
    resources: ["jobs", "cronjobs"]
    verbs: ["create", "delete", "get"]
  - apiGroups: [""]
    resources: ["pods/log", "pods/exec", "pods/portforward"]
    verbs: ["get", "create"]
  - nonResourceURLs: ["/healthz", "/healthz/*"]   # non-resource URLs
    verbs: ["get"]

# resourceNames: restrict to specific instances
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["my-config"]
    verbs: ["get"]

ServiceAccount

Um ServiceAccount é uma identidade para pods. Atribua via serviceAccountName; o token é montado automaticamente em /var/run/secrets/kubernetes.io/serviceaccount. Desde a 1.24, SAs não têm Secrets de token permanentes — use kubectl create token para tokens de curta duração, com prazo. automountServiceAccountToken: false recusa.

kubernetes
# create a service account
kubectl create serviceaccount my-sa -n dev

# assign a RoleBinding (see RoleBinding example)
# mount the SA in a pod
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  serviceAccountName: my-sa
  automountServiceAccountToken: false   # opt out of token mount
  containers:
    - name: app
      image: myapp:1.0

# short-lived tokens (1.24+) - no permanent secret
kubectl create token my-sa -n dev --duration=1h

# list SAs
kubectl get sa -n dev

kubectl auth can-i

kubectl auth can-i verifica permissões RBAC para o usuário atual (ou personificado) — essencial para depurar erros 'forbidden'. --list mostra cada verbo/recurso permitido. --as personifica um usuário/SA para testes. Roles embutidas (view, edit, admin, cluster-admin) cobrem necessidades comuns.

kubernetes
# check if you can do something
kubectl auth can-i create pods -n dev
kubectl auth can-i delete deployments -n prod

# check on behalf of another user/SA
kubectl auth can-i list secrets --as=system:serviceaccount:dev:my-sa -n dev

# check all allowed verbs on a resource
kubectl auth can-i --list --as=alice -n dev

# whoami (1.25+)
kubectl auth whoami

# reconcile: detect over-privileged bindings
kubectl get rolebindings,clusterrolebindings --all-namespaces -o wide

# common built-in cluster roles:
#   view, edit, admin, cluster-admin
19

Probes (Liveness/Readiness/Startup)

Liveness probe

Uma liveness probe diz ao kubelet quando reiniciar um contêiner. Se falhar failureThreshold vezes consecutivas, o kubelet mata o contêiner e a política de reinício se aplica. Use-a para se recuperar de deadlocks ou estados irrecuperáveis — não para checar dependências (isso é readiness).

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        initialDelaySeconds: 15
        periodSeconds: 10
        timeoutSeconds: 2
        failureThreshold: 3
        successThreshold: 1
# if the probe fails failureThreshold times in a row,
# kubelet kills and restarts the container (per restartPolicy)

Readiness probe

Uma readiness probe controla se o pod recebe tráfego dos Services. Uma readiness probe falhando remove o IP do pod dos endpoints — mas NÃO o reinicia. Use para aquecimento (não roteie até estar pronto) e para drenar tráfego durante falhas transitórias ou desligamento gracioso.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  containers:
    - name: app
      image: myapp:1.0
      readinessProbe:
        httpGet:
          path: /ready
          port: 8080
        initialDelaySeconds: 5
        periodSeconds: 5
        failureThreshold: 3
# a failing readiness probe REMOVES the pod from service endpoints,
# but does NOT restart the container.
# use to drain traffic during deploys, warm-up, or transient outages.

Startup probe

Uma startup probe (1.18+) serve para apps lentas para iniciar (Java, servidores legados). Enquanto roda, liveness e readiness ficam desabilitadas — então um boot lento não é morto pela liveness. Uma vez que o startup tem sucesso, liveness/readiness ativam. Use uma janela longa de failureThreshold × periodSeconds para o boot.

kubernetes
apiVersion: v1
kind: Pod
metadata:
  name: slow-app
spec:
  containers:
    - name: app
      image: myapp:1.0
      startupProbe:
        httpGet:
          path: /startup
          port: 8080
        failureThreshold: 30
        periodSeconds: 10      # up to 300s to start
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 10
# while the startup probe runs, liveness/readiness are disabled.
# once startup succeeds, liveness/readiness take over.

Handlers de probe

Três tipos de handler: httpGet (sucesso = HTTP 2xx/3xx), tcpSocket (sucesso = conexão TCP), exec (sucesso = exit 0). A probe gRPC (1.27+ GA) é a opção limpa para serviços gRPC. Prefira httpGet — permite que a app sinalize 'saudável, mas ocupado' (503) sem reiniciar. exec é frágil (precisa de shell/binários na imagem).

kubernetes
# three handler types:

# 1. HTTP GET (most common) - success = 200-399
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    httpHeaders:
      - name: X-Custom
        value: probe
    scheme: HTTP

# 2. TCP socket - success = port open
livenessProbe:
  tcpSocket:
    port: 3306

# 3. Exec - success = exit code 0
livenessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - "pg_isready -h localhost"

# gRPC (1.24+, alpha -> GA): use grpc probe
livenessProbe:
  grpc:
    port: 9090
    service: my.package.Health

Parâmetros de probe

initialDelaySeconds atrasa a primeira probe — mas uma startup probe é uma forma mais limpa de tratar boots lentos. periodSeconds é a cadência; failureThreshold × periodSeconds é quanto tempo um pod pode ficar insalubre antes de agir. Aperte para failover rápido, afrouxe para tolerância. terminationGracePeriodSeconds limita o desligamento.

kubernetes
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 15   # wait before first probe (after start)
  periodSeconds: 10         # probe every 10s
  timeoutSeconds: 2         # max time per probe
  successThreshold: 1       # consecutive successes to mark OK
  failureThreshold: 3       # consecutive failures to mark failed
  terminationGracePeriodSeconds: 30  # (liveness) grace before SIGKILL

# tuning tips:
# - set initialDelaySeconds > typical startup time
# - OR use a startup probe instead (cleaner)
# - shorter period = faster reaction, more load
# - higher failureThreshold = more tolerant of blips

Comportamento de falha de probe

Falha de liveness mata+reinicia o contêiner no lugar (não remarca). Falha de readiness só remove o pod dos Services — sem reinício. Falha de startup comporta-se como liveness. Liveness oscilante costuma vir de probes que dependem de serviços a jusante lentos — mantenha as checagens de saúde locais e baratas.

kubernetes
# --- LIVENESS FAIL ---
#   container killed -> restarted (per restartPolicy: Always/OnFailure)
#   pod stays on the same node (NOT rescheduled)
#   CrashLoopBackOff if it keeps failing

# --- READINESS FAIL ---
#   pod stays running, but is REMOVED from Service endpoints
#   no traffic until it succeeds again
#   NOT restarted by kubelet

# --- STARTUP FAIL ---
#   container killed and restarted (like liveness)
#   liveness/readiness never activate
#   after failureThreshold × periodSeconds, pod is stuck restarting

# check probe results:
kubectl describe pod app | grep -A5 "Last State"
kubectl get pod app -o jsonpath='{.status.containerStatuses[*].state}'

# common cause of flapping: liveness probe hitting a slow dependency
20

Recursos e kubectl avançado

Requests e limits

requests são o que o scheduler reserva (um pod só é agendado se um nó tiver requests sobrando) — defina-os para suas necessidades em estado estável. limits são tetos rígidos: CPU é limitada por throttle, memória é OOMKilled. cpu é em cores (500m = 0.5), memória em bytes (Mi/Gi). Sempre defina ambos em produção.

kubernetes
spec:
  containers:
    - name: app
      image: myapp:1.0
      resources:
        requests:           # what the scheduler guarantees (reservation)
          cpu: 250m          # 250 millicores = 0.25 core
          memory: 256Mi      # 256 mebibytes
          ephemeral-storage: 1Gi
        limits:             # hard ceiling (enforced)
          cpu: "1"           # 1 core
          memory: 512Mi
          ephemeral-storage: 2Gi

# cpu limit: throttled (cfs quota)
# memory limit: OOMKilled if exceeded
# ephemeral-storage limit: evicted if exceeded
# request only (no limit): best-effort burst

Defaults do LimitRange

LimitRange aplica requests/limits padrão a pods que não os especificam — crítico quando um ResourceQuota exige requests. max/min limitam quão grande/pequeno um único contêiner pode ir. maxLimitRequestRatio limita quanto um contêiner pode estourar acima do request, prevenindo vizinhos ruidosos.

kubernetes
apiVersion: v1
kind: LimitRange
metadata:
  name: defaults
  namespace: prod
spec:
  limits:
    - type: Container
      default:               # applied as LIMITS when not set
        cpu: 500m
        memory: 512Mi
      defaultRequest:        # applied as REQUESTS when not set
        cpu: 100m
        memory: 128Mi
      max:                   # max allowed LIMITS
        cpu: "4"
        memory: 8Gi
      min:                   # min allowed REQUESTS
        cpu: 50m
        memory: 64Mi
      maxLimitRequestRatio:  # limit/request ratio cap (burst cap)
        cpu: "4"

# a pod with no resources gets default/defaultRequest applied
# a pod with limit=4cpu, request=50m would breach maxLimitRequestRatio

Horizontal Pod Autoscaler

HPA escala réplicas com base em métricas (CPU/memória via metrics-server, ou custom/external via Prometheus Adapter). behavior (v2) ajusta a agressividade: stabilizationWindowSeconds previne oscilação, policies limitam a taxa por minuto. Escalar para cima costuma ser rápido/agressivo; reduzir é intencionalmente lento.

kubernetes
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 3
  maxReplicas: 50
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization          # avg across pods
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:                          # (v2) scale up/down tuning
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 50                  # max 50% down per minute
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 60

# requires metrics-server for CPU/memory
kubectl get hpa web -w

Pod Disruption Budget

Um PodDisruptionBudget limita quantos pods de um conjunto podem ser expulsos voluntariamente de uma vez — protegendo a disponibilidade durante node drains e ações do cluster-autoscaler. Use minAvailable ou maxUnavailable (não ambos). Ele NÃO protege contra interrupções involuntárias (falha de hardware) — só réplicas fazem isso.

kubernetes
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
  namespace: prod
spec:
  minAvailable: 2            # at least 2 pods always available
  # OR
  # maxUnavailable: 1        # at most 1 down at a time
  selector:
    matchLabels:
      app: web
# PDB protects against VOLUNTARY disruptions:
#   - kubectl drain (node maintenance)
#   - cluster autoscaler evictions
#   - kubectl delete pod (controller-managed)
# It does NOT prevent INVOLUNTARY disruptions (node failure, kernel panic).

# check PDB status
kubectl get pdb -n prod
kubectl describe pdb web-pdb -n prod

Taints, tolerations e affinity

Taints repelem pods; tolerations permitem que pods específicos os ignorem — use para dedicar nós (GPU, ingress, control-plane). nodeAffinity prefere/exige certos nós. podAntiAffinity espalha réplicas por domínios de topologia (hosts, zonas) para HA. Remova um taint com um traço final na mesma chave+effect.

kubernetes
# taint a node
kubectl taint nodes node-1 dedicated=gpu:NoSchedule

# tolerate the taint so a pod can schedule there
spec:
  tolerations:
    - key: dedicated
      operator: Equal
      value: gpu
      effect: NoSchedule

# prefer specific nodes
spec:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          preference:
            matchExpressions:
              - key: disktype
                operator: In
                values: [ssd]
    podAntiAffinity:               # spread replicas across nodes
      requiredDuringSchedulingIgnoredDuringExecution:
        - topologyKey: kubernetes.io/hostname
          labelSelector:
            matchLabels:
              app: web

# remove a taint
kubectl taint nodes node-1 dedicated=gpu:NoSchedule-

kubectl avançado (patch/wait/top/debug)

patch suporta os tipos JSON, strategic-merge e merge. wait bloqueia até uma condição ser atendida — perfeito para scripts. top mostra CPU/memória ao vivo (precisa de metrics-server). kubectl debug anexa um contêiner efêmero a um pod em execução (ótimo para imagens distroless) ou abre um shell num nó.

kubernetes
# JSON patch (precise field ops)
kubectl patch deployment web --type json -p \
  '[{"op":"replace","path":"/spec/replicas","value":3}]'

# strategic merge patch (default for k8s objects)
kubectl patch svc web -p '{"spec":{"type":"NodePort"}}'

# wait for a condition
kubectl wait --for=condition=Ready pod/web --timeout=60s
kubectl wait --for=delete pod/web --timeout=30s

# resource usage (needs metrics-server)
kubectl top nodes
kubectl top pods -n prod
kubectl top pod web --containers

# ephemeral debug container (1.25+)
kubectl debug -it web --image=busybox --target=web
# debug a node
kubectl debug node/node-1 -it --image=ubuntu

# run a one-off pod
kubectl run tmp --rm -it --image=alpine -- sh

# explain a field
kubectl explain pod.spec.containers.resources

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.