Containers da CLI: docker & kubectl

Q: Imagens Go devem usar alpine ou distroless?

distroless/static minimiza a superfície de ataque para binários Go puros. alpine adiciona um shell e gerenciador de pacotes quando os operadores querem ferramentas de depuração apk add.

Q: Como vejo por que um pod reiniciou?

Eventos do kubectl describe pod e kubectl logs --previous para o último container terminado.

Q: Como copio um perfil de um pod?

kubectl port-forward mais curl localmente, ou kubectl cp se o pod escreveu um arquivo em um volume.

Q: Por que minha imagem está enorme apesar dos binários estáticos Go?

O estágio de build ou COPY . acidental inclui dados de teste e .git. Use .dockerignore e builds multi-stage; o runtime deve conter apenas o binário.

Q: Qual contexto kubectl devo usar?

kubectl config current-context antes de comandos destrutivos. Flags de namespace (-n prod) evitam erros entre ambientes.

Q: Como testar serviços gRPC?

grpcurl via kubectl port-forward para a porta gRPC, ou execute grpcurl em um container de depuração efêmero na rede do cluster.

Construa e execute imagens Go com docker localmente, depois depure pods no Kubernetes com kubectl logs, exec e port-forward.

Resumo

Binários estáticos do Go cabem em imagens de container mínimas, mas problemas de produção ainda surgem através das CLIs de container: um pod em loop de reinício (CrashLoopBackOff), uma imagem que funciona no seu laptop mas não em CI, ou uma verificação de integridade (health check) que nunca fica pronta.

Esses comandos são o caminho mais rápido do sintoma para o processo dentro do cluster.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Dockerfile (multi-stage)
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/api ./cmd/api
 
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/api /api
USER nonroot:nonroot
ENTRYPOINT ["/api"]

# Local
docker build -t api:dev .
docker run --rm -p 8080:8080 api:dev
docker logs -f <container_id>
 
# Kubernetes
kubectl get pods -l app=api
kubectl logs deploy/api --tail=200
kubectl exec -it deploy/api -- /api -version 2>/dev/null || kubectl exec -it deploy/api -- /bin/sh
kubectl port-forward deploy/api 6060:6060

Quando usar isto:

Reproduzir uma imagem de produção localmente antes de enviá-la para um registro.
Um pod Go está em CrashLoopBackOff e você precisa de logs e códigos de saída rapidamente.
Você precisa alcançar uma porta de depuração ou pprof sem expô-la em um Service público.

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
 
# --- docker: build e smoke test ---
cat > Dockerfile <<'EOF'
FROM golang:1.26 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /api ./cmd/api
 
FROM gcr.io/distroless/static-debian12
COPY --from=build /api /api
USER 65532:65532
ENTRYPOINT ["/api"]
EOF
 
docker build -t api:local .
CID=$(docker run -d -p 18080:8080 api:local)
sleep 2
curl -sf localhost:18080/healthz
docker logs "$CID" | tail -20
docker rm -f "$CID"
 
# --- kubectl: inspecionar deployment (nomes são exemplos) ---
kubectl get deploy,po -l app=api
kubectl rollout status deploy/api --timeout=120s
kubectl logs deploy/api --tail=100 --timestamps
kubectl describe pod -l app=api | rg -n "State:|Reason:|Exit Code:|Liveness|Readiness"

O que isto demonstra:

Build multi-stage produzindo uma imagem runtime distroless para Go.
Smoke test com porta publicada e cauda de logs antes da limpeza.
Espera de rollout do kubectl mais saída de describe filtrada com ripgrep para falhas de probe.

Mergulho Profundo

Como Funciona

docker build executa os estágios do Dockerfile; o estágio de compilação necessita do toolchain Go e do cache de módulos, o estágio de runtime frequentemente apenas copia o binário estático.
docker run inicia um container com mapeamentos de porta (-p host:container) e variáveis de ambiente opcionais (-e) espelhando as variáveis de ambiente do K8s.
kubectl logs lê o stdout/stderr do container do kubelet; -f segue, --previous mostra a última instância encerrada.
kubectl exec executa um processo no namespace de rede do pod - essencial quando a imagem runtime não possui shell (distroless).
kubectl port-forward cria um túnel de uma porta local para uma porta do pod para APIs pprof ou admin sem alterar o Service.

