Skip to main content

Agent sidecar injector

The OpenBao Agent Injector alters pod specifications to include OpenBao Agent containers that render OpenBao secrets to a shared memory volume using OpenBao Agent Templates. By rendering secrets to a shared volume, containers within the pod can consume OpenBao secrets without being OpenBao aware.

The injector is a Kubernetes Mutation Webhook Controller. The controller intercepts pod events and applies mutations to the pod if annotations exist within the request. This functionality is provided by the openbao-k8s project and can be automatically installed and configured using the OpenBao Helm chart.

Supported kubernetes versions​

The following Kubernetes minor releases are currently supported. The latest version is tested against each Kubernetes version. It may work with other versions of Kubernetes, but those are not supported.

  • = 1.27

Overview​

The OpenBao Agent Injector works by intercepting pod CREATE and UPDATE events in Kubernetes. The controller parses the event and looks for the metadata annotation openbao.openbao.com/agent-inject: true. If found, the controller will alter the pod specification based on other annotations present.

Mutations​

At a minimum, every container in the pod will be configured to mount a shared memory volume. This volume is mounted to /openbao/secrets and will be used by the OpenBao Agent containers for sharing secrets with the other containers in the pod.

Next, two types of OpenBao Agent containers can be injected: init and sidecar. The init container will prepopulate the shared memory volume with the requested secrets prior to the other containers starting. The sidecar container will continue to authenticate and render secrets to the same location as the pod runs. Using annotations, the initialization and sidecar containers may be disabled.

Last, two additional types of volumes can be optionally mounted to the OpenBao Agent containers. The first is secret volume containing TLS requirements such as client and CA (certificate authority) certificates and keys. This volume is useful when communicating and verifying the OpenBao server's authenticity using TLS. The second is a configuration map containing OpenBao Agent configuration files. This volume is useful to customize OpenBao Agent beyond what the provided annotations offer.

Authenticating with OpenBao​

The primary method of authentication with OpenBao when using the OpenBao Agent Injector is the service account attached to the pod. Other authentication methods can be configured using annotations.

For Kubernetes authentication, the service account must be bound to a OpenBao role and a policy granting access to the secrets desired.

A service account must be present to use the OpenBao Agent Injector with the Kubernetes authentication method. It is not recommended to bind OpenBao roles to the default service account provided to pods if no service account is defined.

Requesting secrets​

There are two methods of configuring the OpenBao Agent containers to render secrets:

  • the openbao.openbao.com/agent-inject-secret annotation, or
  • a configuration map containing OpenBao Agent configuration files.

Only one of these methods may be used at any time.

Secrets via annotations​

To configure secret injection using annotations, the user must supply:

  • one or more secret annotations, and
  • the OpenBao role used to access those secrets.

The annotation must have the format:

openbao.openbao.com/agent-inject-secret-<unique-name>: /path/to/secret

The unique name will be the filename of the rendered secret and must be unique if multiple secrets are defined by the user. For example, consider the following secret annotations:

openbao.openbao.com/agent-inject-secret-foo: database/roles/app
openbao.openbao.com/agent-inject-secret-bar: consul/creds/app
openbao.openbao.com/role: 'app'

The first annotation will be rendered to /openbao/secrets/foo and the second annotation will be rendered to /openbao/secrets/bar.

It's possible to set the file format of the rendered secret using the annotation. For example the following secret will be rendered to /openbao/secrets/foo.txt:

openbao.openbao.com/agent-inject-secret-foo.txt: database/roles/app
openbao.openbao.com/role: 'app'

The secret unique name must consist of alphanumeric characters, ., _ or -.

Secret templates​
warning

OpenBao Agent uses the OpenBao Template project to render secrets. For more information on writing templates, see the OpenBao Template documentation.

How the secret is rendered to the file is also configurable. To configure the template used, the user must supply a template annotation using the same unique name of the secret. The annotation must have the following format:

openbao.openbao.com/agent-inject-template-<unique-name>: |
  <
    TEMPLATE
    HERE
  >

For example, consider the following:

openbao.openbao.com/agent-inject-secret-foo: 'database/creds/db-app'
openbao.openbao.com/agent-inject-template-foo: |
  {{- with secret "database/creds/db-app" -}}
  postgres://{{ .Data.username }}:{{ .Data.password }}@postgres:5432/mydb?sslmode=disable
  {{- end }}
openbao.openbao.com/role: 'app'

The rendered secret would look like this within the container:

$ cat /openbao/secrets/foo
postgres://v-kubernet-pg-app-q0Z7WPfVN:A1a-BUEuQR52oAqPrP1J@postgres:5432/mydb?sslmode=disable
warning

The default left and right template delimiters are {{ and }}.

If no template is provided the following generic template is used:

{{ with secret "/path/to/secret" }}
    {{ range $k, $v := .Data }}
        {{ $k }}: {{ $v }}
    {{ end }}
{{ end }}

For example, the following annotation will use the default template to render PostgreSQL secrets found at the configured path:

openbao.openbao.com/agent-inject-secret-foo: 'database/roles/pg-app'
openbao.openbao.com/role: 'app'

The rendered secret would look like this within the container:

$ cat /openbao/secrets/foo
password: A1a-BUEuQR52oAqPrP1J
username: v-kubernet-pg-app-q0Z7WPfVNqqTJuoDqCTY-1576529094
warning

Some secrets such as KV are stored in maps. Their data can be accessed using .Data.data.<NAME>

Renewals and updating secrets​

For more information on when OpenBao Agent fetches and renews secrets, see the Agent documentation.

OpenBao agent configuration map​

For advanced use cases, it may be required to define OpenBao Agent configuration files to mount instead of using secret and template annotations. The OpenBao Agent Injector supports mounting ConfigMaps by specifying the name using the openbao.openbao.com/agent-configmap annotation. The configuration files will be mounted to /openbao/configs.

The configuration map must contain either one or both of the following files:

  • config-init.hcl used by the init container. This must have exit_after_auth set to true.
  • config.hcl used by the sidecar container. This must have exit_after_auth set to false.

An example of mounting a OpenBao Agent configmap can be found here.