Skip to content

Plugins

A plugin is an operator that ctrlplane runs for you, for example a Crossplane provider. You do not deploy it. Turn one on under Plugins, or with ctrlplane plugin on <plugin>. You get:

  • Its API types. The plugin’s CRDs appear in your control plane, read-only.
  • Its operator. Create the plugin’s resources in your namespace. ctrlplane’s copy of the operator reconciles them. It does not show in your controller list, and it does not count toward your limits.

To see which plugins you can turn on, see the plugin catalog. Each plugin has a page with its steps and an example.

The site keeps plugin types apart from your own types:

  • Plugins shows each plugin that is on. It shows the objects of each plugin type, with Delete. Open an object to see or edit its YAML. Expand the line N API types · N objects to see all types of the plugin.
  • API and Resources show only your own CRDs and objects. Their counts do not include plugin types.
  • Plugin catalog shows all plugins, with their API types, an example and links to their docs. Open it from the home page, or with How to use on a plugin.

kubectl shows all types together, as usual.

Use one of these:

  • kubectl apply -f bucket.yaml
  • The site: Resources → Apply resources. Paste the YAML there. The object then shows under Plugins, not under Resources.

The operator is shared, so it has no cloud credentials of its own. You give it yours:

  1. Create a Secret with your credentials in your namespace.
  2. Add the label plugins.ctrlplane.run/copy=true to it. ctrlplane copies it to the operator within five minutes. A change to the Secret is copied too.
  3. Point the plugin’s config at the Secret, in your namespace. Each plugin’s page in the catalog shows how.
Terminal window
kubectl create secret generic aws-creds --from-file=credentials=./aws-credentials
kubectl label secret aws-creds plugins.ctrlplane.run/copy=true

Secrets without the label stay in your control plane.

  • Use your namespace only. Requests for other namespaces are refused.
  • A field namespace in a plugin resource must name your namespace.
  • Plugin resources can not have owner references.
  • Each kind of plugin resource has a limit of 100 objects.
  • The plugin’s CRDs are read-only. To remove them, turn the plugin off.
  • Your own admission webhooks and policies do not apply to plugin resources. The plugin’s own checks apply.
  • Turning a plugin on or off restarts your API server for a few seconds. Your resources and controllers stay.

ctrlplane refuses while resources of its API types exist. Delete them first. Then its API types go away.

If you have a CRD of your own in a group that a plugin brings, turning the plugin on is refused. Delete your CRD first.

The commands work on your current control plane (ctrlplane use <name>), or on --cp <name>:

Terminal window
ctrlplane plugins # all plugins, and which are on
ctrlplane plugin on crossplane-aws-s3
ctrlplane plugin off crossplane-aws-s3

If ctrlplane refuses, the CLI shows the reason. For example, resources of the plugin still exist.

For clients other than the CLI, use the site’s API:

Method Path Does
GET /tenants/<name>/plugins Lists the plugins, and which are on
POST /tenants/<name>/plugins/<plugin> Turns the plugin on
DELETE /tenants/<name>/plugins/<plugin> Turns the plugin off

<name> is your control plane’s full name, for example alice-dev.

Send two headers:

  • Authorization: Bearer <token>. Get the token from the CLI.
  • Accept: application/json. Without it, you get HTML for the site.
Terminal window
TOKEN=$(ctrlplane token | jq -r .status.token)
curl -X POST https://app.ctrlplane.run/tenants/alice-dev/plugins/crossplane-aws-s3 \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

The answer to POST and DELETE:

  • 200 and {"name": "crossplane-aws-s3", "on": true, "changed": true}: done. Your API server restarts for a few seconds. "changed": false means it was on (or off) already.
  • 400 and {"error": "..."}: refused. The message says why.

The token expires after some time. Run ctrlplane token again to get a new one.