Contenedores desde la CLI: docker & kubectl

Q: ¿Deberían las imágenes de Go usar alpine o distroless?

distroless/static minimiza la superficie de ataque para binarios Go puros. alpine añade un shell y un gestor de paquetes cuando los operadores quieren herramientas de depuración con apk add.

Q: ¿Cómo veo por qué se reinició un pod?

Eventos de kubectl describe pod y kubectl logs --previous para el último contenedor terminado.

Q: ¿Cómo copio un perfil de un pod?

kubectl port-forward más curl localmente, o kubectl cp si el pod escribió un archivo en un volumen.

Q: ¿Por qué mi imagen es enorme a pesar de los binarios estáticos de Go?

La etapa de compilación o un COPY . accidental incluye datos de prueba y .git. Usa .dockerignore y compilaciones multi-etapa; el runtime solo debe contener el binario.

Q: ¿Qué contexto de kubectl debo usar?

kubectl config current-context antes de comandos destructivos. Las banderas de namespace (-n prod) evitan errores entre entornos.

Q: ¿Cómo pruebo servicios gRPC?

grpcurl a través de kubectl port-forward al puerto gRPC, o ejecuta grpcurl en un contenedor de depuración efímero en la red del clúster.

Q: ¿docker compose reemplaza a kubectl para el desarrollo local?

Compose modela pilas de desarrollo multi-servicio. kubectl sigue siendo necesario para el comportamiento del clúster: sondas, ConfigMaps y políticas de red.

Compila y ejecuta imágenes de Go con docker localmente, luego depura pods en Kubernetes con kubectl logs, exec y port-forward.

Resumen

Los binarios estáticos de Go encajan en imágenes de contenedor mínimas, pero los problemas de producción aún se manifiestan a través de las CLIs de los contenedores: un pod en un bucle de reinicio (CrashLoopBackOff), una imagen que funciona en tu portátil pero no en CI, o una verificación de estado (health check) que nunca llega a estar lista.

Estos comandos son el camino más rápido desde el síntoma hasta el proceso dentro del clúster.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

# Dockerfile (multi-etapa)
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

Cuándo usar esto:

Reproducir una imagen de producción localmente antes de enviarla a un registro.
Un pod de Go está en CrashLoopBackOff y necesitas logs y códigos de salida rápidamente.
Debes acceder a un puerto de depuración o pprof sin exponerlo en un Service público.

Ejemplo de Trabajo

#!/usr/bin/env bash
set -euo pipefail
 
# --- docker: compilar y probar rápidamente ---
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: inspeccionar despliegue (los nombres son ejemplos) ---
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"

Lo que esto demuestra:

Compilación multi-etapa que produce una imagen de runtime distroless para Go.
Prueba rápida con puerto publicado y cola de logs antes de la limpieza.
Espera de despliegue de kubectl más salida de describe filtrada con ripgrep para fallos de sondas.

Profundización

Cómo Funciona

docker build ejecuta las etapas del Dockerfile; la etapa de compilación necesita el toolchain de Go y la caché de módulos, la etapa de runtime a menudo solo copia el binario estático.
docker run inicia un contenedor con mapeos de puertos (-p host:container) y variables de entorno opcionales (-e) que reflejan las variables de entorno de K8s.
kubectl logs lee la salida estándar/error estándar del contenedor desde el kubelet; -f sigue la salida, --previous muestra la última instancia fallida.
kubectl exec ejecuta un proceso en el espacio de nombres de red del pod, esencial cuando la imagen de runtime no tiene shell (distroless).
kubectl port-forward crea un túnel de un puerto local a un puerto de pod para APIs de pprof o de administración sin modificar el Service.

Referencia de Comandos

Tarea	docker	kubectl
Compilar imagen	`docker build -t nombre:etiqueta .`	`kubectl apply -f` (después de push)
Ejecutar / desplegar	`docker run -p ...`	`kubectl rollout restart deploy/nombre`
Transmitir logs	`docker logs -f id`	`kubectl logs -f deploy/nombre`
Shell	`docker exec -it id sh`	`kubectl exec -it po -- sh`
Puerto de depuración	`-p 6060:6060`	`kubectl port-forward po 6060:6060`
Inspeccionar salida	`docker inspect --format='{{.State.ExitCode}}'`	`kubectl describe po` Eventos

