DEV Community: Chiman Jain

🚀 Stop Chasing Small Docker Images: What Actually Matters for Go in Production

Chiman Jain — Wed, 06 May 2026 10:58:52 +0000

A practical guide to reproducible builds, faster CI pipelines, and debuggable containers for Go engineers

Most Docker + Go tutorials end the same way:

“Use multi-stage builds, switch to Alpine, done.”

That advice works until it doesn’t.

At scale, different problems show up:

CI pipelines slow down unpredictably
Builds stop being reproducible
Debugging minimal containers becomes painful
Monorepos destroy Docker cache efficiency

This article focuses on what actually matters in production:
👉 reproducibility, caching, and operability

🔍 How Docker + Go Builds Actually Work

Before optimizing, it helps to visualize what’s happening.

📊 Build Flow Diagram

        ┌───────────────┐
        │   Source Code │
        └──────┬────────┘
               │
               ▼
        ┌───────────────┐
        │  go.mod/sum   │
        └──────┬────────┘
               │
               ▼
        ┌──────────────────────┐
        │ go mod download      │
        │ (dependency layer)   │
        └──────┬───────────────┘
               │
               ▼
        ┌──────────────────────┐
        │ go build             │
        │ (compile layer)      │
        └──────┬───────────────┘
               │
               ▼
        ┌──────────────────────┐
        │ Final Image          │
        │ (distroless/scratch) │
        └──────────────────────┘

⚠️ Key Insight:

If go.mod changes → everything below it rebuilds

🧠 Reproducible Builds: The Overlooked Problem

❌ What Goes Wrong

Same code, different builds:

Different architectures (amd64 vs arm64)
Embedded file paths
Environment-dependent outputs

✅ Fixing It

1. Remove Local Paths

go build -trimpath -o app

2. Lock Dependencies

go mod download

Optional stricter control:

GOPROXY=https://proxy.golang.org
GONOSUMDB=*

3. Standardize Build Environment

FROM golang:1.26 AS builder

ENV CGO_ENABLED=0

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -trimpath -ldflags="-s -w" -o app

📊 Multi-Arch Build Flow

           ┌──────────────┐
           │   Source     │
           └──────┬───────┘
                  │
     ┌────────────┴────────────┐
     ▼                         ▼
┌──────────────┐        ┌──────────────┐
│ linux/amd64  │        │ linux/arm64  │
└──────┬───────┘        └──────┬───────┘
       ▼                       ▼
   Binary A               Binary B
 (different hash)      (different hash)

👉 Focus on behavior consistency, not identical binaries.

⚡ Docker Caching: Why Monorepos Break It

📊 Layer Caching Model

Layer 1: OS Base Image
Layer 2: go.mod / go.sum
Layer 3: Dependencies (go mod download)
Layer 4: Source Code
Layer 5: Build Output

❌ Problem

Change in go.mod
        ↓
Layer 2 invalidated
        ↓
Layer 3 re-runs (slow)
        ↓
Everything rebuilds

✅ Optimized Caching Strategy

📊 Improved Flow

        ┌──────────────┐
        │ go.mod/sum   │
        └──────┬───────┘
               ▼
   (cached via BuildKit mount)
        ▼
   Dependencies reused ✅

        ┌──────────────┐
        │ Source Code  │
        └──────┬───────┘
               ▼
        Build runs faster ⚡

🔧 Practical Fixes

Use BuildKit Cache

RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

Cache Build Artifacts

RUN --mount=type=cache,target=/root/.cache/go-build \
    go build -trimpath -ldflags="-s -w" -o app

Scope Dependencies

COPY services/service-a/go.mod services/service-a/go.sum ./
RUN go mod download

🐳 Minimal Images: The Trade-Off Nobody Talks About

📊 Image Comparison

scratch      → smallest → hardest to debug ❌
distroless   → balanced → production-ready ✅
alpine       → larger   → easiest debugging 🔧

🚨 Real-World Issues

scratch

No TLS certs → HTTPS fails
No shell → cannot debug
No timezone/DNS tools

distroless

Secure and minimal
But still no shell

alpine

Debuggable
But uses musl libc (can cause subtle issues)

✅ Practical Strategy

Production   → distroless
Debug build  → alpine
Special case → scratch

🧪 CI/CD Optimized Dockerfile

🚀 Production-Ready Template

FROM golang:1.26 AS builder

WORKDIR /app

ENV CGO_ENABLED=0

COPY go.mod go.sum ./

RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

COPY . .

RUN --mount=type=cache,target=/root/.cache/go-build \
    go build \
    -trimpath \
    -ldflags="-s -w" \
    -o app

FROM gcr.io/distroless/base-debian12

WORKDIR /

COPY --from=builder /app/app /app

USER nonroot:nonroot

ENTRYPOINT ["/app"]

🔧 Debug Variant

FROM alpine:3.19

RUN apk add --no-cache ca-certificates

COPY --from=builder /app/app /app

ENTRYPOINT ["/app"]

🧩 The Bigger Picture

Most engineers optimize for:

Image size
Build completion

But production systems care about:

