1. Start here

1.5 Developer experience: onboarding, migration and operations

Requirements: R8, R9, R11, R13, R14, R16, R18, R23, R24, R25, R26, R29, R30, R31, R33, R34, R22.

The platform as an application team meets it: three journeys - onboarding a new application, migrating one that runs elsewhere, and operating the ones in production - told as use cases. The application contract says what a team has to deliver; this page says what happens around it, from the first request to the day the application is retired. It names no tool: the sections it links to do.

Four rules shape every journey:

1. The team owns its application and its repository; the platform owns everything cluster-scoped. A team writes plain Kubernetes for its namespace and nothing else (section 1.4); the namespace, identities, roles, routes’ gateway, DNS, certificates and firewall rules are made for it.
2. Every interaction is a pull request or a request. A change to the application is a pull request in the team’s repository; a change the platform must make for the team (a namespace, an identity, a firewall rule, a secret share) is a request that an agent turns into the platform’s pull request, approved by its risk tier (section 6.1). Nobody, human or agent, changes a cluster by hand.
3. The platform answers before the team asks. Admission policy and the CI checks tell a team what the contract misses before anything runs; denied flows become proposed rules; the right-sizing, release and operations agents open the pull requests and issues a team used to write itself.
4. The same experience in every environment and every cloud. dev, acc and prd differ only in who approves and how fast (section 3.2, R25); a second cloud is the same contract under another implementation (section 1.3, R16).

Running it with a small platform team: the non-negotiable rules

The platform is run by a few people for many applications, with the agents of section 6.1 doing the routine. It stays small only if the platform team does no work per application and negotiates nothing per application: every rule is a policy, a timetable or a limit that applies to every application alike and is applied by a check, an agent or admission, never by a person. The rules below are the ones a team accepts at onboarding (R33); a team that cannot meet one is not onboarded, or carries an exception with an owner and an expiry date (exemptions expire). The platform’s time goes into the rules and the exceptions, not into the applications.

The rules are the first page of the onboarding request: the team accepts them before anything is created for it.

What a team has, and what it never has

Onboarding a new application

The journey from an idea to the first request served in production. Each step is a use case; the right column says who or what does the work.

The onboarding is done when the application serves its name in prd, its SLOs are measured and its owner is on the cost report. The team never created a cluster-scoped object, a DNS record, a certificate, a role assignment or a Firewall rule - it asked for them, by template or by confirming a proposal.

Adding a team member is a change to the team’s Entra ID groups, not to the platform; adding a second application of the same team repeats steps 1 to 7 with a new namespace in the same repository.

Trying it before dev: previews and sandboxes

A team tests a change before it reaches dev’s main, and tries the platform before its first onboarding, in dev itself (R34) - never in a separate sandbox cluster, which would be a fourth environment that drifts and a place where the contract is not enforced. Both kinds of namespace meet every policy of dev, so what works in them works in prd.

A preview is not a release: it never reaches acc or prd, is never promoted, and carries no main commit. It gives a team the real gateway, policies, egress control and telemetry for a branch, which is what a local environment cannot.

Migrating an existing application

An application that runs today on a virtual machine, another Kubernetes cluster or another cloud meets the contract for the first time. The journey adds an assessment and a cut-over to the onboarding; the onboarding itself does not change.

1. Assess against the contract

The team lists what the application does today, and every finding falls into one of four classes. The classes decide the effort and the approvals, not the tools:

The assessment ends as a list of findings with their class, kept with the application, and the same CI check that onboarding uses turns the second class into failing checks the team works down. Every “change where it runs” finding and every exception goes through the onboarding request, where a human approves it.

2. Prepare the data

Data moves first and separately from the code, because two versions run during any cut-over (compatibility rule): the target PaaS service is created by the onboarding, the data is copied or replicated into it with the service’s own migration tooling while the old application keeps running, and the application is made to work against the new store before it moves. The schema follows expand → migrate → contract; a store that cannot be replicated is moved in a planned window, which is the one downtime the journey allows and the team’s call. Where the data stays in the stateful cluster, its exception, backup posture and restore owner are part of the request (section 6.3).

3. Onboard, then cut over

The application is onboarded like a new one (steps 1 to 7 above), in dev first with test data, then in acc and prd next to the running old one, under its platform name. The cut-over moves the clients, and follows the same shape as the migration between cells:

1. Deploy the application in prd on the platform; nothing points to it yet.
2. Test it on its platform name over the real TLS path, with the migrated data.
3. Switch the clients: the old name becomes an alias of the platform name, or the clients are reconfigured, in the order the team chooses (a share of the clients first where the clients allow it).
4. Drain the old deployment: wait until it sees no requests, keep it ready to take the name back.
5. Remove the old deployment and its data after the soak; it was the rollback until then.

Rollback at any step before the last is moving the name back; the data store is already the new one, so the old application must be able to read it, which is what step 2 of the preparation made sure of.

4. Moves inside the platform

Once onboarded, an application moves without a second migration project:

Operating applications in production

What a team does with an application once it is in prd, and what the platform does for it. The platform’s own operations - upgrades, capacity, policy, incidents of the platform - are the agents’ (section 6.1); here is what the team sees of them.

Releasing a change

