signadot resourceplugin

To create a ResourcePlugin (alias: rp), first write a YAML or JSON file containing a name and a spec. The available fields within spec are documented in the ResourcePlugin spec reference.

For example:

name: my-plugin@1.0.0
spec:
  runner:
    image: ubuntu
  create:
  - name: say-hello
    script: |
      #!/usr/bin/env bash
      echo hello
  delete:
  - name: say-goodbye
    script: |
      #!/usr/bin/env bash
      echo good-bye

Submit this plugin by passing the filename to the resourceplugin apply command:

signadot resourceplugin apply -f my-resourceplugin.yaml

Versioning

Requires CLI v1.7.0 or later

Requires Signadot CLI v1.7.0 or later. Earlier CLIs continue to work for unversioned plugins but lack the @<semver> surface, the versions subcommand, the --all-versions flag, and the tailored error messages below.

Resource plugins are versioned with semver. The version travels with the name: field as an @<semver> suffix — there is no separate version: field. Omitting the suffix publishes the plugin at the default version 0.0.0:

# Publishes my-plugin@0.0.0. Round-trips back from `get` as plain
# `name: my-plugin`, indistinguishable from a pre-versioning plugin.
name: my-plugin
spec:
  ...

The version is canonicalized on the way in, so @v1.0.0 and @1.0 are accepted and stored as @1.0.0. Subsequent get and list responses always show the canonical form; the immutability error (below) is the one exception — it repeats the version exactly as you typed it, so applying @1.0 against an existing @1.0.0 reports version "1.0" already exists.

Published (name, version) pairs are immutable. Re-applying a version that has already been published fails with an error that names the existing version and points at the suffix to change:

Error: resource plugin "my-plugin" version "1.0.0" already exists; versions are immutable — bump the @<semver> suffix on name: to publish a new revision

For a bare-name plugin (whose published version is the default 0.0.0), the error identifies the default slot explicitly and shows a sample suffix:

Error: resource plugin "my-plugin" default version (0.0.0) already exists; versions are immutable — add an @<semver> suffix to publish a new revision (e.g. my-plugin@0.0.1)

Inspecting plugins

resourceplugin list returns the latest version of each plugin. Pass --all-versions to expand the output into one row per published (name, version), sorted by name then semver-descending. To enumerate every published version of a single plugin, use versions:

# All plugins (highest-semver version of each)
signadot resourceplugin list

# Every published version of every plugin
signadot resourceplugin list --all-versions

# Every published version of one plugin
signadot resourceplugin versions my-plugin

The default list (without --all-versions) prints a one-line footer counting how many plugins have more than one published version, so multi-version plugins aren't invisible from the collapsed view:

(2 plugins have multiple versions — pass --all-versions to expand, or 'resourceplugin versions NAME')

resourceplugin get accepts NAME[@VERSION]. Omit the suffix (or pass @latest) to fetch the highest-semver published version:

# Latest version
signadot resourceplugin get my-plugin

# A specific version
signadot resourceplugin get my-plugin@1.0.0

The response renders the plugin's name in the same form a user would type to refer to it: bare my-plugin when the plugin is at the default 0.0.0, or my-plugin@<semver> for any other version. get -o yaml produces a spec that apply -f accepts without renaming any field. (The exact response also carries server-populated fields — createdAt, updatedAt, status — which apply -f silently ignores on input; round-trip is functional, not byte-identical.)

Deleting plugins

Delete by name (with an optional version suffix) or by pointing at the same file that was used to create the plugin. Omitting the suffix targets the highest-semver published version:

# Delete the latest version
signadot resourceplugin delete my-plugin

# Delete a specific version
signadot resourceplugin delete my-plugin@1.0.0

# Delete the version specified in a file (via the name@version suffix)
signadot resourceplugin delete -f my-resourceplugin.yaml

A specific plugin version cannot be deleted while any sandbox references that exact version. Older versions may be deleted once no sandbox pins them, even if newer versions of the same plugin are still in use.

note

The bare-name form means different things depending on context. As a delete target it resolves to the latest version, not the default 0.0.0 — so delete my-plugin on a plugin that has been bumped past 0.0.0 removes the newest revision, not the unversioned slot. Pass my-plugin@0.0.0 explicitly to target the default version.

For reusable resource plugin definitions, check out YAML Templates.