Reproducibility  → Can I trust this build?
Debuggability    → Can I fix issues fast?
Performance      → Can CI scale?

🎯 Final Takeaway

If your Docker setup feels:

slow
fragile
hard to debug

…it’s not Docker.

It’s how:

caching
dependencies
and runtime assumptions

interact.

Stop Fighting Annotations: Why Kubernetes Gateway API is Replacing Ingress

Chiman Jain — Sun, 03 May 2026 13:57:17 +0000

If you’ve spent the last few years deploying applications to Kubernetes, you’re intimately familiar with the Ingress resource. It’s the trusty workhorse that gets HTTP traffic from the outside world into your cluster.

But let’s be honest: you’ve also felt the pain.

You want to do something seemingly simple, like split traffic for a canary release, rewrite a header, or do regex path matching. Suddenly, your clean YAML file is overflowing with a massive, unreadable block of controller-specific annotations.

“Wait, was the annotation nginx.ingress.kubernetes.io/rewrite-target or ingress.kubernetes.io/rewrite-target?”

Enter the Kubernetes Gateway API. It’s not just a new tool; it’s a fundamental rethinking of how routing works in a cloud-native world. Let's break down the difference between the legacy Ingress API and the new Gateway APIand why you should start migrating your mindset.

The Legacy Workhorse: Kubernetes Ingress

Introduced way back in Kubernetes v1.1, the Ingress API was designed with a simple goal: provide a unified way to configure HTTP(S) routing to services.

What it does well:

Basic fan-out routing (e.g., /api goes here, /web goes there).
Name-based virtual hosting (e.g., app.example.com).
Basic TLS termination.

Where it falls apart:

It's only for HTTP(S). Need to route TCP/UDP traffic? You're out of luck with standard Ingress. You have to hack it via load balancers or custom controller configs.
The "Annotation Hell". Because the Ingress API spec is so basic, it lacks native fields for advanced routing (retries, header manipulation, traffic splitting). To fill the gap, Ingress controllers (like NGINX, HAProxy, or Traefik) started using custom annotations. Your routing logic became coupled to the specific proxy implementation you were using.
Single Persona Design. In a real organization, an Infrastructure team manages the load balancer, but App Developers manage the application routes. The Ingress object forces everyone to collaborate on a single YAML file, which often leads to stepped-on toes and accidental outages.

The Evolution: Kubernetes Gateway API

The Gateway API (formerly known as Service APIs) is the official evolution of Ingress. After several years in development, the core Gateway APIs reached General Availability (v1.0) in late 2023, making it fully production-ready for standard Kubernetes clusters (typically v1.24+). Because it is delivered as a set of Custom Resource Definitions (CRDs) rather than being baked directly into the Kubernetes core API, you can install it on your cluster right now.

It was designed from the ground up to be expressive, extensible, andmost importantly*role-oriented*.

Here is why it changes the game:

1. Role-Oriented Design

Instead of a single monolithic Ingress object, the Gateway API splits the configuration into three separate resources, aligning perfectly with organizational roles:

GatewayClass (Infrastructure Provider): Defines the underlying load balancer technology (e.g., AWS ALB, GCP Load Balancer, Envoy). Managed by the cloud provider or platform team.
Gateway (Cluster Operator): Instantiates the load balancer and defines listening ports, TLS certificates, and which namespaces are allowed to attach routes to it. Managed by the cluster admins.
HTTPRoute / TCPRoute (App Developer): Defines the actual routing logic (paths, headers, traffic splitting). App developers own this and can attach it to the Gateway without asking the platform team for permission.

This separation of concerns is a massive win for security and self-service capabilities.

2. Goodbye Annotations, Hello Native Expressiveness

Remember all those wild NGINX annotations? The Gateway API bakes advanced routing directly into the API specification.

With HTTPRoute, you can natively configure:

Traffic Splitting (Canary/A-B Testing): Send 90% of traffic to v1 and 10% to v2.
Header Modification: Add, remove, or modify request/response headers.
Advanced Matching: Route based on query parameters or specific HTTP methods.
Cross-Namespace Routing: A Gateway in the infra namespace can securely route traffic to a service in the billing namespace.

All of this is done with strongly typed YAML fields, not brittle annotations.

3. Beyond HTTP and the gRPC Revolution

The Gateway API isn't just for standard L7 HTTP traffic. It natively supports TCPRoute, UDPRoute, TLSRoute, and notably, GRPCRoute.

If you've ever tried to route gRPC traffic through a standard Ingress, you know the struggle: hacking together annotations to force HTTP/2, watching streaming connections drop unexpectedly, and failing to cleanly route traffic to different backend pods based on the specific gRPC method being called.

With the native GRPCRoute, the Gateway API understands gRPC semantics out of the box. You can now reliably route traffic based on specific gRPC services or method names, perform precise traffic splitting for gRPC streams (perfect for canary testing a new microservice), and maintain stable connections without the annotation duct tape. You finally have a unified API to manage all traffic entering your cluster, regardless of the protocol.

So, is Ingress Dead?

Not quite yet. The Ingress API (specifically networking.k8s.io/v1) is stable and isn't being deprecated tomorrow. Millions of clusters rely on it, and it will be supported for a long time.

