The Passage Plan: every BKE upgrade, laid out before it runs

Every component of a Bahriya Kubernetes Engine (BKE) cluster is configured by a values file that belongs to the customer. The file can be edited, kept in source control and reviewed like any other configuration, and BKE never silently overwrites an edit to it. When an upgrade ships new defaults, apply.sh without --commit reports what would change in each file, and changes nothing on the cluster.

That report now has a second form. The Passage Plan shows the same diffs in the Mamluk console, in full and in colour, so that the people who approve an upgrade can read exactly what it will do before anyone commits to it.

Why “Passage Plan”

Before a ship leaves harbour, the navigator draws a passage plan, and the master approves it: every leg of the voyage and every hazard on it, decided before the vessel moves. An upgrade of a production cluster deserves the same discipline. The terminal report has always provided it for the engineer at the node. The Passage Plan extends it to the architect who reviews the change and to the board that approves it, who rarely have a shell on the node.

What it shows

The report separates what BKE changed from what that change means for the customer’s own file, because the two answer different questions.

What BKE changed. BKE’s default for the version the cluster is on, against its default for the version it is moving to. It is the same for every cluster with the same configuration, which makes it the diff to quote in a support request.
What changes in your file. The file as it is now, against the file that apply.sh --commit will write and hand to Helm. Edits the customer has made stand. Where the customer and BKE changed the same setting differently, the run stops and shows both values, because a wrong automatic choice about a gateway’s configuration is worse than a halted upgrade.

The Passage Plan in the Mamluk console for a Longhorn upgrade, in the unified view. Under the heading What BKE changed, six added lines set networkPolicies.restrictInternalTraffic to false, with a comment explaining that BKE keeps the behaviour of the version the cluster is on. Under What changes in your file, the same six lines are added to /etc/bke/values/longhorn.yaml.

In this example, a new Longhorn chart would restrict traffic between Longhorn’s own components by default. BKE’s new default keeps the behaviour of the version the cluster is on, and the Passage Plan shows that one setting being added to the customer’s file. The customer’s own Longhorn settings are left exactly as they were.

Drift is caught first

A values file only describes a cluster if nobody has changed the cluster around it. When someone has run Helm by hand, apply.sh compares what each release is actually running with what its file says. If they disagree, it shows that difference alone and goes no further, because every other diff in the report would have been computed against a file the cluster is not running.

The Passage Plan in the side-by-side view, headed Your file is not what the cluster is running, for Kong. The left column shows what the cluster is running according to helm get values; the right column shows /etc/bke/values/kong.yaml. Four lines differ: averageUtilization, nginx_worker_connections, and the CPU and memory limits.

Here, Kong’s limits were raised on the cluster and the values file was never updated. The side-by-side view puts the two versions of each line next to each other, with line numbers on both sides and unchanged stretches folded away until they are needed.

Nothing is summarised away

The terminal output has not changed. Every diff is still printed on the node, and a diff too large to print is still counted rather than shown. The report now ends with a link to the Passage Plan, where that diff is shown in full as well. Opening the link is optional, and the page is read-only: what it shows is applied only when apply.sh --commit is run on the node.

Private by construction

A values file can hold more than settings, and the Passage Plan is designed on that assumption.

Encrypted, with a key we do not keep. The diffs are encrypted before they are stored, under a fresh key for every report. The key is printed on the node and carried in the link after the #, which a browser does not send to any server. The console decrypts the Passage Plan in the reader’s browser.
Members only. The link alone opens nothing. The reader must be signed in to the console as a member of the organisation that holds the licence.
For an hour. The link stops working an hour after the report, and the report states when. Running apply.sh again without --commit produces a new one, and changes nothing on the cluster.
Only the diffs. What is kept is the diffs the report showed, and nothing else about the cluster or its configuration.

Availability

The Passage Plan is part of every BKE licence, including the 14-day trial, and needs nothing installed or enabled. The next run of apply.sh that would change a values file links to it.

The Passage Plan page on the BKE site describes it further, and Installing components in the BKE documentation covers the report, the four outcomes for a customer’s edits, and how to resolve a conflict.