A Go binary can start in seconds, but production failures rarely come from compilation. They come from missing secrets, weak health checks, root containers, or a rollback nobody tested.
When you deploy Go application code, treat the release as an operating process. Your build, configuration, logs, probes, and recovery plan all need a clear owner.
Start by making the service predictable before you choose a server or cloud platform.
How to deploy Go application code to production
A production deployment starts with a fixed release target. Build one version, record its image digest, test it, then promote that same artifact. Don’t rebuild the application on the production host.
Use a currently supported Go release. Go maintains the newest two major releases, and its official release history shows the current stable versions. Update on a planned cycle instead of waiting for a security incident.
Keep development and production separate
Local development can use go run ./cmd/api, a local .env file, and debug logging. Those settings are useful when you are changing code.
Production needs a compiled binary, runtime secrets, JSON logs, restricted permissions, and a fixed image digest. Never copy a development .env file to a cloud server.
Use a release record for every deployment:
- Git commit SHA and semantic version.
- Container image digest, not only a mutable tag such as
latest. - Configuration version or secret revision.
- Deployment owner, start time, and final status.
- The previous known-good release.
Don’t overwrite a failed release record. Add the rollback event as a new entry. You need the history when an incident review starts.
Define the application contract
Your service needs a port, a readiness endpoint, a liveness endpoint, and a shutdown deadline.
Use PORT for the listener address. Keep /healthz cheap. It should confirm that the process can answer HTTP requests. Use /readyz to state whether the service should receive traffic.
A database migration or an unavailable dependency can make a service unready without making the process dead. That distinction stops an orchestrator from restarting healthy processes during a temporary database outage.
Add health checks and graceful shutdown
A production HTTP service must stop accepting new work before it exits. Kubernetes, Cloud Run, ECS, and most process managers send SIGTERM during a replacement or shutdown.
The net/http package documents Server.Shutdown, which closes listeners and waits for active requests to finish. Review the Go HTTP server documentation before adding custom signal handling.
A runnable Go server example
This example assumes an HTTP service with no database dependency yet. Copy these lines into cmd/api/main.go, then run go run ./cmd/api.
package main
import (
"context"
"errors"
"log/slog"
"net/http"
"os"
"os/signal"
"sync/atomic"
"syscall"
"time"
)
func main() {
var ready atomic.Bool
ready.Store(true)
mux := http.NewServeMux()
mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })
mux.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) { if !ready.Load() { http.Error(w, "not ready", 503); return }; w.WriteHeader(http.StatusOK) })
srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
errCh := make(chan error, 1)
go func() { errCh <- srv.ListenAndServe() }()
select {
case err := <-errCh:
if !errors.Is(err, http.ErrServerClosed) { slog.Error("server failed", "error", err); os.Exit(1) }
case <-ctx.Done():
ready.Store(false)
shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil { slog.Error("shutdown failed", "error", err) }
}
}
Give shutdown enough time
When a termination signal arrives, /readyz should fail first. Your platform then removes the instance from traffic while the service finishes active requests.
Set the application’s shutdown timeout below the platform termination limit. For example, use a 25-second Go timeout with a 35-second Kubernetes grace period. Leave room for the process to close connections and exit.
A liveness probe should not fail because a downstream API is slow. Restart loops make an external outage worse.
For Kubernetes timing details, see this practical guide to graceful Go shutdowns with rolling updates.
Build a small, repeatable container image
A multi-stage build compiles the binary in one image and copies only the output into the runtime image. Docker documents this multi-stage build pattern.
Create Dockerfile with these lines. Replace <GO_VERSION> with your approved supported release.
# syntax=docker/dockerfile:1.7
FROM --platform=$BUILDPLATFORM golang:<GO_VERSION> AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download && go mod verify
COPY . .
ARG TARGETOS
ARG TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -buildvcs=false -ldflags="-s -w" -o /out/app ./cmd/api
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]
Build the image with docker build -t <REGISTRY>/<APP_NAME>:<GIT_SHA> .. Replace every value inside angle brackets before you run the command.
Verify the release artifact
Run tests before building the image: go test ./... and go vet ./....
The -trimpath flag removes local source paths. -buildvcs=false stops build metadata from changing because of the machine that produced it. Keep go.sum committed, and review dependency changes in pull requests.
Pin production base images by digest after testing them. A tag can move. A digest cannot.
CGO_ENABLED=0 supports a static binary and a minimal runtime image. Remove that setting only when your application has a real cgo dependency.
Load secrets at runtime and restrict permissions
A secret in a Dockerfile, Git repository, or image layer is already exposed to the wrong people. Treat it as compromised and rotate it.
Use AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or a controlled Kubernetes secret workflow. Mount secrets as files where your platform supports it.
Read configuration without logging it
For example, set DATABASE_URL_FILE=/var/run/secrets/app/database_url in the runtime configuration. Your Go process reads that file at startup and validates that it is present.
Do not log connection strings, bearer tokens, cookie values, request bodies, or full configuration structs. Log that the configuration loaded, the secret name or revision when safe, and the deployment version.
Keep development defaults outside production. A production service should fail at startup if a required secret is missing.
Run with the least access possible
The container example uses the non-root Distroless account. Keep that setting in production.
For a Kubernetes workload, set runAsNonRoot: true, disable privilege escalation, drop Linux capabilities, and use a read-only root filesystem. Mount a writable temporary directory only if the application needs one.
Expose one application port. Don’t install shells, package managers, compilers, or diagnostic tools in the final image. They increase the attack surface and create more patch work.
Choose the right deployment target
Your first production target should match the service, not a trend. A small stateless HTTP API has different needs than a multi-service platform with private networking and long-running workers.
| Deployment option | Best fit | Operating trade-off |
|---|---|---|
| Cloud Run or Azure Container Apps | Stateless HTTP APIs | Less infrastructure control |
| ECS on Fargate or AWS App Runner | AWS-focused container services | AWS-specific operations |
| GKE, EKS, or AKS | Multiple services and advanced traffic control | More cluster administration |
| A hardened VM with systemd | Small, stable workloads | You own patching and scaling |
Deploy to a managed container service
Managed services work well when your Go application is stateless. Store files in object storage, use managed databases, and keep session state outside the container.
Set a concurrency limit that matches your database pool and memory profile. An application that accepts 100 concurrent requests can still fail if its database pool only allows 10 connections.
Pass the immutable image digest to the platform. Avoid releasing :latest or a branch name.
Deploy to Kubernetes when you need its controls
Kubernetes gives you rollout history, namespaces, ingress controls, autoscaling, and workload policies. It also adds more settings to maintain.
Set a readiness probe for /readyz. Set a liveness probe for /healthz. Add CPU and memory requests before you add autoscaling.
Deploy a tested release with:
kubectl set image deployment/<APP_NAME> <CONTAINER_NAME>=<REGISTRY>/<APP_NAME>@sha256:<IMAGE_DIGEST> -n <NAMESPACE>
Use separate service accounts for CI, deployment, and the running application. The runtime identity should not have permission to modify deployments or read unrelated secrets.
Verify the rollout before you call it complete
A successful image push is not a successful deployment. Check the service after it receives real traffic.
Test the release in a controlled batch
Start with one instance, a canary percentage, or a small internal audience. Check readiness, error rate, p95 latency, database connection count, and log errors.
Log structured events to stdout. Include fields such as level, msg, request_id, method, path, status, duration_ms, release, and trace_id when available.
Count accepted checks, not completed pipeline steps. A deployment that passes CI but creates customer errors has failed its operating test.
Use bounded retries for temporary network errors. Do not retry failed authentication, invalid configuration, or broken database migrations without review. Those failures need an owner and a recorded decision.
Keep rollback simple
Keep the prior production digest available. If error rates or readiness failures cross your release limit, return to that digest.
For a Kubernetes Deployment, use kubectl rollout undo deployment/<APP_NAME> -n <NAMESPACE> when the previous rollout is known-good. Then preserve logs, metrics, image digest, configuration revision, and the exact rollback time.
Name the person who can approve a rollback. State where the release record lives. Record how the team identifies the last trusted version before an incident occurs.
Final Thoughts
To deploy Go application services safely, make the release artifact fixed, the runtime restricted, and the recovery path tested. The binary is the easy part.
Health checks, graceful shutdowns, runtime secrets, structured logs, and an immutable rollback target turn a Go service into something your team can operate under pressure.