Referência de Comandos

Tarefa	docker	kubectl
Construir imagem	`docker build -t nome:tag .`	`kubectl apply -f` (após push)
Executar / implantar	`docker run -p ...`	`kubectl rollout restart deploy/nome`
Transmitir logs	`docker logs -f id`	`kubectl logs -f deploy/nome`
Shell	`docker exec -it id sh`	`kubectl exec -it po -- sh`
Porta de depuração	`-p 6060:6060`	`kubectl port-forward po 6060:6060`
Inspecionar saída	`docker inspect --format='{{.State.ExitCode}}'`	`kubectl describe po` Eventos

Notas Go

# Cache de módulos no estágio de build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/api ./cmd/api

Fixe a tag da imagem golang para a mesma versão menor que seu go.mod declara; alinhe com a política GOTOOLCHAIN em CI.

Armadilhas

Construindo em arquitetura errada - Apple Silicon constrói linux/arm64 enquanto o cluster é amd64. Correção: docker build --platform linux/amd64 ou construtores nativos de CI.
Distroless sem shell - kubectl exec sh falha. Correção: imagem de toolkit de depuração, container de depuração efêmero, ou scratch + copiar binário para um pod de depuração.
Logging para arquivos dentro de containers - Arquivos desaparecem na reinicialização; o kubelet apenas envia stdout/stderr. Correção: registrar em stdout; usar logging centralizado.
USER esquecido - Container executa como root apesar da boa prática do Go. Correção: USER não root correspondendo a securityContext.runAsNonRoot do Kubernetes.
Liveness matando inícios lentos - A inicialização do Go sem JVM é rápida, mas migrações podem atrasar a prontidão. Correção: separar prontidão (readiness) vs. vivacidade (liveness); ajustar initialDelaySeconds.
port-forward deixado rodando - Túneis contornam a política de rede localmente. Correção: fechar após depuração; nunca compartilhar portas de admin em 0.0.0.0.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
CLI docker	Build de imagem em Laptop e CI	Apenas frota de produção no Kubernetes
podman	Containers sem root no RHEL/Fedora	Equipe padronizada em Docker Desktop
kubectl debug	Containers de depuração efêmeros (K8s 1.23+)	Triagem simples apenas de logs
Helm / GitOps	Implantações declarativas	Você só precisa de um `log grep` único
systemd em VM	Nenhum orquestrador	Organização exige Kubernetes

FAQs

Imagens Go devem usar alpine ou distroless?

distroless/static minimiza a superfície de ataque para binários Go puros.

alpine adiciona um shell e gerenciador de pacotes quando os operadores querem ferramentas de depuração apk add.

Como vejo por que um pod reiniciou?

Eventos do kubectl describe pod e kubectl logs --previous para o último container terminado.

Posso executar a mesma imagem com docker run que a de produção?

Puxe pelo digest do seu registro e execute com as mesmas variáveis de ambiente e entrypoint.

Valida a integridade da imagem fora do cluster.

Como copio um perfil de um pod?

kubectl port-forward mais curl localmente, ou kubectl cp se o pod escreveu um arquivo em um volume.

Por que minha imagem está enorme apesar dos binários estáticos Go?

O estágio de build ou COPY . acidental inclui dados de teste e .git.

Use .dockerignore e builds multi-stage; o runtime deve conter apenas o binário.

Qual contexto kubectl devo usar?

kubectl config current-context antes de comandos destrutivos.

Flags de namespace (-n prod) evitam erros entre ambientes.

Como testar serviços gRPC?

grpcurl via kubectl port-forward para a porta gRPC, ou execute grpcurl em um container de depuração efêmero na rede do cluster.

O docker compose substitui o kubectl para desenvolvimento local?

Compose modela pilhas de desenvolvimento multi-serviço.

kubectl continua necessário para comportamento do cluster: probes, ConfigMaps e políticas de rede.

Como passo GOMAXPROCS ou GOGC?

Defina variáveis de ambiente do container no manifesto de Deployment - o mesmo que exports de shell em VMs.

E se os logs estiverem vazios?

O processo pode registrar em um arquivo ou falhar antes de escrever.

Verifique os códigos de saída do kubectl describe e execute a imagem com docker run --rm -it localmente.

Devo instalar plugins kubectl?

Plugins krew como ctx e ns aceleram a troca de contexto.

