Conceptos básicos de despliegue

10 ejemplos para empezar con Deploy & K8s: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Instala Docker para compilaciones de imágenes y un clúster de Kubernetes local (kind, minikube o Docker Desktop Kubernetes).
• Instala kubectl y verifica el acceso al clúster: kubectl cluster-info.
• Crea un módulo: mkdir deploylab && cd deploylab && go mod init example.com/deploylab.

Ejemplos básicos

1. Binario de lanzamiento con go build

Produce un binario optimizado para Linux desde la raíz de tu módulo.

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
  -ldflags="-s -w" -o bin/api ./cmd/api

• CGO_ENABLED=0 genera un binario estático adecuado para imágenes scratch/distroless.
• -trimpath elimina rutas del sistema de archivos local de los binarios para compilaciones reproducibles.
• -ldflags="-s -w" elimina símbolos de depuración para reducir el tamaño del artefacto.

Relacionado: Despliegue de Go: Binario único como superpoder - por qué un solo archivo cambia las operaciones

2. Incrustar metadatos de versión en tiempo de compilación

Estampa la versión de git en el binario para depuración en producción.

package main
 
import "fmt"
 
var (
    version = "dev"
    commit  = "none"
)
 
func main() {
    fmt.Printf("api %s (%s)\n", version, commit)
}

go build -ldflags="-X main.version=1.2.3 -X main.commit=$(git rev-parse --short HEAD)" -o bin/api .

• -X establece variables de cadena en main en tiempo de enlace.
• Registra la versión al inicio para que los incidentes se mapeen a los números de compilación de CI.
• Conserva compilaciones de depuración sin despojar en el almacenamiento de artefactos para simbolización.

Relacionado: Canales de CI/CD para servicios Go - automatiza el estampado de versiones en CI

3. Servidor HTTP mínimo para contenedores

Enlaza a PORT desde el entorno, el patrón predeterminado para PaaS y Kubernetes.

package main
 
import (
    "fmt"
    "log"
    "net/http"
    "os"
)
 
func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "hello")
    })
    log.Fatal(http.ListenAndServe(":"+port, nil))
}

• Los contenedores deben escuchar en todas las interfaces (:8080), no en 127.0.0.1.
• Lee PORT del entorno para que las plataformas puedan asignar puertos efímeros.
• Añade tiempos de espera explícitos antes de producción; los valores predeterminados no son seguros detrás de los balanceadores de carga.

Relacionado: Compilaciones Docker de varias etapas para Go - empaqueta este servidor en una imagen mínima

4. Endpoint de salud Liveness-Ready

Expone un endpoint económico que las sondas de Kubernetes pueden llamar.

http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ok"))
})

• Liveness debe responder "¿está el proceso activo?" sin acceder a bases de datos.
• Readiness puede comprobar dependencias; mantenlo rápido para evitar inestabilidad durante los despliegues.
• Devuelve un código distinto de 200 cuando el proceso deba dejar de recibir tráfico.

Relacionado: Sondas, HPA y Presupuestos de Interrupción de Pods - ajuste de sondas y escalado automático

5. Dockerfile de una sola etapa (Ruta de aprendizaje)

Una imagen de tiempo de ejecución simple de dos líneas para experimentos locales.

FROM golang:1.26-bookworm AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /api ./cmd/api
 
FROM debian:bookworm-slim
COPY --from=build /api /api
EXPOSE 8080
ENTRYPOINT ["/api"]

• Las etapas múltiples mantienen las herramientas de compilación fuera de la capa de tiempo de ejecución.
• Incluso los Dockerfiles de aprendizaje deben establecer CGO_ENABLED=0 para binarios portátiles de Linux.
• Los equipos de producción pasan a distroless; esta etapa debian-slim es más fácil de depurar localmente.

Relacionado: Compilaciones Docker de varias etapas para Go - distroless y certificados CA

6. Compilar y ejecutar la imagen localmente

Etiqueta con un semver o SHA de git, nunca solo latest en entornos compartidos.

docker build -t deploylab/api:0.1.0 .
docker run --rm -p 8080:8080 -e PORT=8080 deploylab/api:0.1.0
curl -s localhost:8080/healthz

• Las etiquetas inmutables vinculan los contenedores en ejecución a los artefactos de CI.
• Mapea el puerto 8080 del host al PORT del contenedor para pruebas rápidas.
• Sube la misma etiqueta que tu manifiesto de Kubernetes referencia.

Relacionado: Mejores prácticas de despliegue - etiquetas semver y disciplina de reversión

7. Despliegue mínimo de Kubernetes

Ejecuta una réplica con solicitudes de recursos para que el planificador pueda colocar el pod.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: deploylab/api:0.1.0
          ports:
            - containerPort: 8080
          env:
            - name: PORT
              value: "8080"
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              memory: 128Mi

kubectl apply -f deployment.yaml
kubectl rollout status deployment/api

• resources.requests ayuda al planificador y a las líneas base de HPA.
• Fija image a una etiqueta o digest específico, no a un latest flotante.
• Observa el estado del despliegue antes de declarar que el despliegue está completo.

Relacionado: Despliegues, Servicios e Ingress de Kubernetes - Servicios, Ingress y límites

Ejemplos intermedios

8. Servicio ClusterIP y reenvío de puertos

Expón el Despliegue dentro del clúster y prueba sin Ingress.

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f service.yaml
kubectl port-forward svc/api 8080:80
curl -s localhost:8080/healthz

• Los servicios enrutan DNS estable (api.default.svc.cluster.local) a las IPs de los pods.
• targetPort debe coincidir con el puerto de escucha del contenedor.
• El reenvío de puertos es para desarrollo; producción utiliza Ingress o Servicios LoadBalancer.

Relacionado: Despliegues, Servicios e Ingress de Kubernetes - reglas de Ingress y TLS

9. Sondas HTTP en el Despliegue

Conecta las sondas de liveness y readiness a /healthz.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /healthz
    port: 8080
  periodSeconds: 5

• initialDelaySeconds evita matar pods que aún están enlazando puertos.
• El fallo de Readiness elimina el pod de los endpoints del Servicio durante el inicio.
• Ajusta periodSeconds y timeoutSeconds a tu SLO y tiempo de arranque en frío.

Relacionado: Sondas, HPA y Presupuestos de Interrupción de Pods - PDBs y escalado automático

10. Cierre elegante con SIGTERM

Kubernetes envía SIGTERM antes de SIGKILL; vacía las solicitudes en curso.

package main
 
import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)
 
func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("ok"))
    })
    srv := &http.Server{Addr: ":8080", Handler: mux}
 
    go func() {
        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            log.Fatal(err)
        }
    }()
 
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
    <-stop
 
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()
    if err := srv.Shutdown(ctx); err != nil {
        log.Fatal(err)
    }
}

• Shutdown deja de aceptar nuevas conexiones y espera las solicitudes activas.
• Haz coincidir el período de gracia de terminación en la especificación del pod con tu tiempo de espera de cierre.
• Durante los despliegues, el fallo de Readiness junto con el cierre elegante evita solicitudes perdidas.

Relacionado: Hooks de ingeniería del caos para microservicios Go - valida el comportamiento bajo fallo

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

pbqrthvqrf.vb|ptvb406|202607