Kubernetes Basics for Go Services

The objects your service lives in

graph TD
DEP["Deployment<br/>(desired: 3 replicas)"] --> RS["ReplicaSet"]
RS --> P1["Pod"]
RS --> P2["Pod"]
RS --> P3["Pod"]
SVC["Service<br/>(stable IP + DNS)"] -->|load-balances| P1
SVC --> P2
SVC --> P3
CM["ConfigMap / Secret"] -.->|env / mounted files| P1
CM -.-> P2
CM -.-> P3

• Pod — the smallest unit: one (usually) container with a shared network and lifecycle. Ephemeral by design.
• Deployment — declares N replicas of an image and reconciles to that state: self-heals crashed Pods, scales, and does rolling updates with rollback.
• Service — a stable virtual IP + DNS name that load-balances across the healthy Pods, hiding their ever-changing IPs.
• ConfigMap / Secret — non-secret and secret config, injected into Pods as env vars or files.

A minimal Deployment + Service

This is fenced (the sandbox has no cluster), but it’s a complete, real manifest for the image you built:

apiVersion: apps/v1
kind: Deployment
metadata: { name: api }
spec:
  replicas: 3                      # desired state: 3 identical Pods
  selector: { matchLabels: { app: api } }
  template:
    metadata: { labels: { app: api } }
    spec:
      containers:
        - name: api
          image: registry/api:abc123   # a specific tag, never :latest
          ports: [{ containerPort: 8080 }]
          env:
            - name: LOG_LEVEL
              valueFrom: { configMapKeyRef: { name: api-config, key: log_level } }
            - name: DB_PASSWORD
              valueFrom: { secretKeyRef: { name: api-secrets, key: db_password } }
          resources:
            requests: { cpu: "100m", memory: "64Mi" }   # scheduler reserves this
            limits:   { cpu: "500m", memory: "256Mi" }  # hard cap
          readinessProbe: { httpGet: { path: /readyz, port: 8080 } }
          livenessProbe:  { httpGet: { path: /healthz, port: 8080 } }
---
apiVersion: v1
kind: Service
metadata: { name: api }
spec:
  selector: { app: api }
  ports: [{ port: 80, targetPort: 8080 }]

The Deployment keeps 3 Pods alive; the Service gives clients a stable api name that load-balances across the ones currently passing their readiness probe.

See it: the app reads its identity from the environment

Kubernetes injects per-Pod identity via the downward API and config via env vars — your Go app just reads them, staying stateless and replica-agnostic. This runs here (env vars simulate what Kubernetes injects):

package main

import (
"fmt"
"os"
)

func getenv(k, def string) string {
if v, ok := os.LookupEnv(k); ok {
	return v
}
return def
}

func main() {
// Kubernetes injects these via the downward API + ConfigMap/Secret refs.
os.Setenv("POD_NAME", "api-7d9f-abc12")
os.Setenv("POD_NAMESPACE", "production")
os.Setenv("LOG_LEVEL", "info")

// The app treats itself as one interchangeable replica.
fmt.Println("pod:      ", getenv("POD_NAME", "local"))
fmt.Println("namespace:", getenv("POD_NAMESPACE", "default"))
fmt.Println("log level:", getenv("LOG_LEVEL", "warn"))
fmt.Println("db pass set:", os.Getenv("DB_PASSWORD") != "") // from a Secret
fmt.Println("-> stateless: any replica behaves identically")
}

The app never assumes it’s a particular instance — it reads its name for logs/metrics but holds no local state, so Kubernetes can kill and replace it freely. That statelessness is what makes scaling and self-healing work.

See also

• Dockerizing Go — the image this Deployment runs.
• Health & lifecycle — the probes the manifest references.
• Configuration — ConfigMaps, Secrets, and reading them in Go.
• The Go scheduler — GOMAXPROCS and container awareness.

Next: telling the cluster when you’re healthy and shutting down cleanly — health & lifecycle.

Related topics