However, Ingress is feature-frozen. The Kubernetes community has made it clear that all future routing innovations, enhancements, and advanced features will be built exclusively into the Gateway API.

The Verdict

If you are running a simple blog with one container, standard Ingress is still fine.

But if you are building a modern, multi-tenant platform, struggling with complex traffic routing, or tired of vendor lock-in caused by proprietary annotations, the Gateway API is the answer. It’s standardized, it’s secure, and it respects the boundaries between your infra team and your developers.

It’s time to stop hacking your Ingress and start building with Gateways.

🚀 REST vs gRPC Performance in Go: A Practical Benchmark-Driven Guide

Chiman Jain — Fri, 24 Apr 2026 14:00:23 +0000

When building high-performance microservices in Go, one question inevitably comes up:

Should you use REST or gRPC?

This isn’t just an architectural debate it directly impacts latency, throughput, infrastructure cost, and scalability. In this post, we’ll break down REST vs gRPC performance using real benchmarks, practical Go examples, and production insights.

🧠 Understanding the Core Difference

Before diving into benchmarks, it’s important to understand why performance differs.

REST

Uses HTTP/1.1 (typically)
Data format: JSON (text-based)
Stateless, resource-oriented

gRPC

Uses HTTP/2
Data format: Protocol Buffers (binary)
Supports streaming (bi-directional)

Why This Matters

Binary serialization is more compact and faster to parse
HTTP/2 enables multiplexing multiple requests over a single connection
Reduced payload size = faster network transfer

⚙️ Benchmark Setup (Go)

Reference repository:

👉 https://github.com/chimanjain/go-rest-grpc-bencmark

This project benchmarks:

REST API (JSON over HTTP)
gRPC API (Protobuf over HTTP/2)

Typical Test Conditions

Concurrent clients
Small to medium payload sizes
High request volume
Controlled environment for fair comparison

📊 Benchmark Results (What Actually Happens)

Across benchmarks (including the referenced repo), a few consistent patterns emerge.

🔥 Key Observations

gRPC shows:
- Lower latency
- Higher throughput
- Better CPU efficiency
REST:
- Performs well at low scale
- Degrades faster under heavy load due to parsing and connection overhead

🧾 Why gRPC Is Faster

Factor	REST	gRPC
Serialization	JSON (text)	Protobuf (binary)
Transport	HTTP/1.1	HTTP/2
Payload Size	Larger	Smaller
Parsing Cost	Higher	Lower
Streaming	Limited	Native

🧪 Sample Go Implementations

🌐 REST Example (net/http)

package main

import (
    "encoding/json"
    "net/http"
)

type User struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

func getUser(w http.ResponseWriter, r *http.Request) {
    user := User{ID: "1", Name: "John"}

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
}

⚡ gRPC Example

package main

import (
    "context"
    pb "example/proto"
)

type server struct {
    pb.UnimplementedUserServiceServer
}

func (s *server) GetUser(ctx context.Context, req *pb.UserRequest) (*pb.UserResponse, error) {
    return &pb.UserResponse{
        Id:   "1",
        Name: "John",
    }, nil
}

⚖️ Key Difference

REST: manual serialization using encoding/json
gRPC: strongly typed, auto-generated code via .proto files

📈 Performance Deep Dive

1. Latency

gRPC typically achieves lower p99 latency
Especially noticeable with:
- High concurrency
- Small payloads

Reason: smaller payloads + faster serialization

2. Throughput

gRPC supports more requests per second
HTTP/2 multiplexing reduces connection overhead

3. CPU Usage

JSON parsing is CPU-intensive
Protobuf significantly reduces CPU overhead

4. Network Efficiency

Protobuf messages are smaller than JSON
Less bandwidth usage leads to faster transfers

🤔 When REST Performs Just Fine

Despite the performance gap, REST is still a solid choice in many scenarios:

Low to moderate traffic
Large payloads (compression reduces differences)
Public APIs and browser-based clients
Faster development and easier debugging

In many real-world systems, the performance difference is not critical.

🧩 Real-World Tradeoffs

Choose gRPC when:

Internal microservices communication
High-throughput or low-latency systems
Real-time streaming (e.g., chat, telemetry)
Strong contract enforcement is needed

Choose REST when:

Building public-facing APIs
Browser compatibility is required
Simplicity and ecosystem support matter

Common Industry Pattern

Use gRPC internally and REST externally

This gives you performance where it matters and compatibility where it’s needed.

🧠 Key Takeaways

gRPC is faster by design due to:
- HTTP/2
- Protobuf serialization
- Efficient connection handling
REST is:
- Simpler
- More widely supported
- “Fast enough” for many applications

🏁 Final Thoughts

Performance decisions should always be context-driven.

Building high-scale backend systems? → gRPC
Building public APIs? → REST

The best architecture often combines both.

🔗 References

💬 If you’ve run your own benchmarks in Go, feel free to share your results!

Dynamic Configuration Reloading in Go Apps on Kubernetes

Chiman Jain — Fri, 24 Apr 2026 11:55:19 +0000

