plexsphere

Appearance

Manage Label Definitions ​

A Label Definition is the schema for a label key plus its value contract and on-delete policy. plexctl label define wraps /v1/label-definitions.

Prerequisites ​

  • An authenticated session — see Log in with plexctl.
  • The scope coordinate: platform, domain:<uuid>, or project:<uuid>. Pick the narrowest scope that covers every object you label.

Steps ​

Create a Definition ​

shell
plexctl label define create \
  --scope domain:<domain-uuid> \
  --key tier \
  --type enum \
  --on-delete block
# ID  SCOPE     QUALIFIED_KEY  TYPE  APPLICABLE_KINDS
# …   domain:…  tier           enum  …

--type is checked against the value-schema kinds (boolean, numeric, regex, enum, string). --on-delete is block, cascade, or orphan — the policy applied when you later delete the Definition while Assignments still exist. block refuses the delete; cascade removes the Assignments with the Definition; orphan detaches them, leaving them readable per object (with a null parent definition) but excluded from Definition-scoped listings.

List, inspect, and update ​

shell
plexctl label define list --scope domain:<domain-uuid>
plexctl label define get <definition-uuid>
plexctl label define update <definition-uuid> --description "Service tier"

scope, key, and immutable are frozen after creation.

Delete a Definition ​

shell
plexctl label define delete <definition-uuid> --yes

Delete honours the Definition's own on_delete policy.

From the Console ​

Open the Domain's Label definitions page, use the per-row Delete action, and confirm in the modal. The delete is irreversible.

Two refusals surface inline rather than as a generic error:

  • A block-policy Definition that still has Assignments is refused — detach the Assignments first, or choose a Definition whose on-delete policy allows removal.
  • A system-managed Definition cannot be deleted.

Verification ​

shell
plexctl label define get <definition-uuid> --output json | jq '{local_key, value_schema}'
# {
#   "local_key": "tier",
#   "value_schema": { … }
# }

See also ​