Verbos principais cobrem a maior parte da depuração de serviços Go.

Como reinicio um deployment após uma mudança de configuração?

kubectl rollout restart deploy/api aciona uma atualização contínua com a mesma tag de imagem se apenas o env foi alterado via aplicação do manifesto.

Relacionados

Build, Test & Profile from the Shell - pprof via port-forward
systemd & Service Unit Files for Go Binaries - alternativa de deploy em VM
Search, ripgrep & jq for Debugging - filtrar dumps de log
Linux CLI Skills for Go Engineers - fluxos de container vs VM
Cloud Deploy Basics - padrões de runtime na nuvem

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build), e golangci-lint (latest - verifique o conjunto de linters na build).

Resumo

Esses comandos são o caminho mais rápido do sintoma para o processo dentro do cluster.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Dockerfile (multi-stage)
FROM golang:1.26 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/api ./cmd/api
 
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/api /api
USER nonroot:nonroot
ENTRYPOINT ["/api"]

# Local
docker build -t api:dev .
docker run --rm -p 8080:8080 api:dev
docker logs -f <container_id>
 
# Kubernetes
kubectl get pods -l app=api
kubectl logs deploy/api --tail=200
kubectl exec -it deploy/api -- /api -version 2>/dev/null || kubectl exec -it deploy/api -- /bin/sh
kubectl port-forward deploy/api 6060:6060

Quando usar isto:

Reproduzir uma imagem de produção localmente antes de enviá-la para um registro.
Um pod Go está em CrashLoopBackOff e você precisa de logs e códigos de saída rapidamente.
Você precisa alcançar uma porta de depuração ou pprof sem expô-la em um Service público.

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
 
# --- docker: build e smoke test ---
cat > Dockerfile <<'EOF'
FROM golang:1.26 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /api ./cmd/api
 
FROM gcr.io/distroless/static-debian12
COPY --from=build /api /api
USER 65532:65532
ENTRYPOINT ["/api"]
EOF
 
docker build -t api:local .
CID=$(docker run -d -p 18080:8080 api:local)
sleep 2
curl -sf localhost:18080/healthz
docker logs "$CID" | tail -20
docker rm -f "$CID"
 
# --- kubectl: inspecionar deployment (nomes são exemplos) ---
kubectl get deploy,po -l app=api
kubectl rollout status deploy/api --timeout=120s
kubectl logs deploy/api --tail=100 --timestamps
kubectl describe pod -l app=api | rg -n "State:|Reason:|Exit Code:|Liveness|Readiness"

O que isto demonstra:

Build multi-stage produzindo uma imagem runtime distroless para Go.
Smoke test com porta publicada e cauda de logs antes da limpeza.
Espera de rollout do kubectl mais saída de describe filtrada com ripgrep para falhas de probe.

Mergulho Profundo

Como Funciona

docker build executa os estágios do Dockerfile; o estágio de compilação necessita do toolchain Go e do cache de módulos, o estágio de runtime frequentemente apenas copia o binário estático.
docker run inicia um container com mapeamentos de porta (-p host:container) e variáveis de ambiente opcionais (-e) espelhando as variáveis de ambiente do K8s.
kubectl logs lê o stdout/stderr do container do kubelet; -f segue, --previous mostra a última instância encerrada.
kubectl exec executa um processo no namespace de rede do pod - essencial quando a imagem runtime não possui shell (distroless).
kubectl port-forward cria um túnel de uma porta local para uma porta do pod para APIs pprof ou admin sem alterar o Service.

Referência de Comandos

Tarefa	docker	kubectl
Construir imagem	`docker build -t nome:tag .`	`kubectl apply -f` (após push)
Executar / implantar	`docker run -p ...`	`kubectl rollout restart deploy/nome`
Transmitir logs	`docker logs -f id`	`kubectl logs -f deploy/nome`
Shell	`docker exec -it id sh`	`kubectl exec -it po -- sh`
Porta de depuração	`-p 6060:6060`	`kubectl port-forward po 6060:6060`
Inspecionar saída	`docker inspect --format='{{.State.ExitCode}}'`	`kubectl describe po` Eventos

Notas Go

# Cache de módulos no estágio de build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/api ./cmd/api

Fixe a tag da imagem golang para a mesma versão menor que seu go.mod declara; alinhe com a política GOTOOLCHAIN em CI.

