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.
In the site
Section titled “In the site”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.
Creating plugin resources
Section titled “Creating plugin resources”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.
Credentials
Section titled “Credentials”The operator is shared, so it has no cloud credentials of its own. You give it yours:
- Create a Secret with your credentials in your namespace.
- Add the label
plugins.ctrlplane.run/copy=trueto it. ctrlplane copies it to the operator within five minutes. A change to the Secret is copied too. - Point the plugin’s config at the Secret, in your namespace. Each plugin’s page in the catalog shows how.
kubectl create secret generic aws-creds --from-file=credentials=./aws-credentialskubectl label secret aws-creds plugins.ctrlplane.run/copy=trueSecrets without the label stay in your control plane.
- Use your namespace only. Requests for other namespaces are refused.
- A field
namespacein 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.
Turning a plugin off
Section titled “Turning a plugin off”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.
From the CLI
Section titled “From the CLI”The commands work on your current control plane (ctrlplane use <name>), or on --cp <name>:
ctrlplane plugins # all plugins, and which are onctrlplane plugin on crossplane-aws-s3ctrlplane plugin off crossplane-aws-s3If 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.
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": falsemeans 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.