Skip to main content

OpenBao agent's process supervisor mode

OpenBao Agent's Process Supervisor Mode allows OpenBao secrets to be injected into a process via environment variables using Consul Template markup.

info

If you are running your applications in a Kubernetes cluster, we recommend evaluating the OpenBao Secrets Operator and the OpenBao Agent Sidecar Injector.

danger

OpenBao Agent's Process Supervisor Mode is in public beta. Please provide your feedback by opening a GitHub issue here.

Functionality​

OpenBao Agent will inject secrets referenced in the env_template configuration blocks as environment variables into the child process specified in the exec block.

When you start OpenBao Agent in process supervisor mode, it will wait until each environment variable template has rendered at least once before starting the process. If restart_on_secret_changes is set to always (default), Agent will restart the process whenever an update to an injected secret is detected. This could be either a static secret update (done on static_secret_render_interval) or dynamic secret being close to its expiration.

In many ways, OpenBao Agent will mirror the child process. Standard intput and output streams (stdin / stdout / stderr) are all forwarded to the child process. Additionally, OpenBao Agent will exit when the child process exits on its own with the same exit code.

Configuration​

info

Agent's generate-config tool will help you get started by generating a valid agent configuration file from the given inputs.

The process supervisor mode requires at least one env_template block and exactly one top level exec block. It is incompatible with regular file template entries.

env_template​

env_template stanza maps the template specified in the contents field or referenced in the source field to the environment variable name in the title of the stanza. It uses the same templating language as file templates but permits only a subset of its configuration parameters:

  • environment variable name (string: <required>) - the name of the environment variable to which the contents of the template should map.

  • contents (string: "") - This option allows embedding the contents of a template in the configuration file rather then supplying the source path to the template file. This is useful for short templates. This option is mutually exclusive with the source option.

  • source (string: "") - Path on disk to use as the input template. This option is required if not using the contents option.

  • error_on_missing_key (bool: false) - Exit with an error when accessing a struct or map field/key that does notexist. The default behavior will print <no value> when accessing a field that does not exist. It is highly recommended you set this to "true". Also see exit_on_retry_failure in global OpenBao Agent Template Config.

  • left_delimiter (string: "\{\{") - Delimiter to use in the template. The default is "{{" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself.

  • right_delimiter (string: "}}") - Delimiter to use in the template. The default is "}}" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself.

exec​

The top level exec block has the following configuration entries.

  • command (string array: required) - Specify the command for the child process with optional arguments. The executable's path must be either absolute or relative to the current working directory.

  • restart_on_secret_changes (string: "always") - Controls whether agent will restart the child process on secret changes. There are two types of secret changes relevant to this configuration: a static secret update (on [static_secret_render_interval](/docs/agent-and-proxy/agent/template#static_secret_render_interval)) and dynamic secret being close to its expiration. The configuration supports two options: alwaysandnever`.

  • restart_stop_signal (string: "SIGTERM") - Signal to send to the child process when a secret has been updated and the process needs to be restarted. The process has 30 seconds after this signal is sent until SIGKILL is sent to force the child process to stop.

Configuration example​

The following example was generated using bao agent generate-config, a configuration helper tool. Given this configuration, OpenBao Agent will run the child process (./my-app arg1 arg2) with two additional environment variables (FOO_USER and FOO_PASSWORD) populated with secrets from OpenBao.

auto_auth {

  method {
    type = "token_file"

    config {
      token_file_path = "/Users/avean/.vault-token"
    }
  }
}

template_config {
  static_secret_render_interval = "5m"
  exit_on_retry_failure         = true
}

vault {
  address = "http://localhost:8200"
}

env_template "FOO_PASSWORD" {
  contents             = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.password }}{{ end }}"
  error_on_missing_key = true
}
env_template "FOO_USER" {
  contents             = "{{ with secret \"secret/data/foo\" }}{{ .Data.data.user }}{{ end }}"
  error_on_missing_key = true
}

exec {
  command                   = ["./my-app", "arg1", "arg2"]
  restart_on_secret_changes = "always"
  restart_stop_signal       = "SIGTERM"
}