Notas de Go

# Caché de módulos en la etapa de compilación
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/api ./cmd/api

Fija la etiqueta de la imagen golang a la misma versión menor que declara tu go.mod; alinéate con la política GOTOOLCHAIN en CI.

Trampas Comunes

Compilación en arquitectura incorrecta - Apple Silicon compila linux/arm64 mientras que el clúster es amd64. Solución: docker build --platform linux/amd64 o constructores nativos de CI.
Distroless sin shell - kubectl exec sh falla. Solución: imagen de kit de herramientas de depuración, contenedor de depuración efímero, o scratch + copiar binario a un pod de depuración.
Registrar en archivos dentro de contenedores - Los archivos desaparecen al reiniciar; kubelet solo envía stdout/stderr. Solución: registrar en stdout; usar registro centralizado.
USER olvidado - El contenedor se ejecuta como root a pesar de las mejores prácticas de Go. Solución: USER no root que coincida con securityContext.runAsNonRoot de Kubernetes.
Liveness matando arranques lentos - El arranque de Go sin JVM es rápido, pero las migraciones pueden retrasar la preparación. Solución: separar readiness de liveness; ajustar initialDelaySeconds.
port-forward dejado ejecutándose - Los túneles eluden la política de red localmente. Solución: cerrar después de depurar; nunca compartir puertos de administración en 0.0.0.0.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
docker CLI	Portátil y compilación de imágenes en CI	Flota de producción solo en Kubernetes
podman	Contenedores sin root en RHEL/Fedora	Equipo estandarizado en Docker Desktop
kubectl debug	Contenedores de depuración efímeros (K8s 1.23+)	Triaje simple solo de logs
Helm / GitOps	Despliegues declarativos	Solo necesitas buscar logs una vez
systemd en VM	Sin orquestador	La organización exige Kubernetes

Preguntas Frecuentes

¿Deberían las imágenes de Go usar alpine o distroless?

distroless/static minimiza la superficie de ataque para binarios Go puros.

alpine añade un shell y un gestor de paquetes cuando los operadores quieren herramientas de depuración con apk add.

¿Cómo veo por qué se reinició un pod?

Eventos de kubectl describe pod y kubectl logs --previous para el último contenedor terminado.

¿Puedo ejecutar con `docker run` la misma imagen que en producción?

Descarga por digest de tu registro y ejecuta con las mismas variables de entorno y ENTRYPOINT.

Valida la integridad de la imagen fuera del clúster.

¿Cómo copio un perfil de un pod?

kubectl port-forward más curl localmente, o kubectl cp si el pod escribió un archivo en un volumen.

¿Por qué mi imagen es enorme a pesar de los binarios estáticos de Go?

La etapa de compilación o un COPY . accidental incluye datos de prueba y .git.

Usa .dockerignore y compilaciones multi-etapa; el runtime solo debe contener el binario.

¿Qué contexto de kubectl debo usar?

kubectl config current-context antes de comandos destructivos.

Las banderas de namespace (-n prod) evitan errores entre entornos.

¿Cómo pruebo servicios gRPC?

grpcurl a través de kubectl port-forward al puerto gRPC, o ejecuta grpcurl en un contenedor de depuración efímero en la red del clúster.

¿`docker compose` reemplaza a `kubectl` para el desarrollo local?

Compose modela pilas de desarrollo multi-servicio.

kubectl sigue siendo necesario para el comportamiento del clúster: sondas, ConfigMaps y políticas de red.

¿Cómo paso GOMAXPROCS o GOGC?

Establece variables de entorno del contenedor en el manifiesto de Deployment - igual que las exportaciones de shell en VMs.

¿Qué pasa si los logs están vacíos?

El proceso puede registrar en un archivo o fallar antes de escribir.

Comprueba los códigos de salida de kubectl describe y ejecuta la imagen con docker run --rm -it localmente.

