Exercise · Trace the Sandcastle → Kubernetes hand-off on paper

A short, pen-and-paper task. Complete it before moving on to the runnable Lab.

See the Open Engineering Language Server (OELS) onboarding guide for the local install and editor setup.

TipOELS in your editor

While you work through this content, keep the Open Engineering Language Server (OELS) active in VS Code (or any LSP-capable editor). See the OELS onboarding guide linked at the top of this page (also linked from the academy Resources page) for the one-time install and configuration steps.

What OELS validates. OELS only recognizes OE-shaped YAML/JSON: files with a mapping root that declare an apiVersion beginning with open-engineering.io/, a non-empty kind, and a DNS-1123 metadata.name. Ordinary academy metadata.yaml, Quarto/QMD pages and front matter, Kubernetes/Crossplane/runtime manifests, JSON payload samples, and shell scripts are intentionally non-OE — OELS ignores them silently and you should not add synthetic apiVersion/kind headers to force recognition.

Where you see diagnostics. OELS surfaces UnknownProperty, MissingRequiredProperty, IncorrectType, InvalidEnumValue, MalformedIdentifier, UnknownDefinition, and reference-shape hints in the editor Problems panel as you type. These are independent of quarto render: OELS diagnostics do not block rendering, and Quarto errors do not appear in the Problems panel.

The executable check still comes from this exercise. OELS speeds up editing, but the exercise’s own parser, verifier, or verify.sh (for example the pico parse … command shown below) remains the authoritative success check. Run it as usual.

Task

Trace, on paper, the concrete hand-off from the Sandcastle branch to a Crossplane Composite Resource, then use the trace to spot two boundary violations this lab intentionally rules out.

You do not need a cluster or the runnable lab for this exercise. The goal is to lock in the construct → compose boundary as a one-page picture before touching any tooling.

Step 1 · List the boundary inputs and outputs

Copy this table into your notes and fill in the blanks:

Position File on disk Field
Sandcastle output rules/hello.yaml on branch ___________________ ___
Crossplane input 05-xr.yaml ___

Answer in your notes: how many fields cross the boundary? (Answer: one — the greeting value.)

Step 2 · Diagram the hand-off

Sketch a two-arrow diagram:

   [Sandcastle target repo]        [Crossplane XR file]
   branch: sandcastle/hello-world-pico
       │
       │ (1) read rules/hello.yaml
       ▼
   [.value = "Hello, Pico!"]
       │
       │ (2) write spec.value into an XHelloWorldPico XR
       ▼
   apiVersion: oe.academy/v1alpha1
   kind: XHelloWorldPico
   metadata: { name: hello }
   spec: { value: "Hello, Pico!" }

Answer in your notes: what would you need to change on either side of the diagram if the greeting were different? (Answer: only the value: field; the surrounding shape is fixed by the XRD.)

Step 3 · Spot the boundary violations

For each of the following hypothetical hand-off implementations, mark ✅ if it is well-behaved or ❌ if it violates one of the four rules from the lesson (read-only against the sandbox, deterministic, byte-equivalent to the downstream contract, cluster-independent). For each ❌, name which rule.

Case 1

The hand-off script clones the sandbox directory to re-read rules/hello.yaml from there because it is “faster than a Git read”.

❌ Violates read-only against the Sandcastle side — the sandbox is disposed by design; reaching into it makes the hand-off non-reproducible.

Case 2

The hand-off script reads rules/hello.yaml from the branch, then also appends the current timestamp to the XR’s spec.value so the greeting is unique per run.

❌ Violates deterministic against the branch — the same branch should always produce the same XR.

Case 3

The hand-off script emits an XR that uses oe.academy/v1beta1 instead of v1alpha1 because “the beta version is nicer”.

❌ Violates byte-equivalent to the downstream contract — the Kubernetes lab’s XRD only serves v1alpha1; the XR would fail admission on the cluster.

Case 4

The hand-off script requires kubectl to be pointed at a running cluster before it will produce the XR file.

❌ Violates cluster-independent — the hand-off is a file-in-file-out step; cluster reconciliation is the Kubernetes lab’s responsibility.

Case 5

The hand-off script reads rules/hello.yaml from the branch, extracts .value, writes the XR YAML, and exits.

✅ Well-behaved — this is exactly what handoff.sh does.

Success criteria (paper)

Next

Run the hand-off end-to-end in the Lab.