Compose a Sandcastle request

Turn a learner-authored Crossplane XR into an EngineeringTask and have a Sandcastle construct the requested artifact on a durable branch.

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.

Overview

Compose a Sandcastle request is the first runnable lab that demonstrates the compose → construct boundary of the academy story:

Crossplane composes, Sandcastle constructs, Picos behave.

The lab takes a learner-authored Crossplane XHelloWorldPico request, runs a small local composition that turns the XR into an EngineeringTask (a declarative record of the construction work the cluster wants done), and has a Sandcastle pick up that task, construct the requested artifact on a dedicated branch, and dispose of the sandbox. The construction stage is parametric on the request — the greeting comes from the XR, not from a hard-coded string.

This lab is reusable across courses: it lives at the repository root under labs/compose-sandcastle-request/ and is referenced from the Sandcastle course.

Structure

What you will produce

Two durable artifacts:

  1. work/compose-sandcastle-request/task/engineering-task.yaml — the EngineeringTask the composition emitted from the XR. It is the produces entry compose-sandcastle-request-engineering-task in metadata.yaml.
  2. A durable branch named sandcastle/hello-world-pico-<name> on a local target repository (where <name> is metadata.name from the XR), containing exactly one committed file (rules/hello.yaml) whose greeting value matches spec.value from the XR. This is the produces entry compose-sandcastle-request-branch.

The XR-side and the branch-side never meet inside the Sandcastle: the composition emits the EngineeringTask, and only the EngineeringTask crosses into the sandbox. That separation is what verify.sh’s fifth assertion checks.

Downloads and screenshots

Runnable files live under downloads/:

  • xr-request.yaml — the learner-authored Crossplane XR requesting a hello-world-pico artifact with a specific greeting value.
  • compose.sh — the simulated Crossplane Composition that turns the XR into an EngineeringTask. Writes no code and touches no repository.
  • expected-task.yaml — reference EngineeringTask shape the generated task is compared against.
  • sandcastle-run.sh — Sandcastle driver that reads the EngineeringTask, provisions the isolated workspace, runs the task-driven agent under a PATH allowlist, hands the branch back, and disposes of the workspace.
  • sandcastle-agent.sh — the task-driven inner iteration loop (inspect task → generate → validate → commit) run inside the sandbox. Reads the greeting from the mounted EngineeringTask; never sees the XR.
  • verify.sh — automatable check that runs the full compose → construct path and asserts the five boundary invariants.

Screenshot targets for the walkthrough live under screenshots/; no image files ship yet.

Metadata

Machine-readable descriptor: metadata.yaml. Fields follow the same schema as labs/hello-pico/metadata.yaml.

Referenced from