DEV Community: George Michalakis

K8s: The Affinity Club

George Michalakis — Sun, 16 Aug 2026 10:26:02 +0000

Introduction

If you have fiddled with Kubernetes long enough to worry about which node your Pods are actually running on, you can probably relate.

First: what does affinity even mean?

Affinity: a strong feeling that you understand or like someone or something; a close relationship between people or things with similar qualities.

Okay. Fair enough.

In Kubernetes, affinity is a family of scheduling rules:

Node affinity defines hard requirements and soft preferences for which nodes can run a Pod.
Pod affinity lets us place a Pod near other Pods.
Pod anti-affinity lets us keep Pods away from other Pods.

So, loosely, if I were a Pod, I would say:

“I have an affinity for being near or away from these Pods.”

But why care?

At the end of the day, I can always scale to more replicas. I’m safe… right?

Let’s see it in action

Let’s take the worst-case scenario.

Imagine a cluster with two worker nodes. We have a critical service, but all of its Pods happen to be scheduled on worker-1.

Traffic grows, so we scale the Deployment. But every new replica still lands on worker-1.

After scaling, two things become obvious:

worker-1 is becoming stressed.
If worker-1 fails, every replica fails with it—and the application is down.

The scheduler is not random, but without a placement rule, it has no obligation* to spread our replicas across workers.

In this scenario, worker-2 is right there... empty..

Ok. Can we force Kubernetes to keep replicas of the same service on different workers?

Yes. That is exactly what pod anti-affinity is for.

Below, we apply pod anti-affinity to our critical service’s Deployment.

Before: no placement rule

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: drainlab
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          resources:
            requests:
              cpu: 250m
              memory: 128Mi
          ports:
            - containerPort: 80

After: hard pod anti-affinity

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: drainlab
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      affinity: # <-Magic starts to happen here
        podAntiAffinity: 
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: web
              topologyKey: kubernetes.io/hostname # <-finishes here
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          resources:
            requests:
              cpu: 250m
              memory: 128Mi
          ports:
            - containerPort: 80

This tells the scheduler:

requiredDuringScheduling “A new app: web Pod cannot be scheduled onto a node that already runs another matching app: web Pod.”

If every eligible worker already runs one, the new Pod stays Pending rather than placing two replicas on the same node.

More specifically:

requiredDuringScheduling: if no valid worker exists, the new Pod stays Pending.
IgnoredDuringExecution: Kubernetes does not evict an already-running Pod merely because later changes violate the anti-affinity condition.
topologyKey: kubernetes.io/hostname: each worker node is treated as a separate failure domain.

But wait… if I have two eligible worker nodes and need four replicas, do the other two remain Pending?

Before anti-affinity, all four Pods could run on worker-1, even though one node failure would take down the entire service.

Now, Kubernetes protects us from that false sense of safety but hard pod anti-affinity limits us to one matching Pod per worker.

So we gained failure isolation, but we gave up that easy scaling?

No, This is where topology spread constraints come in.

*Kubernetes may already prefer to spread Pods using soft scheduling preferences. Exact placement depends on available resources and scheduler configuration. This example demonstrates why relying on a preference is different from declaring a hard availability rule.

Labs / Visualizations for this article can be found here

Save yourself from Architectural Amnesia: ADRs

George Michalakis — Sat, 14 Mar 2026 02:03:07 +0000

When you see it...

From smaller teams to larger ones, from the senior SWE managing the entire backlog to EOs, POs, and SMs juggling overlapping responsibilities, I have often found myself in meetings or PR discussions nitpicking scope details and suddenly realizing one of two things:

I disagree with the broader implementation picture.
I do not even remember whether I agreed with it in the first place.

That second one is worse.

For context, I am working in a SAFe Scrum setup, so these roles and handoffs are a very real part of day-to-day delivery.

Half-measures (Best-case scenario)

"Uhh, there is a Confluence page about this decision. We had a meeting for that."

Clicks the link.

Scans a page with 10 comments (8 resolved, 2 still open).

OK, this makes a bit more sense now.

Still, I do not remember what we said. I do not remember how long it took, and it probably took longer than it should have.

Even in this best-case scenario, I am still left with two problems:

I do not remember the back-and-forth, and some of it was probably important.
If I now have a different opinion, I really do not want to reopen the topic. That usually means more meetings, more pages, and more comments. Atlassian may be doing a great job with version control, but I do not want to be stuck restoring version 23 of a Confluence page that nobody will care about two weeks later.

Give credit where it is due

That does not mean Confluence is useless.

Architects, PMs, and business stakeholders need version control, comments, and discussions too. You cannot expect a product owner:

To log in to GitHub every time they want to sync with the architect on whether the team is migrating the DB.
To align on the confidence level of PI objectives with different POs inside a pull request.

Confluence has its place.

But at the same time, nobody wants to spend all of this just to discuss something like a new or existing PR label:

10 minutes to raise it during the daily stand-up
5 minutes to schedule a call
20 minutes to prepare a page explaining the current state and the proposal
35 minutes for the meeting itself
20 minutes for the notes afterward
20 minutes updating the page with the latest comments and decisions

And yes, those numbers are completely realistic.

Architecture Decision Records

This is where ADRs help.

An ADR is a lightweight record of an important technical decision: why it was needed, what options were considered, what was chosen, and what tradeoffs came with that choice.

At its simplest, it is just a markdown file living in your repo, somewhere like this:

docs/
  adrs/
    0001-use-topic-a.md

That is basically it.

A small document, committed with the code, with sections such as:

Context: what problem are we trying to solve?
Decision: what did we choose?
Alternatives considered: what were the other realistic options?
Consequences: what do we gain, and what do we give up?
Status: proposed, accepted, superseded, deprecated

Nothing fancy. Just enough to preserve the reasoning behind a technical decision close to the codebase where engineers will actually look for it.

Basic rules

Keep ADRs for technical topics that are likely to be searched while someone is working in the repo. If you used a specific pattern, tool, or extension, I would much rather Ctrl+F the repo and find the reasoning in the docs than dig through a GitHub page or old meeting notes.
Make the person opening the PR the driver of the discussion. They should gather feedback, collect comments, help the team converge on a decision, and eventually merge or close the PR with the ADR alongside the change.
Do not optimize for unanimous agreement. Optimize for a clear decision with explicit tradeoffs and enough context that the next person can understand why it happened.

That is the real value: not perfect documentation, but recorded reasoning close to the codebase.

If you want a good collection of ADR templates, look here.

PS1: Use this as a starting point for introducing ADRs to your team.

PS2: An agent helped with syntax refactoring. The expressions, the main writing, the flow and the pain is mine :)