A merged pull request in the team’s repository is a release candidate; the promotion pull requests carry it to acc and prd, and the release train moves it through the cells one at a time behind SLO gates (releases cell by cell). The team sees the train on its pull request: which cell runs the new version, the test results on the per-cell names, the soak, and a rollback with its reason when a gate fails. Consequences the team plans for:

• A change rides a train with other teams’ changes; a release is not instantaneous. An urgent fix takes the same path with a shorter soak, and a team that needs to stop a rollout asks for the halt - a safe action that needs no pull request (section 6.1).
• Two versions run at once during the train, so every change is backwards compatible with the previous one; the compatibility rule is the team’s, not the platform’s to check.
• Switching an application off is replicas: 0 in Git; it is switched on the same way. Nothing in between is allowed (R23).

Patching: base images and dependencies

Patching is the one change that must reach every application without anyone asking every team, so the platform drives it and the team’s tests gate it:

• Base images are the platform’s. For every supported runtime and version (a .NET LTS, a Java LTS, Node LTS, Python, a static base for Go and the like) the platform keeps one base image in the environment’s registry, built from the vendor’s image, scanned and signed. Every application image is built from one of them by the platform’s build workflow in the team’s repository, and records its base, so the registry knows every image per base.
• A vendor patch rebuilds the fleet. When the vendor publishes a patch, the platform rebuilds the base, then the base image agent rebuilds every application on it from the current commit of its main: the same source, a new base layer, the team’s tests and the contract check in CI, a signed image. Each rebuild is a pull request in the team’s repository that sets the new digest for dev and merges itself when the tests pass (tier low); the release agent’s promotion pull requests carry the digest to acc and prd the same way (tier low: a digest that passed every gate in acc). The patch train runs on the automated gates alone - the tests, the smoke tests on the per-cell names, the SLO gates and a shorter soak - inside the change windows; a breach rolls the cell back like any release (section 3.4).
• The timetable is the update policy’s: a routine patch rides the next train in each environment; a fix for an actively exploited vulnerability takes the emergency fast track of section 3.5 - the waiting times skipped with the platform owner’s approval, still dev → acc → prd and one cell at a time. A runtime version that reaches its end of life is retired on a date; the team moves to the next supported base before it, under the same deadline rule.
• Dependencies inside the image (packages the application brings) are the team’s to update; the registry’s scan reports them with the same deadlines, and a critical one past its deadline is treated like a stale base.
• What the team sees: a pull request it did not write that merges itself, an issue with a date when a rebuild or its tests fail, and the share of its images on the newest base in the compliance report. It does nothing else.
• What the team owes: an image built from the platform’s base with the platform’s workflow, a main that always builds and passes its tests, and tests that prove its routes - because nothing else stands between a rebuilt image and prd.

Knowing that it works

The team’s SLOs, dashboards and alerts live next to its manifests and are applied with them (section 1.4). The default SLOs - availability and latency at the zone’s gateway - exist from the first run; the team sets the targets and adds what the gateway cannot see (queue lag, business events). Alerts are routed by the namespace’s team label (section 2.6), and every member of the environment’s Grafana stack sees everything in it (R31), so a team debugs a call across applications with one trace id, and keeps secrets and personal data out of what it logs (what must not be sent). The same place shows the application’s cost per month by team and cost centre, and its requests against its use.

Being on call

An alert on the application reaches the team; an alert on the platform reaches the platform. The line between the two is the contract: the gateway, nodes, network, DNS, certificates, Firewall, the vault and the cluster are the platform’s, the pods and their behaviour are the team’s. The operations agent triages every alert first, correlates it with releases, platform changes and cell health, and files an issue with the evidence - to the team when the cause is in its application, to the platform otherwise (section 6.1), so a team on call starts from a diagnosis, not from a dashboard. In prd a team reads its namespace and changes it only through Git; there is no shell into a pod of prd, and break-glass is the platform’s, followed by a pull request that brings Git back in line.

Changing the application’s resources, access and reach

Every day-2 change of an application is a pull request, and most of them are proposed before the team asks:

Living with the platform’s changes

The platform changes under the application without asking it, and the team notices only what concerns it:

• Cluster upgrades, node images and base images are invisible: a cell is drained, upgraded and returned; an internal application is migrated out of the cell and back (section 3.5). What the team owes is the contract’s rollout rules, which make the drain harmless.
• A removed Kubernetes API or a new policy reaches the team as an issue from the upgrade or compliance agent with the manifests concerned and a date (section 6.1); a policy starts in audit, so the team sees its finding before it is denied (section 2.7).
• A cell failure fails the internal applications of that cell over to another cell and leaves a drained external cell out of the answers; the team is told, and does nothing (section 3.1). A region loss is the platform’s recovery; the team’s part is the restore of its own data stores, named at onboarding (section 6.3).
• Cost is reported, not negotiated: the capacity and cost agent files an issue when an application’s requests are far from its use or its spot share could grow; the team answers with a pull request or a reason.

Retiring an application

The last use case is the first in reverse: the team removes the application’s directory and its cell directories, and asks for the retirement. The request removes, in order, the DNS name, the Flux configuration, the namespace and its roles, the Firewall rules and the traffic flow page, the identity and its roles, the vault prefix (recovered for the vault’s retention, then purged) and the budget line; the backups of its data stores stay for their retention and are the last thing to go. The cost report shows the team’s share going to zero.

The same journey in every environment