In modern cloud-native environments, especially those leveraging Kubernetes, configuration management becomes a critical part of maintaining scalable, resilient applications. Kubernetes provides several ways to handle configurations, but knowing how to reload configurations dynamically without causing downtime can be tricky. As developers, we need to ensure that configuration updates are handled seamlessly without disrupting user experience or application stability.

In this post, I’ll dive into three key concepts: ConfigMaps vs Secrets, File Watchers vs API Polling, and Zero-Downtime Configuration Reloading Patterns, with a focus on how these work in Go applications on Kubernetes.

ConfigMaps vs Secrets: What’s the Difference?

Before we dive into dynamic reloading, let's quickly clarify Kubernetes' two main configuration management resources: ConfigMaps and Secrets.

ConfigMaps

ConfigMaps are used to store non-sensitive configuration data in Kubernetes. They’re ideal for settings like feature toggles, app settings, and environment variables that do not need encryption. ConfigMaps are mounted into pods either as environment variables or files, and can be updated without restarting the pod.

Secrets

Secrets, as the name suggests, are used to store sensitive data like passwords, API keys, and certificates. They are encoded (base64) for storage, though they are not fully encrypted by default. Secrets can be mounted into a pod as environment variables or files, just like ConfigMaps.

While ConfigMaps are suitable for general application configuration, Secrets should be reserved for anything confidential. Both can be dynamically reloaded, but Secrets often have additional security considerations around access control.

File Watchers vs API Polling: The Reload Dilemma

Now that we’ve covered how to store configurations, let’s talk about how to dynamically reload these configurations without restarting your app. Two common patterns are File Watchers and API Polling.

File Watchers

File watchers are a very common and efficient method for detecting configuration changes. When a ConfigMap or Secret is updated in Kubernetes, it can be automatically mounted as a file inside your pod. Go provides a rich ecosystem of libraries for watching file changes, such as fsnotify.

A file watcher listens for changes to the configuration files inside the container. Once a change is detected, the application can reload the configuration without the need for a restart. This method is often fast and efficient because it doesn't require polling or regular API calls.

Pros:

Real-time detection of changes.
Efficient and resource-friendly.
Suitable for configuration changes that are mounted as files in the pod.

Cons:

Complexity increases if you need to watch multiple files or complex directories.
It can be more challenging to scale if your app has many microservices or pods with different configuration requirements.

API Polling

API polling involves periodically querying Kubernetes' API server to check if there are any changes to your ConfigMap or Secret. This approach can be implemented using Kubernetes’ REST API to fetch the updated configurations.

While this method can work, it is generally less efficient than file watchers because it involves making HTTP requests at regular intervals, which can put unnecessary load on the Kubernetes API server.

Pros:

Works well for distributed systems where files aren’t directly available or accessible.
Simple to implement if the configuration is relatively small or doesn’t change frequently.

Cons:

Polling intervals introduce latency and additional overhead.
More resource-intensive, especially in larger applications with multiple polling intervals.

Zero-Downtime Config Reload Patterns

One of the key goals of dynamic configuration reloading is to ensure that your app can adapt to configuration changes without downtime. Whether you are using file watchers or API polling, the way your application reloads the configuration matters.

Here are some common patterns to achieve zero-downtime configuration reloads:

1. Graceful Restart with Rolling Updates

Kubernetes' Rolling Updates feature allows you to replace pods with minimal downtime. When a configuration change is detected, Kubernetes can create new pods with the updated configuration and slowly replace the old pods. This ensures that there’s no downtime for the application as the new configuration is applied.

In Go, you can combine this with graceful shutdown techniques. For example, you can use a signal handler to catch termination signals and allow the application to finish in-progress requests before shutting down. This ensures that while pods are being replaced, your app remains functional throughout the update process.

2. In-Memory Configuration with Hot Swapping

For some applications, you might want to handle configuration changes completely in-memory, without reloading files or restarting pods. In Go, this can be achieved by implementing an in-memory configuration store that can be updated dynamically.

You can listen for file changes or poll an API to update the in-memory store. When the configuration changes, the new values are swapped in without restarting the application. This technique is commonly used in apps that need to handle high availability, like microservices that provide low-latency responses.

Example:

You could implement a simple configuration manager using Go’s sync.RWMutex to safely update and read configurations in-memory.

3. Blue-Green Deployment

Another common approach to achieve zero-downtime updates is Blue-Green Deployment. In this pattern, you run two identical environments (Blue and Green). When a new configuration is ready, it is deployed to the inactive environment (e.g., Blue). Once the update is complete, you switch the traffic to the new environment, making it active while the old environment becomes idle. This eliminates downtime since there’s always one environment serving requests.

For Go apps in Kubernetes, this could mean deploying the updated pods with the new configuration to a separate environment, testing it, and then routing traffic to the new pods once everything is validated.

Conclusion

Dynamic configuration reloading in Kubernetes is essential for modern, resilient applications. Whether you're managing non-sensitive data with ConfigMaps, securing your credentials with Secrets, or deciding between file watchers and API polling for configuration updates, the goal is the same: minimize downtime and make the app as responsive as possible.

