Plugins in Deckhouse Platform

In Deckhouse Platform, plugin delivery differs from a Standalone installation: the operator does not copy plugin binaries to the server manually, but declares the plugin list in ModuleConfig.

After that, the platform:

• Downloads plugins from the specified URLs
• Verifies their checksums
• Places them into the Stronghold container
• Restarts Stronghold when the plugin list changes

After delivery, the plugin still has to be registered in Stronghold and then enabled at the required path.

Configure the plugin list

The list of downloadable plugins is configured in ModuleConfig.

Example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: stronghold
spec:
  enabled: true
  version: 1
  settings:
    plugins:
      - name: "vault-plugin-secrets-github"
        url: "https://github.com/martinbaillie/vault-plugin-secrets-github/releases/download/v2.3.2/vault-plugin-secrets-github-linux-amd64"
        sha256: "72cb1f2775ee2abf12ffb725e469d0377fe7bbb93cd7aaa6921c141eddecab87"
      - name: "vault-plugin-auth-any"
        url: "https://plugins.example.local/myplugins/vault-plugin-auth-any-linux-amd64"
        sha256: "c943b505b39b53e1f4cb07f2a3455b59eac523ebf600cb04813b9ad28a848b21"
        ignoreFailure: true
        insecureSkipVerify: false
        ca: |
          -----BEGIN CERTIFICATE-----
          MIIDDTCCAfWgAwIBAgIJAOb7PcmW8W9MMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNV
          BAMTCWxvY2FsaG9zdDAeFw0yNjA1MjAwMDAwMDBaFw0yNjA2MjAwMDAwMDBaMBQx
          EjAQBgNVBAMTCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC
          ggEBAKHh4g5i1R+3+9XdG0RFLiX1x5T2PvQ92E/78vR6+Bn09+G0P+C6143+wLn
          j96/E8rHbHr4R6L0f62/OJZh8JnZ/qRqE1N8oNc06Vh9Y7X8EzF4nZ4KgX/3y6L
          vXD251Qm7g==
          -----END CERTIFICATE-----

Download parameters

Each plugin in the download list has the following parameters:

• name: Plugin binary name.
• url: URL used to download the plugin. The last URL segment (the file name) must not contain dots, so keep the version out of it (for example, vault-plugin-auth-any-linux-amd64) and pass it with the -version flag when registering the plugin.
• sha256: SHA256 checksum of the plugin.
• ignoreFailure: Allows Stronghold startup to continue even if this plugin could not be downloaded.
• insecureSkipVerify: Disables TLS certificate verification for the remote server.
• ca: PEM-encoded CA certificate used to validate TLS. It is the only trusted CA for this plugin’s URL: system CAs are not used.

What happens when the plugin list changes

Adding or removing plugins triggers a Stronghold restart.

If a plugin cannot be downloaded or validated:

• Stronghold startup is blocked.
• Plugins with ignoreFailure: true are the exception.
• If checksum validation fails, the plugin is treated as not loaded and is removed.

Air-gapped environments

In air-gapped environments where Stronghold does not have outbound internet access, you can host the plugin inside the Deckhouse Platform cluster itself.

One practical approach is:

1. Build or prepare an nginx container image that includes the plugin binary.
2. Run that container in Kubernetes.
3. Expose it through an internal Kubernetes Service.
4. Point ModuleConfig to a URL such as http://<SERVICE>.<NAMESPACE>.svc.cluster.local/... so the platform downloads the plugin through the internal Kubernetes service.

Example ModuleConfig fragment:

spec:
  settings:
    plugins:
      - name: "vault-plugin-auth-any"
        url: "http://plugin-repo.plugins.svc.cluster.local/vault-plugin-auth-any"
        sha256: "c943b505b39b53e1f4cb07f2a3455b59eac523ebf600cb04813b9ad28a848b21"

This approach lets you:

• Avoid opening outbound internet access.
• Keep plugin binaries inside the internal environment.
• Manage plugin versions centrally through an internal service.

Register a plugin

After the plugin is delivered into the container, register it through the CLI:

PLUGIN_SHA=$(sha256sum <PLUGIN_BINARY> | awk '{print $1;}')

d8 stronghold plugin register -command <PLUGIN_COMMAND> -sha256 "${PLUGIN_SHA}" -version "<PLUGIN_VERSION>" <PLUGIN_TYPE> <PLUGIN_NAME>

PLUGIN_SHA=$(sha256sum <PLUGIN_BINARY> | awk '{print $1;}')

stronghold plugin register -command <PLUGIN_COMMAND> -sha256 "${PLUGIN_SHA}" -version "<PLUGIN_VERSION>" <PLUGIN_TYPE> <PLUGIN_NAME>

In the commands:

• <PLUGIN_BINARY>: Path to the plugin binary
• <PLUGIN_COMMAND>: Command that runs the plugin binary
• <PLUGIN_VERSION>: Semantic version of the plugin, for example, v1.0.1
• <PLUGIN_TYPE>: Plugin type: secret, auth, or database
• <PLUGIN_NAME>: Name under which the plugin is registered

Example: register the secret plugin mykv:

d8 stronghold plugin register -command mykvplugin -sha256 "${PLUGIN_SHA}" -version "v1.0.1" secret mykv

stronghold plugin register -command mykvplugin -sha256 "${PLUGIN_SHA}" -version "v1.0.1" secret mykv

Enable a plugin

After registration, enable the plugin as a secret or auth engine:

d8 stronghold <secrets|auth> enable -path <MOUNT_PATH> <PLUGIN_NAME>

stronghold <secrets|auth> enable -path <MOUNT_PATH> <PLUGIN_NAME>

Meaning:

• secrets: For secret-type plugins
• auth: For authentication plugins
• -path: Mount path
• <PLUGIN_NAME>: Registered plugin name

Example:

d8 stronghold secrets enable -path test-kv mykv

stronghold secrets enable -path test-kv mykv

Disable and remove a plugin

To disable and remove a plugin, follow these steps:

1. Disable all secret and auth methods that use the plugin.
2. Deregister the plugin:

d8 stronghold plugin deregister secret my-custom-plugin

stronghold plugin deregister secret my-custom-plugin

1. Remove the plugin from ModuleConfig.

Practical recommendations

Follow these guidelines when you use plugins in Deckhouse Platform:

• For production, use an internal plugin repository or trusted artifact storage.
• Always define sha256 and verify it against the actual binary.
• Use ignoreFailure only for non-critical plugins.
• Remember that changing the plugin list restarts Stronghold.

Additional resources

• Plugins in Standalone