plexsphere

Appearance

Author a Blueprint ​

A Blueprint is a catalog entry; an operator provisions a Resource from one of its published versions. This guide registers a Blueprint and publishes its first version with plexctl.

Prerequisites ​

  • An authenticated session — see Log in with plexctl.
  • The platform-level manage relation, which gates registration. The registrar is granted owner on the new Blueprint, which confers the publish permission used in the second step.
  • Three JSON files: the Crossplane XRD, the Composition, and the parameter-schema document. The Composition's compositeTypeRef must name the composite type the XRD declares.

Bind the control-plane URL the steps reference:

shell
export PLEXSPHERE_URL="${PLEXSPHERE_URL:-https://localhost:8080}"

Steps ​

1. Register the Blueprint ​

shell
plexctl blueprint create \
  --server "${PLEXSPHERE_URL}" \
  --slug managed-postgres \
  --display-name "Managed PostgreSQL" \
  --description "A managed PostgreSQL database instance."

The command prints the new Blueprint's id. A duplicate slug exits non-zero with blueprint_slug_conflict.

2. Prepare the version files ​

The parameter-schema file is the canonical document the catalog stores:

json
{
  "parameters": [
    { "name": "storage_gb", "type": "integer", "required": true },
    { "name": "high_availability", "type": "boolean", "required": false }
  ]
}

xrd.json and composition.json carry the Crossplane manifests as JSON objects. A minimal pair:

json
{
  "apiVersion": "apiextensions.crossplane.io/v2",
  "kind": "CompositeResourceDefinition",
  "metadata": { "name": "xmanagedpostgres.example.org" },
  "spec": { "group": "example.org", "names": { "kind": "XManagedPostgres", "plural": "xmanagedpostgres" } }
}
json
{
  "apiVersion": "apiextensions.crossplane.io/v1",
  "kind": "Composition",
  "metadata": { "name": "managed-postgres-composition" },
  "spec": { "compositeTypeRef": { "apiVersion": "example.org/v1", "kind": "XManagedPostgres" } }
}

3. Publish a version ​

Use the Blueprint id from step 1:

shell
plexctl blueprint version create \
  --server "${PLEXSPHERE_URL}" \
  --blueprint-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0b0 \
  --version 1.0.0 \
  --injection-strategy helm-values \
  --provider-kinds aws,hetzner \
  --xrd-file ./xrd.json \
  --composition-file ./composition.json \
  --parameter-schema-file ./parameter-schema.json

The version is immutable; re-publishing the same --version exits with blueprint_version_exists.

The owner grant from step 1 is written asynchronously. If you script register → publish back-to-back and the publish returns 403, retry it after a short delay — the grant has not yet propagated.

4. Confirm ​

shell
plexctl blueprint get 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0b0 \
  --server "${PLEXSPHERE_URL}" \
  --output yaml

The response carries the Blueprint with its versions array including the version you just published.

See also ​