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.
# 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.
# 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 -wContext 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.
# 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-configExplain 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.
# 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/v1Dry 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.
# 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 yamlAjuda 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.
# 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' >> ~/.bashrcPod
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.
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: AlwaysPod 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.
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.
# 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.
# 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=nginxExec 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.
# 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 :80Delete 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.
# 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=30sDeployment
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.
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: 80Estraté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).
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.
# 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/nginxScale 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).
# 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: 80Atualizando 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.
# 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.yamlStatus 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.
# 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}'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.
# 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.comService 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>.
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 VIPService 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.
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.
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/hostnameService 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.
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.localEndpoints 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.
# 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)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.
# 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.propertiesManifest 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.
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.
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 missingConsumindo 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.
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/configAtualizaçã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.
# 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_LEVELConfigMap 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.
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)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.
# 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.pemManifest 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.
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 -dUsando 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.
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: trueUsando 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.
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 nodeImagePullSecret
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.
# 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.
# 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: passNamespace
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.
# 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=devResourceQuota
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.
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 namespaceLimitRange
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.
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: 1GiExcluindo 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.
# 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-foundNamespaces 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.
# 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.
# 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 # shorthandLabels 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.
# 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.
# 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.
# 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.
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: webAnnotations
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.
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.
# 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.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.
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 nginxComo 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.
# 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=5ReplicaSet 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.
# 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 practiceEscalonamento 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.
# 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 resourceMudanç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.
# 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-kindRemovendo 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.
# 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 itStatefulSet
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.
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: 10GiIdentidade 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.
# 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 reschedulesArmazenamento 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.
# 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-2Deploy 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).
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 orderRolling 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.
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 templateAssociaçã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.
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 nameDaemonSet
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.
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 automaticallyAgendamento 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.
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: ExistsEstraté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).
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-systemTaints 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.
# 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 | PreferNoScheduleCasos 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.
# 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/containersStatus 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.
# 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-abcdeJob 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.
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/piCompletions 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.
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.
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.
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 jobsSuspend 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.
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=backupCronograma 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.
# 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 mathIngress
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.
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: 8080Ingress 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.
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-prodRegras 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.
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.
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 defaultTipos 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.
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 controllerAnnotations (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.
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 } }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.
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-xxxxManifest 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.
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 foundModos 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ó.
# 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.
# 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.
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.
# 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 PVStorageClass
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, …).
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 storageclassStorageClass 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).
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.
# 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.
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
# AllowedTopologiesPolí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.
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 survivesExpansã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).
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 expandedHelm
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.
# 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-namespacesEstrutura 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.
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-chartValues 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á.
# 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.yamlTemplates 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.
# 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.
# 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.0Rollback 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.
# 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 5mNetworkPolicy
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.
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.
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: 8080Regras 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.
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.
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/24Polí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.
# --- 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 anywhereTipos 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.
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=webRBAC
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.
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.
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.
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 RoleBindingVerbs, 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.
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.
# 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 devkubectl 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.
# 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-adminProbes (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).
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.
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.
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).
# 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.HealthParâ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.
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 blipsComportamento 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.
# --- 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 dependencyRecursos 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.
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 burstDefaults 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.
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 maxLimitRequestRatioHorizontal 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.
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 -wPod 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.
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 prodTaints, 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.
# 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ó.
# 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.resourcesSnippets de Kubernetes relacionados
Copy-paste ready code for common tasks.
Pod Manifest
Define a standalone Pod with a container, env, and probe.
Deployment & Rollout
Manage a replicated, rolling-updated workload.
Service Types
Expose Pods via ClusterIP, NodePort, and LoadBalancer services.
ConfigMap & Secret
Inject configuration and sensitive data into containers.
Ingress Routing
Route external HTTP traffic to services by host and path.
Labels & Selectors
Tag resources and query them with selectors.
kubectl Basics
Common kubectl commands for everyday operations.
Namespaces
Partition a cluster into isolated virtual clusters.
Was this helpful?