Run Gin on Kubernetes

By Khimananda Oli | Last reviewed: August 2026

You want to run Gin on Kubernetes because your Go API needs horizontal scaling, self-healing, and consistent deployments across environments. While Gin is lightweight and fast, running it reliably in a cluster requires specific configurations for containerization, health probing, and resource management that differ from standard tutorials. This guide covers the exact patterns I use to deploy production-grade Gin services, avoiding common pitfalls like missing graceful shutdowns or bloated images.

How Do You Containerize Gin for Kubernetes?

The foundation of any reliable Kubernetes deployment is the container image. For Go applications like Gin, you should never ship source code or build tools into production. A multi-stage build reduces attack surface and image size dramatically. In my experience auditing SOC 2 compliance for fintech clients, minimizing the container footprint is often the first remediation step security teams request.

This Dockerfile produces a static binary that runs without libc dependencies. The key flags are CGO_ENABLED=0 for static linking and -ldflags="-s -w" to strip debug symbols. Always use gcr.io/distroless/static-debian12 or alpine:3.19 as your runtime base; never use the full golang image in production.

<!-- Dockerfile -->
FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download && go mod verify
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-s -w -X main.version=$(git describe --tags --always)" \
    -o /out/server ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /out/server /server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]

A common mistake is forgetting go mod verify. This ensures dependency checksums match, preventing supply chain attacks. If you're integrating with databases, check our PostgreSQL administration essentials guide for connection pooling patterns that work well with Gin's concurrency model.

What Health Checks Does Gin Need on Kubernetes?

Kubernetes relies on probes to determine when your Gin application is ready to serve traffic and when it needs restarting. Without proper health endpoints, pods may receive requests before initialization completes or continue serving during failures. I've seen countless outages caused by missing readiness probes where new pods crashed under load immediately after deployment.

Your Gin application must expose three distinct endpoints. Separate them clearly—liveness indicates the process is alive, readiness confirms dependencies are available, and startup handles slow initialization. Here's a production-ready implementation:

// internal/handler/health.go
package handler

import (
    "context"
    "database/sql"
    "net/http"
    "sync/atomic"
    "time"

    "github.com/gin-gonic/gin"
)

type HealthHandler struct {
    db        *sql.DB
    ready     atomic.Bool
    startTime time.Time
}

func NewHealth(db *sql.DB) *HealthHandler {
    return &HealthHandler{db: db, startTime: time.Now()}
}

// StartupProbe: fails if app hasn't initialized within deadline
func (h *HealthHandler) Startup(c *gin.Context) {
    if time.Since(h.startTime) > 30*time.Second {
        c.JSON(http.StatusServiceUnavailable, gin.H{"status": "startup timeout"})
        return
    }
    if !h.ready.Load() {
        c.JSON(http.StatusServiceUnavailable, gin.H{"status": "initializing"})
        return
    }
    c.JSON(http.StatusOK, gin.H{"status": "started"})
}

// ReadinessProbe: checks DB connectivity and cache availability
func (h *HealthHandler) Ready(c *gin.Context) {
    ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Second)
    defer cancel()

    if err := h.db.PingContext(ctx); err != nil {
        c.JSON(http.StatusServiceUnavailable, gin.H{
            "status": "unhealthy",
            "error":  err.Error(),
        })
        return
    }
    c.JSON(http.StatusOK, gin.H{"status": "ready"})
}

// LivenessProbe: simple process check, no external deps
func (h *HealthHandler) Live(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"status": "alive"})
}

Configure these in your Deployment manifest with appropriate timing. Startup probes prevent premature kills during initialization. Readiness probes gate traffic. Liveness probes catch deadlocks. Never make liveness depend on database connectivity—a transient DB outage shouldn't restart your entire fleet.

How Do You Configure Resource Limits for Gin?

Gin applications typically consume far fewer resources than Java or Node.js equivalents, but setting limits incorrectly causes throttling or OOMKills. Based on profiling hundreds of Go services, here are evidence-based defaults for most REST APIs:

Always set requests equal to observed P95 usage and limits at 2-4x requests. Go's garbage collector scales with memory limit, so overly generous limits increase GC pause times. Use Vertical Pod Autoscaler in recommendation mode to right-size based on actual metrics. For deeper tuning guidance, see Kubernetes resource limits and requests.

How Do You Handle Graceful Shutdown in Gin?

Kubernetes sends SIGTERM when terminating pods. Without proper handling, in-flight requests drop and users see errors. Gin supports graceful shutdown natively via signal.NotifyContext. This is non-negotiable for zero-downtime deployments, especially when using blue-green or canary strategies.

// cmd/server/main.go
package main

import (
    "context"
    "errors"
    "log/slog"
    "net/http"
    "os/signal"
    "syscall"
    "time"

    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.New()
    // ... register routes ...

    srv := &http.Server{
        Addr:         ":8080",
        Handler:      r,
        ReadTimeout:  15 * time.Second,
        WriteTimeout: 30 * time.Second,
        IdleTimeout:  60 * time.Second,
    }

    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
    defer stop()

    go func() {
        slog.Info("starting server", "addr", srv.Addr)
        if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
            slog.Error("server error", "err", err)
        }
    }()

    <-ctx.Done()
    slog.Info("shutdown signal received, draining...")

    shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
    defer cancel()

    if err := srv.Shutdown(shutdownCtx); err != nil {
        slog.Error("graceful shutdown failed", "err", err)
    } else {
        slog.Info("server stopped cleanly")
    }
}

Set terminationGracePeriodSeconds to at least 35 seconds in your Deployment spec. This gives Gin 25 seconds to drain plus buffer for endpoint propagation. Monitor shutdown duration via metrics—if drains regularly hit the timeout, investigate long-running queries or WebSocket connections that block closure.

What Deployment Manifest Works Best for Gin?

Combine all elements into a production-ready Deployment. This template includes anti-affinity for HA, topology spread for zone resilience, and security hardening aligned with ISO 27001 controls:

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gin-api
  labels:
    app.kubernetes.io/name: gin-api
    app.kubernetes.io/version: v1.4.2
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: gin-api
  template:
    metadata:
      labels:
        app.kubernetes.io/name: gin-api
    spec:
      securityContext:
        runAsNonRoot: true
        fsGroup: 65534
      containers:
      - name: gin-api
        image: registry.example.com/gin-api:v1.4.2
        ports:
        - containerPort: 8080
          protocol: TCP
        env:
        - name: GIN_MODE
          value: release
        - name: DB_DSN
          valueFrom:
            secretKeyRef:
              name: gin-api-secrets
              key: db-dsn
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi
        startupProbe:
          httpGet:
            path: /startupz
            port: 8080
          initialDelaySeconds: 2
          periodSeconds: 2
          failureThreshold: 15
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8080
          periodSeconds: 5
          failureThreshold: 3
        livenessProbe:
          httpGet:
            path: /livez
            port: 8080
          periodSeconds: 10
          failureThreshold: 3
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          capabilities:
            drop: ["ALL"]
      topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: topology.kubernetes.io/zone
        whenUnsatisfiable: DoNotSchedule
        labelSelector:
          matchLabels:
            app.kubernetes.io/name: gin-api

Note the readOnlyRootFilesystem constraint. Gin doesn't need write access unless you're logging to disk (don't—use stdout). This prevents attackers from writing malicious scripts even if they achieve RCE. Pair this with NetworkPolicies restricting egress to only required destinations.

Running Gin on Kubernetes Reliably

Successfully operating Gin in production comes down to four pillars: minimal container images, comprehensive health probes, right-sized resources, and graceful lifecycle management. These aren't optional optimizations—they're requirements for passing security audits and maintaining uptime SLAs. Start with the deployment manifest above, instrument with OpenTelemetry for visibility, and iterate based on real metrics rather than guesses. If your team needs help architecting or auditing Go microservices infrastructure, reach out directly to discuss your specific requirements.