By implementing patterns like graceful restarts, in-memory configuration swapping, and blue-green deployments, you can ensure that your Go apps on Kubernetes remain highly available, even when configurations change dynamically.

Things I Regret After Writing Go for 8 Years

Chiman Jain — Fri, 24 Apr 2026 11:34:41 +0000

I’ve been writing Go for over 8 years now, and like many developers, I started with high hopes, clean code, and a naive understanding of what it takes to build scalable, maintainable systems. Over the years, I’ve written more Go code than I’d care to admit, and like many seasoned developers, I’ve accumulated a list of regrets. These aren’t just about syntax or Go-specific quirks; they’re about the decisions I made, the assumptions I held, and the trade-offs I didn’t fully appreciate.

So, if you’re just starting out with Go or you’re thinking about using it for your next big project, here are some of the mistakes, lessons, and regrets I’ve learned the hard way.

1. Overusing Interfaces

The Mistake

When I first started with Go, I was enamored with interfaces. Go's interface system felt like magic it was so simple, powerful, and decoupled. I thought that every single component should be abstracted behind an interface for maximum flexibility.

The Reality

While Go’s interfaces are indeed powerful, overusing them created more problems than it solved. What I didn’t realize was that too many interfaces made the codebase harder to reason about. Too often, I found myself navigating through layers of abstraction to understand what a component actually did. The flexibility interfaces offer often led to more complexity, not less.

The Lesson

Only use interfaces when they add real value. Prefer concrete types and composition where possible. Simple code is easier to understand, maintain, and refactor than code full of unnecessary interfaces.

2. Ignoring Context Propagation

The Mistake

Early on, I wasn’t fully aware of how crucial context propagation is in Go, especially in long-running services. I often neglected to pass the context.Context to functions that required it, which led to hard-to-debug issues later on.

The Reality

As my applications grew, I realized that not using context correctly can lead to messy cancellation logic, ungraceful shutdowns, and worst of all, unpredictable behavior. Context is meant to handle things like timeouts, cancellation signals, and request-scoped data. When I ignored it, I missed out on traceability and correct request lifecycle management.

The Lesson

Make it a habit to always pass context in request-handling functions and background tasks. It’ll save you headaches down the road when it comes to cancellation, deadlines, and ensuring your application handles requests gracefully.

3. Relying Too Much on Goroutines for Concurrency

The Mistake

In the early days, I treated Go’s goroutines as the solution to all concurrency problems. My solution to any performance bottleneck was to spawn more goroutines. Concurrency? Just throw more goroutines at it.

The Reality

Goroutines are cheap, but they’re not free. Goroutine leaks and contention between goroutines can severely degrade performance, especially if you’re not managing them properly. I learned the hard way that goroutines, if not handled carefully, can lead to memory bloat and race conditions.

The Lesson

Use worker pools and bounded concurrency patterns rather than spawning goroutines indiscriminately. Don’t assume that more goroutines will always equal better performance measure and profile before scaling your concurrency model.

4. Not Paying Enough Attention to Garbage Collection

The Mistake

Go’s garbage collector is known for being efficient, so I assumed I could ignore it in the early stages of development. I didn’t pay much attention to memory allocations or the impact of GC pauses on latency.

The Reality

As my application scaled, GC pauses started becoming a noticeable bottleneck. Even though Go’s garbage collector is one of the best, when you’re dealing with high-throughput services, even a small pause can cause latency spikes that affect the user experience.

The Lesson

Profile your application’s memory usage and understand how Garbage Collection works. Use tools like pprof and runtime/trace to monitor allocation rates and GC pauses. And whenever possible, minimize allocations in hot paths to reduce GC pressure.

5. Underestimating the Power of Tests

The Mistake

I used to think that unit tests were the most important thing, and everything else was secondary. This made me ignore integration and end-to-end tests, which I now know are just as crucial, if not more so, in production-grade systems.

The Reality

Unit tests are great, but they don’t tell the full story. While unit tests validate individual components, they don’t help much when you're dealing with distributed systems, real-world failures, and the complexity of interacting services. In my case, skipping integration tests led to some hard-to-debug issues in production.

The Lesson

Adopt a test pyramid: focus on writing high-quality integration and end-to-end tests, alongside unit tests. Simulate failure scenarios, and don't just test the happy path. Mocks and stubs are useful, but they can’t replace the value of testing the actual integrations.

6. Over-Optimizing Too Soon

The Mistake

I often jumped into optimizing before fully understanding the problem. I would focus on low-level micro-optimizations (like caching, network call optimizations, etc.) before understanding whether the optimization was even necessary.

The Reality

More often than not, my premature optimizations created complexity that didn’t yield any meaningful performance improvements. In some cases, it actually slowed things down by introducing extra dependencies or introducing bugs.

The Lesson

Measure first, optimize later. Focus on clean, simple solutions first. Use profiling tools to identify bottlenecks before diving into optimizations. And always ask yourself: “Is this optimization really solving a problem, or is it a premature attempt at perfection?”

Conclusion: Growing with Go