¿Debo instalar plugins de kubectl?

Los plugins de krew como ctx y ns aceleran el cambio de contexto.

Los verbos principales cubren la mayor parte de la depuración de servicios Go.

¿Cómo reinicio un despliegue después de un cambio de configuración?

kubectl rollout restart deploy/api activa una actualización continua con la misma etiqueta de imagen si solo cambiaron las variables de entorno a través de la aplicación del manifiesto.

Relacionados

Compilar, Probar y Perfilar desde la Shell - pprof a través de port-forward
systemd y Archivos de Unidad de Servicio para Binarios Go - alternativa de despliegue en VM
Search, ripgrep y jq para Depuración - filtrar volcados de logs
Habilidades de CLI de Linux para Ingenieros Go - flujos de contenedores vs VM
Conceptos Básicos de Despliegue en la Nube - patrones de runtime en la nube

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación).

Resumen

Estos comandos son el camino más rápido desde el síntoma hasta el proceso dentro del clúster.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

# Dockerfile (multi-etapa)
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

Cuándo usar esto:

Reproducir una imagen de producción localmente antes de enviarla a un registro.
Un pod de Go está en CrashLoopBackOff y necesitas logs y códigos de salida rápidamente.
Debes acceder a un puerto de depuración o pprof sin exponerlo en un Service público.

Ejemplo de Trabajo

#!/usr/bin/env bash
set -euo pipefail
 
# --- docker: compilar y probar rápidamente ---
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: inspeccionar despliegue (los nombres son ejemplos) ---
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"

Lo que esto demuestra:

Compilación multi-etapa que produce una imagen de runtime distroless para Go.
Prueba rápida con puerto publicado y cola de logs antes de la limpieza.
Espera de despliegue de kubectl más salida de describe filtrada con ripgrep para fallos de sondas.

Profundización

Cómo Funciona

docker build ejecuta las etapas del Dockerfile; la etapa de compilación necesita el toolchain de Go y la caché de módulos, la etapa de runtime a menudo solo copia el binario estático.
docker run inicia un contenedor con mapeos de puertos (-p host:container) y variables de entorno opcionales (-e) que reflejan las variables de entorno de K8s.
kubectl logs lee la salida estándar/error estándar del contenedor desde el kubelet; -f sigue la salida, --previous muestra la última instancia fallida.
kubectl exec ejecuta un proceso en el espacio de nombres de red del pod, esencial cuando la imagen de runtime no tiene shell (distroless).
kubectl port-forward crea un túnel de un puerto local a un puerto de pod para APIs de pprof o de administración sin modificar el Service.

Referencia de Comandos

Tarea	docker	kubectl
Compilar imagen	`docker build -t nombre:etiqueta .`	`kubectl apply -f` (después de push)
Ejecutar / desplegar	`docker run -p ...`	`kubectl rollout restart deploy/nombre`
Transmitir logs	`docker logs -f id`	`kubectl logs -f deploy/nombre`
Shell	`docker exec -it id sh`	`kubectl exec -it po -- sh`
Puerto de depuración	`-p 6060:6060`	`kubectl port-forward po 6060:6060`
Inspeccionar salida	`docker inspect --format='{{.State.ExitCode}}'`	`kubectl describe po` Eventos

Notas de Go

# Caché de módulos en la etapa de compilación
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/api ./cmd/api

Fija la etiqueta de la imagen golang a la misma versión menor que declara tu go.mod; alinéate con la política GOTOOLCHAIN en CI.

Trampas Comunes

