Migration advice fails in two familiar ways: it assumes a greenfield platform that nobody actually has, or it recommends moving everything at once, which is how weekends get ruined. The workable path is narrower. Pick one service of modest importance, give it a recorded and reconciled home, prove the loop for a fortnight, and only then widen the circle. This article lays out that path in eight steps, with the reasoning stated at each point so your team can adapt the sequence to its own platform rather than following a script blindly.
GitOps Migration: Choosing the Right First Service
Scope decisions deserve evidence, so score candidates before picking. A good first subject is stateless, internal, and mildly annoying to deploy — annoying enough that the improvement is visible, unimportant enough that a mistake costs an apology rather than revenue. Reject anything holding customer data for round one. Reject the service everybody’s bonus depends on. Write the choice down with the reasons; when a sceptic asks in three months why this service went first, the note answers for you.
The full route, compressed to one line per step:
- Stand up the repository and its folder structure.
- Write the service’s desired state as files the agent can read.
- Install the reconciliation agent, pointed at its own configuration.
- Enrol the chosen service with destructive behaviour disabled.
- Compare live against the record, then absorb the differences deliberately.
- Switch on automatic sync once the diff reads boring.
- Add drift rules and the documented pause switch.
- Collect numbers, present them, and choose the next service.
Step 1 — Build the Repository Around Folders
Structure the store as directories that describe reality: a top area for cluster definitions, another for shared infrastructure, a third for tenant-level configuration, and an applications area where each service lives. Keep every environment inside those directories as its own folder set. Resist the branch-per-environment arrangement that new arrivals always propose; long-lived branches drift apart, merges turn into archaeology, and nobody can say which branch told the truth last Tuesday. Promotion happens by moving rendered files from one folder to another, which a reviewer can read like any other change.
Step 2 — Declare the State in Plain Files
Capture what the service needs to exist: its workload definition, configuration values, routing, and resource requests. Two renderers dominate the field — one composes templates, the other patches plain manifests — and either is acceptable; what matters is that the files describe the finish line rather than the journey. Render them once in the pipeline and attach the output to the change under review, so the person approving sees the exact result their approval produces. Unrendered abstractions get approved on faith, and faith is not a review process.
Step 3 — Bootstrap the Agent With Itself as the First Customer
Install the reconciliation agent into a test environment and point it at the repository — deliberately including the agent’s own settings among the recorded files. From then on the tool manages its own upgrades and configuration via the identical reviewed route the rest of the platform uses, which removes the classic snowflake where the automation is the one thing nobody dares touch. Both mainstream agents support this from the first minutes of installation; the bootstrapping guides at xOps School’s GitOps guide walk the exact commands for each.
Step 4 — Enrol the Service With the Destructive Parts Off
Register the chosen service in the applications area, and switch pruning off for the enrolment. The reasoning is simple: during migration the record is incomplete, and an agent that deletes whatever is missing from an incomplete record will surprise you. With pruning disabled, mismatches surface as warnings instead of deletions, which is precisely the behaviour you want while the picture is still being filled in. Note the expiry date on this setting — it is scaffolding, not architecture.
Step 5 — Reconcile the Differences on Purpose
Now compare what runs against what is written. Expect noise: fields the platform filled in itself, settings that predate the migration, resource values set by hand during past emergencies. Work through them in one of two directions — absorb them into the record where they are legitimate, or correct the live system where they are not — and keep a log of the decision for each. This is the step where undocumented history gets recovered; treat the oddities as findings, because each one is a configuration fact somebody once considered urgent enough to apply outside the process.
Step 6 — Allow Automatic Sync When the Diff Reads Boring
Watch the sync report for a week. The trigger for automation is dullness: a difference list that stays empty, or contains only the tolerated items you documented in step five. At that point enable self-directed convergence for the service, and add the wake-up hook so merges reconcile in seconds rather than on the next poll — with a shared secret configured on that hook’s endpoint, since such receivers accept unauthenticated knocking unless told otherwise. Boring, evidence-based enablement is the difference between a migration and an experiment that quietly becomes load-bearing.
Step 7 — Write the Drift Rules and the Pause Switch
Fix policy in writing before the first disagreement. For each resource kind, decide whether divergence gets reverted, tolerated, alerted, or shielded from deletion — and name where each rule lives so the next engineer inherits it. Platform-managed values, such as replica counts an autoscaler owns, belong in the tolerated column with an explicit ignore setting. Alongside the rules, rehearse the interruption: suspend reconciliation deliberately, make a manual correction, then bring the record back into agreement before resuming. A pause switch that has never been thrown will not throw smoothly the night it matters.
Step 8 — Measure, Report, and Pick Number Two
Run the service for two weeks and collect four numbers: time from approved change to healthy, the count of unexpected divergences, how many needed a human, and how many edits happened outside the process. Even rough figures beat the anecdotes that preceded them, and the deck that wins budget for round two is the one with these four lines on a slide. Then choose the next service using the same scoring as step one — slightly more important this time, slightly more stateful, never the crown jewels yet. When the city stops looking like a construction site and starts looking like a plan, you are done: what remains is repetition, which is the most transferable skill in this whole business.
GitOps Momentum: What Changes After Service One
Something shifts in the team’s conversation once the first service has lived on the record for a month. Deploy questions stop being personal (“did you run the script?”) and become historical (“what does the record say?”), which lowers the temperature of every incident. New joiners onboard faster, because the repository doubles as documentation that cannot go stale — it is either accurate or the sync report is red, and both states are informative. And the second migration runs at perhaps a third of the effort of the first, because all eight steps now have precedent, tooling, and a written policy behind them. Momentum, in this field, is nothing mystical: it is the absence of novel decisions.
Between migration sessions, step away from the terminal. Readers following our city coverage already know the pattern — the Chennai travel guide to attractions, heritage, and culture makes the same argument for pacing that this article makes for scope, and the best things to do in Chennai for a fun, memorable trip fill an evening nicely once step six goes green. If the family wants a longer break while you finish the rollout, the events, places, and local fun across Kerala we profiled recently are a train ride away.
