Skip to main content

OCI plugins

OpenBao supports the distribution of plugins in Open Container Initiative (OCI) images. 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 images 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.
  • Integrity Verification: When extracting plugin binaries from OCI images OpenBao ensures the SHA256 sum of the extracted binary is the same as in the configuration files.
  • 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"
  binary_name = "plugin-binary-name"
  sha256sum   = "sha256-checksum"
}

Multiple plugin blocks may exist and 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.

Parameters​

  • image (string: required) - OCI image URL including registry and repository.

  • version (string: required) - The image version or tag.

  • binary_name (string: required) - Name of the plugin binary file within the OCI image.

  • sha256sum (string: required) - Expected SHA256 checksum of the plugin binary. Must be a 64-character hexadecimal string.

Example​

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

plugin_download_behavior​

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

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"
  binary_name = "openbao-plugin-secrets-aws"
  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"]