In the end, Go is a fantastic language that rewards simplicity and clarity. But just like any language, it’s easy to make mistakes if you don’t fully understand the trade-offs and long-term consequences of your design decisions. These regrets are part of the growth process. Every mistake taught me something valuable about writing scalable, maintainable Go code.

So if you’re just starting out with Go, take it slow, plan for the long term, and don’t rush into decisions without considering how they’ll impact your system’s future. And most importantly, learn from the mistakes of others it’ll save you time, headaches, and, ultimately, lead to better code.

Here’s to the next 8 years of Go!

Designing Go APIs That Don’t Age Badly

Chiman Jain — Fri, 24 Apr 2026 11:20:56 +0000

When building APIs in Go, it’s easy to get caught up in the rush to ship. You create an elegant endpoint, document it, and call it a day. But as your service evolves and your user base grows, what once seemed like a simple, clean API can quickly turn into a maintenance nightmare. If you don’t consider the long-term design of your Go APIs, you may find yourself with an API that becomes difficult to maintain, fragile, and hard to scale.

In this post, we’ll cover some essential strategies for designing Go APIs that can stand the test of time. These include versioning, avoiding breaking changes, and mindful interface design.

The Problem with API Design in Go

Go encourages simplicity and directness, but when it comes to managing evolving APIs, the language itself doesn’t impose conventions for API stability. The challenge for Go developers is to strike a balance between flexibility and longevity.

A bad decision made early on in API design can result in breaking changes that ripple through your application, potentially causing months of work for your team and frustration for consumers. But with careful planning and foresight, you can design APIs that are robust, adaptable, and flexible without introducing future headaches.

1. Versioning Your Go APIs Don’t Ignore It

When building an API, versioning should be a core consideration from day one. Even if you don’t plan to make major changes now, assume that you will need to, and plan accordingly.

Why Versioning Matters

Maintaining backward compatibility: Versioning allows you to introduce changes to your API while ensuring that existing clients can continue to work without disruption.
Controlled deprecation: You can signal to consumers which features or endpoints are deprecated and provide a migration path.
Separation of concerns: It allows your codebase to evolve while clearly distinguishing between stable and experimental functionality.

Versioning Strategies

URI Versioning (e.g., /v1/resource or /v2/resource):
- Pros: Simple to implement and understand. It’s immediately obvious which version of the API a client is calling.
- Cons: If not managed carefully, it can lead to API version bloat, where you have to maintain multiple versions for a long time.
- Best for: Major version changes, or when you need to make breaking changes that require a new major version of the API.
Header-based Versioning (e.g., X-API-Version):
- Pros: Cleaner URLs, and you can keep versioning entirely out of the URL path.
- Cons: Requires consumers to be aware of and set the correct headers. Not as intuitive as URI versioning.
- Best for: Small, non-breaking changes that do not require creating an entirely new version of the API.
Semantic Versioning (e.g., v1.0.0, v1.1.0):
- Pros: You can convey the type of changes made (major, minor, patch) through version numbers. Very clear for both developers and consumers.
- Cons: Slightly more complex than simple URI-based versioning.
- Best for: APIs that evolve over time and need to clearly communicate how changes affect consumers.

Versioning Tip

Start versioning early. Even if your API doesn’t seem to need versioning now, create a versioning scheme from the beginning. It’s easier to version early than to retroactively patch an unversioned API.

2. Avoiding Breaking Changes A Delicate Balance

In Go, backward compatibility is crucial, but sometimes breaking changes are inevitable as your API evolves. The goal is to minimize these changes, especially for clients relying on your service.

Common API Changes That Cause Breakage

Removing or renaming fields: Clients may rely on specific fields being present, even if they aren’t always used.
Changing return types: A seemingly small type change can break client code that relies on the original type.
Changing HTTP methods: A switch from POST to PUT, or modifying an endpoint’s expected behavior, can cause unexpected failures.
Introducing new required fields: If your API starts requiring new fields that weren’t previously required, existing clients may break.

Best Practices to Avoid Breaking Changes

Deprecate, Don’t Delete

Rather than removing or renaming an endpoint, deprecate it and introduce a new one. Provide clear documentation about the deprecation, give consumers plenty of time to migrate, and offer new functionality alongside old functionality.
Use Optional Fields

When adding new fields, make them optional and only introduce required fields in new versions of the API. This ensures existing consumers won’t be broken by your changes.
Don’t Change Existing Behaviors

If you change how an endpoint behaves, try to do so in a way that’s backward compatible. For example, you could add an optional query parameter to change the behavior, rather than altering the behavior entirely.
Graceful Error Handling

When an API change occurs, ensure that you handle errors gracefully. Provide clear, actionable error messages that guide users toward the changes they need to make in their client applications.

3. Interface Design Pitfalls Avoiding Tomorrow’s Headaches

In Go, interfaces are incredibly powerful, but they come with a lot of room for misuse. Designing APIs with poorly thought-out interfaces can lead to rigid, fragile systems that break easily when your application evolves.

Common Pitfalls in Interface Design

Overuse of Interfaces

Go interfaces are great, but they shouldn’t be overused. Often, developers fall into the trap of defining interfaces for every little component in their code. This can lead to unnecessary complexity and makes it harder to refactor in the future.
Inconsistent Method Sets