Armadilhas

Construindo em arquitetura errada - Apple Silicon constrói linux/arm64 enquanto o cluster é amd64. Correção: docker build --platform linux/amd64 ou construtores nativos de CI.
Distroless sem shell - kubectl exec sh falha. Correção: imagem de toolkit de depuração, container de depuração efêmero, ou scratch + copiar binário para um pod de depuração.
Logging para arquivos dentro de containers - Arquivos desaparecem na reinicialização; o kubelet apenas envia stdout/stderr. Correção: registrar em stdout; usar logging centralizado.
USER esquecido - Container executa como root apesar da boa prática do Go. Correção: USER não root correspondendo a securityContext.runAsNonRoot do Kubernetes.
Liveness matando inícios lentos - A inicialização do Go sem JVM é rápida, mas migrações podem atrasar a prontidão. Correção: separar prontidão (readiness) vs. vivacidade (liveness); ajustar initialDelaySeconds.
port-forward deixado rodando - Túneis contornam a política de rede localmente. Correção: fechar após depuração; nunca compartilhar portas de admin em 0.0.0.0.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
CLI docker	Build de imagem em Laptop e CI	Apenas frota de produção no Kubernetes
podman	Containers sem root no RHEL/Fedora	Equipe padronizada em Docker Desktop
kubectl debug	Containers de depuração efêmeros (K8s 1.23+)	Triagem simples apenas de logs
Helm / GitOps	Implantações declarativas	Você só precisa de um `log grep` único
systemd em VM	Nenhum orquestrador	Organização exige Kubernetes

FAQs

Imagens Go devem usar alpine ou distroless?

distroless/static minimiza a superfície de ataque para binários Go puros.

alpine adiciona um shell e gerenciador de pacotes quando os operadores querem ferramentas de depuração apk add.

Como vejo por que um pod reiniciou?

Eventos do kubectl describe pod e kubectl logs --previous para o último container terminado.

Posso executar a mesma imagem com docker run que a de produção?

Puxe pelo digest do seu registro e execute com as mesmas variáveis de ambiente e entrypoint.

Valida a integridade da imagem fora do cluster.

Como copio um perfil de um pod?

kubectl port-forward mais curl localmente, ou kubectl cp se o pod escreveu um arquivo em um volume.

Por que minha imagem está enorme apesar dos binários estáticos Go?

O estágio de build ou COPY . acidental inclui dados de teste e .git.

Use .dockerignore e builds multi-stage; o runtime deve conter apenas o binário.

Qual contexto kubectl devo usar?

kubectl config current-context antes de comandos destrutivos.

Flags de namespace (-n prod) evitam erros entre ambientes.

Como testar serviços gRPC?

grpcurl via kubectl port-forward para a porta gRPC, ou execute grpcurl em um container de depuração efêmero na rede do cluster.

O docker compose substitui o kubectl para desenvolvimento local?

Compose modela pilhas de desenvolvimento multi-serviço.

kubectl continua necessário para comportamento do cluster: probes, ConfigMaps e políticas de rede.

Como passo GOMAXPROCS ou GOGC?

Defina variáveis de ambiente do container no manifesto de Deployment - o mesmo que exports de shell em VMs.

E se os logs estiverem vazios?

O processo pode registrar em um arquivo ou falhar antes de escrever.

Verifique os códigos de saída do kubectl describe e execute a imagem com docker run --rm -it localmente.

Devo instalar plugins kubectl?

Plugins krew como ctx e ns aceleram a troca de contexto.

Verbos principais cobrem a maior parte da depuração de serviços Go.

Como reinicio um deployment após uma mudança de configuração?

kubectl rollout restart deploy/api aciona uma atualização contínua com a mesma tag de imagem se apenas o env foi alterado via aplicação do manifesto.

Relacionados

Build, Test & Profile from the Shell - pprof via port-forward
systemd & Service Unit Files for Go Binaries - alternativa de deploy em VM
Search, ripgrep & jq for Debugging - filtrar dumps de log
Linux CLI Skills for Go Engineers - fluxos de container vs VM
Cloud Deploy Basics - padrões de runtime na nuvem

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build), e golangci-lint (latest - verifique o conjunto de linters na build).

Containers da CLI: docker & kubectl

Buscar na documentação

Containers da CLI: docker & kubectl