Register a Blueprint

A Blueprint is a reusable recipe; a BlueprintVersion is a concrete, immutable revision of it. This lesson — the last of the three that build the provisioning catalog — registers the cloudless demo Blueprint and publishes its first version, still acting as the platform operator.

The lean local stack has no cloud account, so the demo uses a cloudless blueprint: a dev-only recipe whose substrate is rendered entirely in-cluster. A Blueprint stands on its own — it needs no Cloud or Credential — so you can take this lesson before or after the other two catalog lessons.

This lesson takes about ten minutes.

Before you start

This lesson is standalone: it does not depend on the Cloud or Credential lessons. You need a running, logged-in stack from Set up your local plexsphere, jq on your $PATH, and kubectl pointed at the local cluster — the version id is read straight from Postgres at the end.

You act as the platform operator throughout — operator@example.com, which holds the platform:plexsphere#admin authoring grant that gates Blueprint registration. See the tutorials overview for the full cast.

Recreate the shell environment and read the Acme Corp Domain id and its active IdP binding with make dev-ids — the operator sign-in needs both:

export PATH="$PWD/bin:$PATH"
export PLEXSPHERE_URL=http://localhost:8080

eval "$(make -s dev-ids)"
echo "domain=$DOMAIN_ID binding=$BINDING_ID"

Step 1 — Register the Blueprint

Sign in as the platform operator under the operator profile, completing sign-in in the browser as operator@example.com with the password password:

plexctl login --profile-name operator --domain-id "$DOMAIN_ID" --idp-binding-id "$BINDING_ID"

Author the cloudless Blueprint — registration is gated by the platform#manage authoring grant the operator holds:

BLUEPRINT_ID=$(plexctl blueprint create \
  --slug kubernetes-cloudless-node \
  --display-name "Cloudless Kubernetes Node" \
  --description "A node materialised entirely in-cluster, with no cloud account." \
  --profile operator --output json | jq -r '.id')
echo "$BLUEPRINT_ID"

Step 2 — Publish a version

The cloudless version renders a real in-cluster node, so it carries the full Crossplane XRD and Composition manifests — these ship in the repository as the canonical cloudless recipe under internal/provisioning/blueprints/catalog/kubernetes-cloudless-node/. Publishing a version from a pair of manifest files is its own flow: Author a Blueprint walks through converting the recipe's xrd.yaml and composition.yaml to the JSON files the command takes. With those files in hand, publish under the Blueprint you just created:

plexctl blueprint version create \
  --blueprint-id "$BLUEPRINT_ID" \
  --version v1alpha1 \
  --injection-strategy helm-values \
  --provider-kinds aws \
  --xrd-file ./xrd.json \
  --composition-file ./composition.json \
  --parameter-schema-file ./parameter-schema.json \
  --profile operator

The cloudless blueprint declares no parameters — the node it stands up needs no operator input — so parameter-schema.json is {"parameters":[]} and the resource create in the provisioning lesson passes an empty object.

Step 3 — Read the version id

resource create takes the BlueprintVersion's id, the broker's internal handle for that revision. That id is not surfaced on the read API, so read it straight from the database:

VERSION_ID=$(kubectl exec statefulset/postgres -- \
  env PGPASSWORD=plexsphere psql -U plexsphere -d plexsphere -tAc \
  "SELECT id FROM plexsphere.blueprint_versions WHERE blueprint_id='$BLUEPRINT_ID'")
echo "$VERSION_ID"

That VERSION_ID is the unit a Resource is provisioned against — the provisioning lesson re-derives it the same way, so there is nothing to carry across.

What you learned

• A Blueprint is a recipe; a BlueprintVersion is an immutable revision. You register the Blueprint once, then publish one or more versions under it; a published version never changes.
• The cloudless blueprint needs no cloud account. Its substrate is rendered entirely in-cluster, so the same provisioning flow runs on the lean local stack with no provider behind it.
• The version id is the unit you provision against. resource create takes the immutable BlueprintVersion id — not the Blueprint id — and the parameter schema tells you what input it needs. The cloudless version declares none.

Where to go next

• Keep learning by doing — Provision a cloud Resource consumes the Cloud, Credential, and Blueprint you built across these three lessons: request and approve a credential assignment, then drive a Resource through the broker's lifecycle to Ready.

Or pick the quadrant that matches what you need now:

• You have a job to do — the Author a Blueprint how-to covers the operator runbook, including the manifest conversion.
• You want the exact contract — the plexctl blueprint reference documents every flag and output shape.
• You want to understand why the catalog is shaped this way — the Blueprint Catalog context explains the Blueprint and version aggregates.