An interface should have a well-defined, coherent set of methods. If you change the method set too frequently or make the methods too vague, you’ll find it difficult to maintain consistency across your codebase.
Interface Pollution

Avoid creating interfaces that are too general and try to do too much. Each interface should have a clear, focused responsibility.
Breaking Changes in Interfaces

Removing or changing methods in an interface is a breaking change. Instead, prefer adding methods and allowing optional extensions in your interfaces.

Best Practices for Interface Design

Design Interfaces for Use, Not for Flexibility

Focus on designing interfaces that actually solve problems for users of your API. Don’t make interfaces more general than they need to be just to add flexibility.
Make Interfaces Small and Focused

Keep interfaces small and focused on one responsibility. The more focused the interface, the easier it is to maintain and evolve without breaking things.
Prefer Composition Over Inheritance

Use struct embedding (composition) rather than inheritance (interface embedding) to compose behavior across different types. This avoids complex hierarchies and allows for better flexibility in adding new functionality without breaking existing code.
Avoid Tight Coupling

Make sure your API is loosely coupled. This can be achieved by:
- Using dependency injection where necessary
- Avoiding direct dependencies on other packages in your interfaces
- Keeping interfaces simple and allowing different implementations

Final Thoughts: Future-Proofing Your Go API

API design isn’t just about making something that works today it’s about making something that will still be usable, maintainable, and extensible tomorrow. In Go, the key to future-proofing your APIs is thinking ahead versioning early, avoiding breaking changes, and being mindful of interface design. With these strategies, you’ll ensure that your Go APIs not only work in the present but can also adapt to changes as your application and team evolve.

If you’re planning a major API refactor or starting a new project, take the time to implement these principles early. By doing so, you’ll save yourself (and your team) from much greater pain later down the road.

Remember: Good design is not just about elegance today it’s about resilience over time.

Why Your Go Service Has Latency Spikes (Even If It’s “Fast”)

Chiman Jain — Fri, 24 Apr 2026 11:06:16 +0000

You shipped a Go service. Benchmarks look great. CPU usage is low. Average latency is comfortably within targets.

And yet every now and then your p99 explodes.

This is the part many engineers underestimate: fast systems can still be unpredictable systems. In Go, latency spikes are rarely caused by a single obvious bottleneck. They emerge from the interaction between the runtime, the OS, and your code under real-world load.

Let’s dig into the less obvious reasons your Go service spikes and what you can actually do about them.

The Illusion of “Fast Enough”

Go makes it easy to build services that are consistently good on average. Goroutines are cheap, the standard library is efficient, and deployment is simple.

But averages lie.

Latency-sensitive systems live and die by tail latency p95, p99, p999. These outliers are where user experience breaks down, SLAs fail, and debugging becomes painful.

If your service is “fast but spiky,” you’re likely dealing with one (or more) of the following.

1. Garbage Collection Isn’t Free (Even When It’s Good)

Go’s garbage collector is excellent, but it is not invisible.

What’s happening

Modern Go uses a concurrent, tri-color mark-and-sweep GC. Most of the work happens alongside your application, but there are still stop-the-world (STW) phases especially during:

Stack scanning
Mark termination

Even if these pauses are short (microseconds to milliseconds), they can stack up under load and show up as latency spikes.

Why it gets worse in production

High allocation rates increase GC frequency
Large heaps increase scan time
Pointer-heavy data structures slow marking

What to look for

Sudden spikes aligned with GC cycles
Increased GOGC pressure
High allocation profiles in pprof

What actually helps

Reduce allocations in hot paths
Reuse objects (sync.Pool, carefully)
Avoid unnecessary pointers
Flatten data structures when possible

2. Goroutine Contention and Scheduler Behavior

Goroutines are cheap but not free, and definitely not magic.

What’s happening

Go’s scheduler multiplexes goroutines onto OS threads. Under load:

Run queues grow
Context switching increases
Work stealing adds overhead

If too many goroutines compete for CPU or locks, latency spikes emerge not from raw compute, but from waiting.

Common traps

Spawning unbounded goroutines per request
Blocking operations inside goroutines
Assuming “more concurrency = faster”

Subtle issue: cooperative preemption

Go relies partly on cooperative preemption. If a goroutine runs tight loops without safe points, it can delay scheduling fairness.

What to do

Use worker pools for bounded concurrency
Avoid long-running CPU loops without yielding
Profile scheduler latency (runtime/trace)

3. Lock Contention: The Silent Killer

Mutexes don’t show up in CPU profiles but they absolutely show up in latency.

What’s happening

Under contention:

Goroutines block on locks
Queueing delays increase
Throughput may remain high, but latency explodes

Where it hides

Global maps with mutex protection
Shared caches
Logging pipelines
Metrics collectors

Why it’s tricky

You might not notice until traffic scales. Everything works fine until it suddenly doesn’t.

What works

Reduce lock granularity
Prefer sharded structures
Use lock-free or atomic patterns where appropriate
Measure with mutex profiling (go test -mutexprofile)

4. Network and Syscall Variability