Compilación en arquitectura incorrecta - Apple Silicon compila linux/arm64 mientras que el clúster es amd64. Solución: docker build --platform linux/amd64 o constructores nativos de CI.
Distroless sin shell - kubectl exec sh falla. Solución: imagen de kit de herramientas de depuración, contenedor de depuración efímero, o scratch + copiar binario a un pod de depuración.
Registrar en archivos dentro de contenedores - Los archivos desaparecen al reiniciar; kubelet solo envía stdout/stderr. Solución: registrar en stdout; usar registro centralizado.
USER olvidado - El contenedor se ejecuta como root a pesar de las mejores prácticas de Go. Solución: USER no root que coincida con securityContext.runAsNonRoot de Kubernetes.
Liveness matando arranques lentos - El arranque de Go sin JVM es rápido, pero las migraciones pueden retrasar la preparación. Solución: separar readiness de liveness; ajustar initialDelaySeconds.
port-forward dejado ejecutándose - Los túneles eluden la política de red localmente. Solución: cerrar después de depurar; nunca compartir puertos de administración en 0.0.0.0.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
docker CLI	Portátil y compilación de imágenes en CI	Flota de producción solo en Kubernetes
podman	Contenedores sin root en RHEL/Fedora	Equipo estandarizado en Docker Desktop
kubectl debug	Contenedores de depuración efímeros (K8s 1.23+)	Triaje simple solo de logs
Helm / GitOps	Despliegues declarativos	Solo necesitas buscar logs una vez
systemd en VM	Sin orquestador	La organización exige Kubernetes

Preguntas Frecuentes

¿Deberían las imágenes de Go usar alpine o distroless?

distroless/static minimiza la superficie de ataque para binarios Go puros.

alpine añade un shell y un gestor de paquetes cuando los operadores quieren herramientas de depuración con apk add.

¿Cómo veo por qué se reinició un pod?

Eventos de kubectl describe pod y kubectl logs --previous para el último contenedor terminado.

¿Puedo ejecutar con `docker run` la misma imagen que en producción?

Descarga por digest de tu registro y ejecuta con las mismas variables de entorno y ENTRYPOINT.

Valida la integridad de la imagen fuera del clúster.

¿Cómo copio un perfil de un pod?

kubectl port-forward más curl localmente, o kubectl cp si el pod escribió un archivo en un volumen.

¿Por qué mi imagen es enorme a pesar de los binarios estáticos de Go?

La etapa de compilación o un COPY . accidental incluye datos de prueba y .git.

Usa .dockerignore y compilaciones multi-etapa; el runtime solo debe contener el binario.

¿Qué contexto de kubectl debo usar?

kubectl config current-context antes de comandos destructivos.

Las banderas de namespace (-n prod) evitan errores entre entornos.

¿Cómo pruebo servicios gRPC?

grpcurl a través de kubectl port-forward al puerto gRPC, o ejecuta grpcurl en un contenedor de depuración efímero en la red del clúster.

¿`docker compose` reemplaza a `kubectl` para el desarrollo local?

Compose modela pilas de desarrollo multi-servicio.

kubectl sigue siendo necesario para el comportamiento del clúster: sondas, ConfigMaps y políticas de red.

¿Cómo paso GOMAXPROCS o GOGC?

Establece variables de entorno del contenedor en el manifiesto de Deployment - igual que las exportaciones de shell en VMs.

¿Qué pasa si los logs están vacíos?

El proceso puede registrar en un archivo o fallar antes de escribir.

Comprueba los códigos de salida de kubectl describe y ejecuta la imagen con docker run --rm -it localmente.

¿Debo instalar plugins de kubectl?

Los plugins de krew como ctx y ns aceleran el cambio de contexto.

Los verbos principales cubren la mayor parte de la depuración de servicios Go.

¿Cómo reinicio un despliegue después de un cambio de configuración?

kubectl rollout restart deploy/api activa una actualización continua con la misma etiqueta de imagen si solo cambiaron las variables de entorno a través de la aplicación del manifiesto.

Relacionados

Compilar, Probar y Perfilar desde la Shell - pprof a través de port-forward
systemd y Archivos de Unidad de Servicio para Binarios Go - alternativa de despliegue en VM
Search, ripgrep y jq para Depuración - filtrar volcados de logs
Habilidades de CLI de Linux para Ingenieros Go - flujos de contenedores vs VM
Conceptos Básicos de Despliegue en la Nube - patrones de runtime en la nube

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación).

Contenedores desde la CLI: docker & kubectl

Buscar en la documentación

Contenedores desde la CLI: docker & kubectl