Case Study: How Daily Migration Logs Rescued a Kubernetes Move

Case Study: How Daily Migration Logs Rescued a Kubernetes Move

This is a fictional case study, built from patterns that come up repeatedly when engineering teams move workloads to Kubernetes. The company, the people and the numbers are invented for illustration. The lesson is real: on a long migration, a short daily migration log kept by each engineer did more to protect the schedule than any single tool choice. Below is how the team got there, what the logs contained, and how they changed the outcome.

Background: a migration that kept stalling

Northline Logistics, a mid-sized freight software firm, ran about forty services on virtual machines. Leadership approved a move to a managed Kubernetes platform, with a target of six months. A team of five platform engineers owned the work, supported by developers from each product squad.

By the end of month two, only six services had moved. A retrospective surfaced three problems, and none of them was technical in the usual sense:

  • Repeated discovery. Engineers kept hitting the same issues, such as a legacy service that read configuration from a local file path, and solving them independently.
  • Broken handovers. When an engineer moved between services or went on leave, the next person had to re-investigate what had already been tried.
  • Disputed facts. Discussions stalled on questions like “did we already test the connection pooling change?” because nobody could say for sure.

The team lead, Anjali, framed it bluntly: “We are not slow because Kubernetes is hard. We are slow because we keep forgetting what we learned.”

The intervention: one migration log per engineer

The team agreed to a lightweight experiment for four weeks. Each engineer would keep a personal migration log in a Markdown file in a shared repository. The rules were deliberately minimal:

  1. One dated entry per working day, written before logging off.
  2. Three headings per entry: tried, learned, next.
  3. Include failures and dead ends. They were considered the most valuable lines.
  4. No polishing and no review. The log belonged to its author.
  5. Anyone could read anyone else’s log, and search across them.

Notably, the team did not ask for procedures, templates or formal documentation. Those already existed and were not the bottleneck. The gap was the day-to-day reasoning that never made it into a commit message.

What the entries looked like

A typical entry from one engineer, Marco, read:

Tue 14 Apr. Tried: moving the rates service; readiness probe kept failing. Learned: the service takes about 90 seconds to warm its cache, probe timeout was 30. Raised initial delay; pod healthy. Next: check whether quotes and invoicing have the same warm-up pattern.

Two days later, a colleague migrating the invoicing service searched the logs for “readiness,” found Marco’s note and skipped what would otherwise have been an afternoon of debugging.

Results after four weeks

The team measured three things before and during the experiment, using their ticketing data and the logs themselves. Again, these figures are illustrative of the kind of change teams report, not data from a real company.

Throughput

In the four weeks before the logs, the team migrated three services. In the four weeks with logs, it migrated nine. Some of that gain came from growing familiarity with the platform, so the team was careful not to credit the logs with all of it. But in the retrospective, engineers could point to specific entries that had saved them time on at least five of those nine services.

Repeat investigations

Before the experiment, the team estimated that roughly one in three blocking issues had already been solved by someone else. During it, engineers searched the logs first, and that share fell sharply. The logs made prior knowledge findable at the moment it was needed.

Handover time

When one engineer went on two weeks’ leave mid-migration, her replacement read the last ten days of her log and resumed work on the same morning. Previously, similar handovers had cost two or three days of re-orientation.

Why it worked: an analysis

Looking back, the team identified four mechanisms.

Low cost of entry. Each entry took around five minutes. Because the format was personal and unreviewed, nobody felt they were writing documentation, which removed the usual resistance.

Capturing negative results. Commit histories record what worked. The logs recorded what did not, which is often what saves the next person the most time.

Searchability. Keeping all logs in one repository meant a single search across the team’s collective experience. This turned five individual memories into one shared one.

Context for decisions. When debates arose, the logs provided dated evidence of what had been tried and why. Arguments got shorter.

The broader skill mix the team needed, combining container platforms, cloud services and delivery practices, is discussed in this piece on bringing DevOps, cloud and Kubernetes skills together deliberately. The logs became the place where those skills were developed and recorded in practice.

What did not work

The experiment was not friction-free. Two engineers struggled to write daily and caught up in weekly batches, which produced thinner, less useful entries. One person tried an elaborate template with ten fields and abandoned it within a week. The team concluded that brevity and daily rhythm mattered more than structure.

They also learned to keep secrets out. An early entry included a database connection string, which was removed and rotated. A one-line rule went into the repository’s readme afterwards.

After the migration

Northline completed the move in a little over seven months, one month behind the original target but far ahead of the pace it had been on. The logs did not stop when the project ended. The team adopted declarative, Git-driven operations for the new platform, the approach outlined in this article on running platforms through GitOps for operational stability, and engineers kept writing daily entries alongside their pull requests. Several of the most common lessons were later promoted into team documentation, with links back to the original log entries for context.

Wider context

The practice is common in other technical communities too. AI Universe, a publication on machine learning and big data, features a Stories section of daily logs from practitioners, showing the same tried, learned, next rhythm the Northline team settled on.

Takeaways for your own team

  • On long projects, lost knowledge is a bigger drag than technical difficulty.
  • A personal, dated log with three headings is enough. Keep it short.
  • Record failures; they save the most time later.
  • Put all logs where they can be searched together.
  • Run it as a time-boxed experiment, measure what changes and decide on evidence.