Your Go code might be fast. The network is not.

What’s happening

Every request eventually hits:

TCP stack
DNS resolution
Kernel scheduling
External services

Even tiny variations here can cascade into visible latency spikes.

Common culprits

DNS lookups without caching
Connection churn (lack of keep-alives)
Slow downstream dependencies
Kernel-level queueing

The hidden factor: tail amplification

If your service calls 5 downstream services, each with p99 latency of 50ms, your combined p99 is much worse.

What helps

Use connection pooling aggressively
Set timeouts everywhere (and mean it)
Cache DNS where possible
Budget latency across dependencies

5. GC + Scheduler + Syscalls: The Perfect Storm

The real problem is rarely one issue it’s interaction effects.

A typical spike might look like this:

GC cycle starts under high allocation pressure
Goroutines increase due to incoming traffic
Lock contention rises in shared structures
A few slow network calls block threads
Scheduler struggles to keep up

Individually, each is manageable. Together, they create a spike that’s hard to reproduce and harder to debug.

6. Misleading Benchmarks

Your local benchmarks probably didn’t show any of this.

Why?

No real network variability
No production traffic patterns
No contention
No long-lived heap growth

Benchmarks measure ideal conditions. Production exposes emergent behavior.

7. Observability Gaps

You can’t fix what you can’t see.

Most teams track:

Average latency
CPU usage
Memory usage

But miss:

GC pause distribution
Goroutine counts over time
Scheduler delays
Mutex contention
Per-endpoint tail latency

Without these, spikes remain mysterious.

What Actually Works in Practice

If you care about latency consistency, not just speed:

1. Profile under realistic load

Use:

pprof (CPU, heap, allocs, mutex)
runtime/trace for scheduler insights

2. Track the right metrics

p95/p99 latency (not averages)
GC pause time
Goroutine count
Queue lengths

3. Design for bounded behavior

Limit concurrency
Avoid unbounded queues
Apply backpressure

4. Reduce variability, not just cost

Stable systems beat “fast on average” systems
Predictability > peak performance

Final Thought

Go gives you the tools to build extremely fast systems. But it doesn’t guarantee consistent latency that part is on you.

If your service has latency spikes, don’t look for a single bug. Look for interactions under pressure.

Because in production, the question isn’t:

“Is my service fast?”

It’s:

“Is my service predictable when everything starts going wrong?”

DEV Community: Chiman Jain

🚀 Stop Chasing Small Docker Images: What Actually Matters for Go in Production

A practical guide to reproducible builds, faster CI pipelines, and debuggable containers for Go engineers

🔍 How Docker + Go Builds Actually Work

📊 Build Flow Diagram

⚠️ Key Insight:

🧠 Reproducible Builds: The Overlooked Problem

❌ What Goes Wrong

✅ Fixing It

1. Remove Local Paths

2. Lock Dependencies

3. Standardize Build Environment

📊 Multi-Arch Build Flow

⚡ Docker Caching: Why Monorepos Break It

📊 Layer Caching Model

❌ Problem

✅ Optimized Caching Strategy

📊 Improved Flow

🔧 Practical Fixes

Use BuildKit Cache

Cache Build Artifacts

Scope Dependencies

🐳 Minimal Images: The Trade-Off Nobody Talks About

📊 Image Comparison

🚨 Real-World Issues

scratch

distroless

alpine

✅ Practical Strategy

🧪 CI/CD Optimized Dockerfile

🚀 Production-Ready Template

🔧 Debug Variant

🧩 The Bigger Picture

🎯 Final Takeaway

Stop Fighting Annotations: Why Kubernetes Gateway API is Replacing Ingress

The Legacy Workhorse: Kubernetes Ingress

The Evolution: Kubernetes Gateway API

1. Role-Oriented Design

2. Goodbye Annotations, Hello Native Expressiveness

3. Beyond HTTP and the gRPC Revolution

So, is Ingress Dead?

The Verdict

Further Reading

🚀 REST vs gRPC Performance in Go: A Practical Benchmark-Driven Guide

🧠 Understanding the Core Difference

REST

gRPC

Why This Matters

⚙️ Benchmark Setup (Go)

Typical Test Conditions

📊 Benchmark Results (What Actually Happens)

🔥 Key Observations

🧾 Why gRPC Is Faster

🧪 Sample Go Implementations

🌐 REST Example (net/http)

⚡ gRPC Example

⚖️ Key Difference

📈 Performance Deep Dive

1. Latency

2. Throughput

3. CPU Usage

4. Network Efficiency

🤔 When REST Performs Just Fine

🧩 Real-World Tradeoffs

Choose gRPC when:

Choose REST when:

Common Industry Pattern

🧠 Key Takeaways

🏁 Final Thoughts

🔗 References

Dynamic Configuration Reloading in Go Apps on Kubernetes

ConfigMaps vs Secrets: What’s the Difference?

ConfigMaps

Secrets

File Watchers vs API Polling: The Reload Dilemma

File Watchers

API Polling

Zero-Downtime Config Reload Patterns

1. Graceful Restart with Rolling Updates

2. In-Memory Configuration with Hot Swapping