Declarative plugins

External plugins can be declared with the plugin stanza. This is primarily intended for:

1. Simple plugin deployment: The combination of OCI-based plugin distribution, auto-download, and auto-registration is the recommended plugin deployment flow.
2. kms plugin deployment: kms plugins cannot be registered via the API (since they must be available in a sealed state). The declarative method is the only way to define kms plugins.

The plugin stanza allows the declaration of both plugins automatically downloaded from an OCI registry and manually downloaded plugins.

OCI-based plugin distribution

OpenBao supports the distribution of plugins in Open Container Initiative (OCI) artifacts. Operators can define the desired plugins for their OpenBao cluster directly in the server configuration files. On startup, OpenBao will check for locally cached binaries, verify their integrity, and only download and extract new or updated plugin binaries from the specified OCI artifacts if necessary. This approach uses existing container ecosystem tooling and infrastructure for robust, secure, and efficient plugin management.

Making use of OCI based plugins provides a number of advantages over manually managing the plugin binaries:

• Automated Discovery and Installation: Operators can define the used plugins in code and OpenBao will automatically download and extract them during startup.
• Version Management: Distributing new a new version of a plugin just requires an update of the configuration file instead of manually placing the binary on every node.
• Supply Chain Security: Using OCI registries for plugin distribution allows operators to make use of the registries security features like authentication, vulnerability scanning and immutable storage.

plugin

A plugin block defines an OCI-based plugin to download:

plugin "type" "name" {
  image       = "registry.example.com/org/plugin"
  version     = "v0.0.0"
  sha256sum   = "sha256-checksum"
}

Or it specifies a plugin to automatically register that was manually downloaded:

plugin "type" "name" {
  command     = "plugin-binary-name"
  version     = "v0.0.0"
  env         = ["MY_ENV=value"]
  args        = ["-some-argument"]
}

Multiple plugin blocks may exist and OCI plugins are downloaded in the order they are specified in the configuration file(s). Blocks may share the same type and name but must have different a version. This allows for seamless upgrades of plugin versions.

type must be one of the pre-defined plugin types available in OpenBao, see plugin system for more information.

Parameters

• image (string: required) - OCI artifact/image URL including registry and repository. Conflicts with the command value. One of image or command is required.

• command (string: required) - Command name of the plugin that has been manually downloaded. Conflicts with the image value. One of image or command is required.

• version (string: required) - The (semantic) version of the plugin. When image is set, this doubles as the image tag on the registry.

• sha256sum (string: optional) - Expected SHA-256 digest of the plugin binary. Must be a 64-character hexadecimal string. This is required when image is set, but optional otherwise. When set, OpenBao will revalidate the digest of the plugin binary on disk against what was configured before executing the plugin, though note that the check is subject to a TOCTOU problem.

• args ([]string: optional) - Any arguments to pass to the running plugin.

• env ([]string: optional) - Any environment variables to pass to the running plugin.

• binary_name (string: optional) - Name of the plugin binary file within the OCI image. Only applies when image is set. If unset, OpenBao determines the binary name by reading the OCI image's ENTRYPOINT and CMD metadata (in that order). Plugin images distributed via openbao-plugins always set ENTRYPOINT, so you don't need to set this option.

Example

JSON

{
  "plugin": [
    {
      "secret": {
        "aws": {
          "image": "ghcr.io/openbao/openbao-plugin-secrets-aws",
          "version": "v1.0.0",
          "sha256sum": "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"
        }
      }
    }
  ]
}

HCL

plugin "secret" "aws" {
  image       = "ghcr.io/openbao/openbao-plugin-secrets-aws"
  version     = "v1.0.0"
  sha256sum   = "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"
}

plugin_download_behavior

A string which controls server behavior when plugin downloads fail.

plugin_download_behavior = "fail"

Values

• "fail" (default) - Server startup fails if any plugin download fails
• "warn" - Log warnings for failed downloads but continue startup

plugin_auto_download

A boolean which controls server behavior of whether or not plugins are automatically downloaded on server startup and SIGHUP.

plugin_auto_download = true

Values

• true - server startup and SIGHUP triggers downloading of plugins; can still be manually downloaded with bao plugin init.
• false (default) - only bao plugin init will manually download plugins.

plugin_auto_register

A boolean which controls server behavior of whether or not plugins are automatically registered on server startup and SIGHUP.

plugin_auto_register = true

Values

• true (default) - server startup and SIGHUP triggers registering of plugins; can still be manually registered with bao plugin register.
• false - only bao plugin register will manually register plugins.

plugin_download_max_size

A number defining the maximum allowed plugin binary size in bytes when extracted from an OCI image. Defaults to 536870912 (512 MiB) if not set.

Authentication

When downloading plugin images from a private registry, OpenBao will use credentials as described in the Docker or Podman configuration files present on the system in the following order:

1. ~/.docker/config.json or %USERPROFILE%\.docker\config.json on Windows.
2. A config.json file in the directory specified in the DOCKER_CONFIG environment variable.
3. The path specified by the REGISTRY_AUTH_FILE environment variable.
4. $XDG_RUNTIME_DIR/containers/auth.json

tip

When deploying OpenBao to Kubernetes you can mount an Image Pull Secret into the Pods to use for authentication.

Complete example

storage "raft" {
  path = "/opt/openbao/data"
}

listener "tcp" {
  address = "0.0.0.0:8200"
}

plugin_directory = "/opt/openbao/plugins"
plugin_download_behavior = "fail"

plugin "secret" "aws" {
  image       = "ghcr.io/openbao/openbao-plugin-secrets-aws"
  version     = "v1.0.0"
  sha256sum   = "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"
}

OCI image requirements

OpenBao requires the plugin binary to be present in the image's root directory. It is also advised to make use of a static Go binary to not run into any libc issues.

Example Containerfile

FROM scratch
LABEL org.opencontainers.image.source=https://github.com/openbao/openbao-plugins

COPY bin/openbao-plugin-auth-aws_linux_amd64* openbao-plugin-auth-aws

ENTRYPOINT ["/openbao-plugin-auth-aws"]

Set either ENTRYPOINT or CMD such that binary_name does not need to be configured explicitly when installing the plugin.