Columns › 5. Going live and operating › Part 19
Deploying One Go Service with Docker and Kubernetes
Docker 與 Kubernetes 部署(單一服務)
Package a single Go service into a small, non-root distroless image with a multi-stage Dockerfile and a static binary, then run it on Kubernetes with a Deployment, Service, probes, resource limits, ConfigMap/Secret and safe rolling updates.
In this article
- What this article solves
- Step 1: A multi-stage Dockerfile and a static binary
- Step 2: Choosing a base image and running as non-root
- Step 3: Building, tagging and pushing the image
- Step 4: Injecting configuration with ConfigMaps and Secrets
- Step 5: Deployment, Service and probes
- Step 6: Resource requests and limits
- Step 7: Rolling updates and rollbacks
- Common pitfalls
- Key takeaways
- Next
In the previous article, “Configuration and Graceful Shutdown in Go”, we had the order service read its configuration from the environment, clean up in order when it receives SIGTERM, and expose /healthz and /readyz. This article packages that one service into a container image and runs it on Kubernetes, so that those designs actually connect to the platform.
What this article solves
"It works on my machine" is the line you hear most often about deployments. The cause is usually an inconsistent runtime environment: the local Go version, system libraries, environment variables and file paths all differ from the server's. Containers package a program together with the runtime environment it needs into an image, which starts the same way on any machine with a container runtime; Kubernetes then takes care of placing these containers on machines in a cluster, keeping the specified number running, restarting them on failure and replacing them gradually on update.
Go has a natural advantage here: it can compile a static binary that depends on no system libraries, so almost nothing else needs to go into the image, which can be very small, very clean and have a very small attack surface.
This article handles one service only: packaging the order service from cmd/order, pushing it to an image registry, and running it reliably on Kubernetes with the most basic objects. The goals are:
- The image is small, quick to build, reproducible, and runs as a non-root user.
- The image tag maps back to a source code version.
- Kubernetes knows when the service is "ready", when it is "stuck" and how many resources it needs.
- Configuration and secrets are injected by the platform, not baked into the image.
- Updating to a new version does not interrupt service, and problems can be rolled back quickly.
How the whole system (api-gateway, order, payment, inventory, plus the database and message queue) is deployed together is left to the two articles in the next part, "Deploying the system".
Step 1: A multi-stage Dockerfile and a static binary
The most intuitive Dockerfile uses the official golang image as its base, copies in the source code, compiles it and runs it directly. That works, but the final image contains the entire Go toolchain, the source code and the module cache, and can approach a gigabyte in size; it also contains a shell, a package manager and lots of other things that are never used at runtime, each of them a potential weakness.
A multi-stage build solves this: the first stage (build) compiles with the full Go image; the second stage (runtime) starts from a tiny base and copies over only the compiled binary. The final image contains only what is in the second stage.
# syntax=docker/dockerfile:1
ARG GO_VERSION=1.27
# ---- Stage 1: compile ----
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION} AS build
WORKDIR /src
# Copy only go.mod / go.sum first and download dependencies, so this layer stays cached when source code changes
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
ARG TARGETOS TARGETARCH
ARG VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache/go-build \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" \
-o /out/order ./cmd/order
# ---- Stage 2: run ----
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/order /order
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/order"]A few key choices, line by line:
CGO_ENABLED=0: turns off cgo so Go does not link against C libraries, producing a fully static binary. With cgo off, the standard library'snet(DNS resolution) andos/userswitch to pure Go implementations, which makes no difference to an ordinary service. If the project genuinely depends on cgo (for example some SQLite drivers), you cannot use ascratchorstaticbase and need an image that includes a C library.-trimpath: removes the build machine's file paths from the binary, so the build output does not depend on which machine built it and does not leak the directory layout.-ldflags="-s -w": strips the symbol table and DWARF debug information to shrink the file. The cost is that you cannot use a debugger on this binary; but stack traces on panic remain complete and pprof still works as usual, which the next article, “Performance Tuning in Go: pprof and Benchmarks”, relies on.-X main.version=...: writes the version string into a program variable at compile time; print it in the logs at startup and put it in a metric label, and when something goes wrong you can tell at a glance which version it is.--platform=$BUILDPLATFORMandTARGETOS/TARGETARCH: run the compiler on the build machine's native architecture and cross-compile to the target architecture. Go cross-compilation needs only environment variables, which is much faster than compiling under an emulator for another architecture, and can produce both amd64 and arm64 images in one go.- Cache mounts:
--mount=type=cachekeeps the module downloads and build cache between builds, so rebuilding after a small source change takes only a few seconds.
Remember to add a .dockerignore as well, excluding at least .git, local build output and any file containing secrets. The build context is sent to the build process as a whole; anything not excluded not only slows the build but can also end up in the first stage by accident through COPY . ..
Figure: the first stage has the full toolchain and source code, the second stage receives only a static binary, and the final image contains only what is on the right.
Step 2: Choosing a base image and running as non-root
There are a few common choices for the second stage's base:
| Base | Contents | Advantages | Watch out for |
|---|---|---|---|
scratch | Completely empty | Smallest | No CA certificates, time zone data or /etc/passwd, which you must copy in yourself; runs as root by default |
distroless/static | CA certificates, time zones, user definitions, no shell | Small and secure, with a built-in nonroot user | Cannot exec into it with a shell for debugging |
alpine | A small distribution with a shell | Convenient for debugging | Uses musl, so watch compatibility for cgo programs; has a package manager |
debian-slim etc. | A general-purpose distribution | Best compatibility | Large, with more vulnerability scan findings |
For a Go service built with CGO_ENABLED=0, the nonroot variant of distroless/static is usually the best balance. The order service calls a third-party payment provider over HTTPS and needs CA certificates to verify it; handling time zones in logs or reports needs time zone data. scratch has neither, and if you forget to add them the errors only appear at runtime. (Go also provides the time/tzdata package, which embeds time zone data directly into the binary.)
Running as non-root is the most important security setting at the image level. There is isolation between root inside a container and root on the host, but if a container escape vulnerability is ever exploited, a process running as root can do far more damage. The distroless nonroot user has UID 65532; the Dockerfile selects it with USER nonroot:nonroot, and the Kubernetes configuration in Step 4 adds another layer of enforcement with runAsNonRoot.
Non-root has one knock-on effect: the program cannot listen on ports below 1024. The Go service listens on 8080 inside the container, and the Kubernetes Service exposes port 80 to the outside; no privileges are needed.
Step 3: Building, tagging and pushing the image
An image's tag is the name used to pick a version at deployment time. A common mistake is to use only latest: it is not a guarantee of "the newest version", just a default name, and it gets overwritten. You cannot tell from latest which version is actually running in the cluster, nor roll back reliably.
A better approach is to use immutable tags, such as the short Git commit hash or a semantic version number: every build produces a new tag, and tags are never overwritten. At deployment time you can even reference the image's digest (sha256:...) directly, guaranteeing that exactly the same bytes are pulled.
# Use the commit hash as the version and tag
VERSION=$(git rev-parse --short HEAD)
IMAGE=registry.example.com/shop/order
# Build amd64 and arm64 in one go and push to the image registry
docker buildx build \
--platform linux/amd64,linux/arm64 \
--build-arg VERSION="$VERSION" \
-t "$IMAGE:$VERSION" \
--push .
# Local checks: image size, which user it runs as, whether it has a shell
docker build -t order:local .
docker image ls order:local
docker run --rm order:local # starts as nonroot
docker run --rm --entrypoint sh order:local # distroless has no shell, so this fails, as expected
# Get the digest after pushing; deployments can reference it directly
docker buildx imagetools inspect "$IMAGE:$VERSION"A distroless image containing only a static Go binary is usually somewhere between a dozen and a few dozen MB, depending mainly on the size of the program itself; compared with a version based on the full Go image, the difference is often tens of times. (The actual numbers depend on the program; this is only meant to convey the order of magnitude.) A small image pulls quickly and new Pods on a node start quickly, which shows up directly in waiting time during scale-up and rolling updates.
Before the build pipeline goes live, it is worth adding two more checks: scan the image with a vulnerability scanner, and confirm in continuous integration that the image really runs as non-root.
Tip: never pass secrets into a Dockerfile through
ARGorENV; they remain in the image's layers or history. If the build stage truly needs a secret (for example to pull private modules), use BuildKit's--mount=type=secret, which is mounted only while that oneRUNline executes and is never written into any layer.
Step 4: Injecting configuration with ConfigMaps and Secrets
The configuration principles from the previous article map onto two Kubernetes objects here: ordinary configuration goes in a ConfigMap and secrets go in a Secret. Both can become environment variables for the container or be mounted as files.
apiVersion: v1
kind: ConfigMap
metadata:
name: order-config
data:
ORDER_ADDR: ':8080'
ORDER_INVENTORY_URL: 'http://inventory:8080'
ORDER_SHUTDOWN_TIMEOUT: '20s'
---
apiVersion: v1
kind: Secret
metadata:
name: order-secrets
type: Opaque
stringData: # for the example only; in practice never commit real secrets to version control
database-url: 'postgres://order:CHANGE_ME@postgres:5432/shop?sslmode=require'In the Pod, the ConfigMap is turned into environment variables wholesale with envFrom; the Secret is better mounted as a read-only file, with the program reading the file through the ORDER_DATABASE_URL_FILE convention mentioned in the previous article. That way the secret does not appear in the environment variable list of kubectl describe pod and is not inherited by child processes.
Two points need particular attention. First, when a ConfigMap is injected as environment variables, changing the ConfigMap does not affect Pods that are already running; they must be restarted to pick up the new values. When it is mounted as files, the file contents update after a while, but the program has to re-read them for that to have any effect. A common practice is to write a hash of the configuration into an annotation on the Pod template: when the configuration changes, the Pod template changes with it, which automatically triggers a rolling update. Second, a Secret is by default only base64-encoded; real protection comes from the cluster's access control and etcd encryption, and in practice secret values are usually synced in from an external secret management service rather than written in YAML under version control.
Step 5: Deployment, Service and probes
A Deployment describes "which image to use, how many copies to run and how to update them". It creates a ReplicaSet, which in turn keeps the specified number of Pods running. A Service provides a stable name and virtual IP and spreads traffic across Pods that match its label selector and whose readiness probe passes; this is the platform's built-in service discovery mentioned in “Service Discovery and Load Balancing for Go Microservices”.
apiVersion: apps/v1
kind: Deployment
metadata:
name: order
labels: { app: order }
spec:
replicas: 3
revisionHistoryLimit: 5
selector:
matchLabels: { app: order }
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1 # at most 1 extra Pod during an update
maxUnavailable: 0 # never drop below replicas available Pods during an update
template:
metadata:
labels: { app: order }
spec:
terminationGracePeriodSeconds: 30
securityContext:
runAsNonRoot: true
seccompProfile: { type: RuntimeDefault }
containers:
- name: order
image: registry.example.com/shop/order:3f9c2ab
ports:
- { name: http, containerPort: 8080 }
envFrom:
- configMapRef: { name: order-config }
env:
- name: ORDER_DATABASE_URL_FILE
value: /etc/order/secrets/database-url
- name: GOMEMLIMIT # tell Go's GC the container memory limit
valueFrom:
resourceFieldRef: { resource: limits.memory }
volumeMounts:
- { name: secrets, mountPath: /etc/order/secrets, readOnly: true }
resources:
requests: { cpu: 250m, memory: 128Mi }
limits: { memory: 256Mi }
startupProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 2
failureThreshold: 30
readinessProbe:
httpGet: { path: /readyz, port: http }
periodSeconds: 5
livenessProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 10
failureThreshold: 3
lifecycle:
preStop:
sleep: { seconds: 5 }
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities: { drop: ['ALL'] }
volumes:
- name: secrets
secret: { secretName: order-secrets }
---
apiVersion: v1
kind: Service
metadata:
name: order
spec:
selector: { app: order }
ports:
- { name: http, port: 80, targetPort: http }
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: order
spec:
minAvailable: 2
selector:
matchLabels: { app: order }Figure: the Deployment manages Pods through a ReplicaSet, the Service sends traffic only to Pods whose readiness passes, and the ConfigMap and Secret are injected when the Pod starts.
The three probes each have their own job and map onto the two endpoints from the previous article:
- startupProbe: takes charge during startup (for example connecting to the database and warming up); until it succeeds, neither liveness nor readiness runs, so a slow start is not mistaken by liveness for a hang and restarted.
- readinessProbe: on failure the Pod is only removed from the Service's endpoint list, not restarted. During graceful shutdown
/readyzreturns 503, using exactly this behaviour to move traffic away early. - livenessProbe: restarts the container only after consecutive failures, and is used only to detect "the process is stuck and cannot recover on its own". Do not check external dependencies such as the database here, or a brief external outage will get every Pod restarted at once.
On the security side, runAsNonRoot refuses to start the container at all if the image would run as root, giving a double safeguard together with the Dockerfile's USER; readOnlyRootFilesystem makes the container's file system read-only, and if the program really needs a scratch directory you mount an extra emptyDir; capabilities: drop: ["ALL"] removes all Linux capabilities, which an ordinary Go network service never needs.
A PodDisruptionBudget (PDB) handles "voluntary disruptions", such as draining a node for maintenance or upgrading the cluster. The settings above require at least 2 Pods to be available at any time; maintenance tools respect this limit when evicting Pods and move one at a time, rather than evicting all three Pods at once.
Step 6: Resource requests and limits
resources is a block many people copy without much thought, but its impact on stability is actually large:
- requests are the basis for scheduling: Kubernetes only places a Pod on a node with enough remaining allocatable resources. They are also the basis for sharing CPU under contention. Set them too low and nodes get overpacked; set them too high and cluster resources are wasted.
- A CPU limit is hard throttling: when the process uses more, it is paused until the next period, which shows up as a sudden rise in latency rather than as errors. Many teams choose to set only CPU requests and no CPU limit, letting the service use idle CPU on the node; whether to do so depends on the cluster's multi-tenancy policy.
- A memory limit is a hard ceiling: exceed it and the kernel kills the process with OOM, and the Pod restarts. Memory cannot be throttled like CPU, so a memory limit should almost always be set.
A Go program in a container has two resource-related runtime settings to line up. The first is GOMEMLIMIT: the Deployment above uses resourceFieldRef to pass the container's memory limit, in bytes, into an environment variable, and Go's garbage collector reclaims more aggressively as it approaches that value, reducing the chance of being OOM-killed; in practice it is often set slightly below the limit to leave some room for non-heap memory. The second is GOMAXPROCS: since Go 1.25 it is set automatically on Linux from the container's CPU limit, whereas older versions see the whole node's core count, which causes heavy throttling when the CPU limit is low. The details of these parameters and how to tune them are covered further in the next article.
The most reliable basis for setting requests is the metrics from “Observability in Go: Logs, Metrics and Tracing”: observe CPU and memory usage under normal and peak traffic over a period of time, use that as the baseline and leave some headroom, rather than filling in a round number by feel.
Step 7: Rolling updates and rollbacks
When you change the Deployment's image tag to a new version, Kubernetes creates a new ReplicaSet and, following maxSurge and maxUnavailable, gradually adds new Pods and removes old ones. With the settings above (3 replicas, maxSurge: 1, maxUnavailable: 0), the process is: start one extra new Pod, wait for its readiness to pass, then stop one old Pod, and repeat until everything has been replaced by the new version. At no point are there fewer than 3 available Pods.
Figure: with maxSurge at 1 and maxUnavailable at 0, each round first gets one new Pod ready and then removes one old Pod, so the number of available Pods never drops below the configured value.
This process achieves zero downtime only because every earlier step plays its part: the readiness probe ensures a new Pod can really serve before it receives traffic; preStop and the graceful shutdown from the previous article ensure that removing an old Pod does not cut off in-flight requests; and terminationGracePeriodSeconds gives the clean-up enough time. Leave out any one of these and a rolling update can produce errors in the few seconds of the switchover.
# Update the image and watch progress; if new Pods never become ready, the rollout stays put and old Pods keep serving
kubectl set image deployment/order order=registry.example.com/shop/order:7d41e0c
kubectl rollout status deployment/order --timeout=5m
# View history and roll back to the previous version
kubectl rollout history deployment/order
kubectl rollout undo deployment/order
# Troubleshooting: Pod status, events, logs of the previous container (e.g. exited because config validation failed)
kubectl get pods -l app=order
kubectl describe pod -l app=order
kubectl logs deploy/order --previousIn practice, kubectl set image is usually replaced by a continuous deployment pipeline that rewrites the YAML and runs kubectl apply, so that the cluster's state matches the files in version control. Rollbacks work the same way: changing the YAML back to the previous tag and applying it is easier to track than rollout undo. This is also why Step 3 insists on immutable tags: only when a tag maps uniquely to one version does "go back to the previous version" have a clear meaning.
In addition, spec.progressDeadlineSeconds (600 seconds by default) determines how long a rolling update can go without progress before it is marked as failed. Combined with the previous article's "exit immediately on a configuration error", a new version with a bad configuration keeps restarting and never becomes ready, the rollout stops and reports failure, and the old version carries on serving completely unaffected.
Common pitfalls
- Using the
latesttag. You cannot know the actual version or roll back reliably, and combined withimagePullPolicydifferent nodes may even be running different images. Use immutable tags or digests. - Running the image as root. Use distroless's
nonrootor a custom UID, and addrunAsNonRoot: trueto the Pod. scratchlacking CA certificates or time zone data. Certificate verification errors on HTTPS calls and failed time conversions are often caused by this.- Baking secrets into the image. Secrets put in via
ENV,ARGorCOPYall remain in the image. Inject them at runtime through a Secret instead. - A liveness probe that is too strict or checks external dependencies. On a slow start or a brief database outage, every Pod gets restarted over and over. Leave startup to the startupProbe and have liveness check only the process itself.
- No readiness probe. New Pods receive traffic as soon as they start and return errors before the program is ready, so the error rate jumps during rolling updates.
- Setting only limits and no requests, or a memory limit that is too low. The former leaves scheduling with nothing to go on; the latter gets the Go program OOM-killed frequently. Pair it with
GOMEMLIMITand adjust based on real metrics. - Too short a grace period. If
terminationGracePeriodSecondsis less thanpreStopplus the in-program shutdown limit, the process is SIGKILLed halfway through its clean-up. - A single replica with a PDB of
minAvailable: 1. When a node is drained, this Pod can never be evicted and the maintenance gets stuck. Plan the replica count and the PDB together.
Key takeaways
- A multi-stage Dockerfile compiles with the full Go image and runs on a tiny base;
CGO_ENABLED=0,-trimpathand-ldflags="-s -w"produce a small, reproducible static binary. - The preferred base is the
nonrootvariant ofdistroless/static: it has CA certificates and time zones, no shell, and runs as non-root. - Images use immutable tags (commit hash or version number), deployed by digest where needed; secrets stay out of the image, and if the build needs one, use BuildKit's secret mount.
- Use a ConfigMap for configuration and a Secret mounted as a file for secrets; configuration changes need a rolling update so that Pods re-read them.
- A Deployment manages replicas and updates, and a Service provides a stable name and routes only to ready Pods; the startup, readiness and liveness probes each have their own job.
- Requests drive scheduling and the memory limit prevents runaway usage; pair Go programs with
GOMEMLIMITand keep an eye on howGOMAXPROCSrelates to the CPU limit. maxSurge/maxUnavailable, readiness, preStop, graceful shutdown and a PodDisruptionBudget together make zero-downtime rolling updates and node maintenance possible.- This article deployed only one service; deploying the whole system (several services, databases, message queues, an external entry point and autoscaling) is completed in the next part, "Deploying the system", in “Deploying a Whole Microservice System with Docker Compose” and “Deploying a Microservice System on Kubernetes”.
Next
The service now runs reliably in the cluster, but "it runs" is not the same as "it runs fast enough": how many resources to give it, which code uses the most CPU and why memory keeps growing can only be answered by measuring. “Performance Tuning in Go: pprof and Benchmarks” shows how to find bottlenecks with benchmarks and pprof, and how to tune runtime parameters such as GOGC and GOMEMLIMIT.