HashiCorp Developer AI Private beta now available Sign up today
Vault
Vault Home

You are viewing documentation for version v1.10.x. View latest version.

Annotations

The following are the available annotations for the injector. These annotations are organized into two sections: agent and vault. All of the annotations below change the configurations of the Vault Agent containers injected into the pod.

Agent Annotations

Agent annotations change the Vault Agent containers templating configuration. For example, agent annotations allow users to define what secrets they want, how to render them, optional commands to run, etc.

  • vault.hashicorp.com/agent-inject - configures whether injection is explicitly enabled or disabled for a pod. This should be set to a true or false value. Defaults to false.

  • vault.hashicorp.com/agent-inject-status - blocks further mutations by adding the value injected to the pod after a successful mutation.

  • vault.hashicorp.com/agent-configmap - name of the configuration map where Vault Agent configuration file and templates can be found.

  • vault.hashicorp.com/agent-image - name of the Vault docker image to use. This value overrides the default image configured in the injector and is usually not needed. Defaults to hashicorp/vault:1.10.3.

  • vault.hashicorp.com/agent-init-first - configures the pod to run the Vault Agent init container first if true (last if false). This is useful when other init containers need pre-populated secrets. This should be set to a true or false value. Defaults to false.

  • vault.hashicorp.com/agent-inject-command - configures Vault Agent to run a command after the template has been rendered. To map a command to a specific secret, use the same unique secret name: vault.hashicorp.com/agent-inject-command-SECRET-NAME. For example, if a secret annotation vault.hashicorp.com/agent-inject-secret-foobar is configured, vault.hashicorp.com/agent-inject-command-foobar would map a command to that secret.

  • vault.hashicorp.com/agent-inject-secret - configures Vault Agent to retrieve the secrets from Vault required by the container. The name of the secret is any unique string after vault.hashicorp.com/agent-inject-secret-, such as vault.hashicorp.com/agent-inject-secret-foobar. The value is the path in Vault where the secret is located.

  • vault.hashicorp.com/agent-inject-template - configures the template Vault Agent should use for rendering a secret. The name of the template is any unique string after vault.hashicorp.com/agent-inject-template-, such as vault.hashicorp.com/agent-inject-template-foobar. This should map to the same unique value provided in vault.hashicorp.com/agent-inject-secret-. If not provided, a default generic template is used.

  • vault.hashicorp.com/agent-inject-containers - comma-separated list that specifies in which containers the secrets volume should be mounted. If not provided, the secrets volume will be mounted in all containers in the pod.

  • vault.hashicorp.com/secret-volume-path - configures where on the filesystem a secret will be rendered. To map a path to a specific secret, use the same unique secret name: vault.hashicorp.com/secret-volume-path-SECRET-NAME. For example, if a secret annotation vault.hashicorp.com/agent-inject-secret-foobar is configured, vault.hashicorp.com/secret-volume-path-foobar would configure where that secret is rendered. If no secret name is provided, this sets the default for all rendered secrets in the pod.

  • vault.hashicorp.com/agent-inject-file - configures the filename and path in the secrets volume where a Vault secret will be written. This should be used with vault.hashicorp.com/secret-volume-path, which mounts a memory volume to the specified path. If secret-volume-path is used, the path can be omitted from this value. To map a filename to a specific secret, use the same unique secret name: vault.hashicorp.com/agent-inject-file-SECRET-NAME. For example, if a secret annotation vault.hashicorp.com/agent-inject-secret-foobar is configured, vault.hashicorp.com/agent-inject-file-foobar would configure the filename.

  • vault.hashicorp.com/agent-inject-perms - configures the permissions of the file to create in the secrets volume. The name of the secret is the string after "vault.hashicorp.com/agent-inject-perms-", and should map to the same unique value provided in "vault.hashicorp.com/agent-inject-secret-". The value is the octal permission, for example: 0644.

  • vault.hashicorp.com/agent-inject-template-file - configures the path and filename of the custom template to use. This should be used with vault.hashicorp.com/extra-secret, which mounts a Kubernetes secret to /vault/custom. To map a template file to a specific secret, use the same unique secret name: vault.hashicorp.com/agent-inject-template-file-SECRET-NAME. For example, if a secret annotation vault.hashicorp.com/agent-inject-secret-foobar is configured, vault.hashicorp.com/agent-inject-template-file-foobar would configure the template file.

  • vault.hashicorp.com/agent-inject-default-template - configures the default template type for rendering secrets if no custom template is defined. Possible values include map and json. Defaults to map.

  • vault.hashicorp.com/template-config-exit-on-retry-failure - controls whether Vault Agent exits after it has exhausted its number of template retry attempts due to failures. Defaults to true. See Vault Agent Template Config for more details.

  • vault.hashicorp.com/template-static-secret-render-interval - If specified, configures how often Vault Agent Template should render non-leased secrets such as KV v2. See Vault Agent Template Config for more details.

  • vault.hashicorp.com/agent-extra-secret - mounts Kubernetes secret as a volume at /vault/custom in the sidecar/init containers. Useful for custom Agent configs with auto-auth methods such as approle that require paths to secrets be present.

  • vault.hashicorp.com/agent-inject-token - configures Vault Agent to share the Vault token with other containers in the pod, in a file named token in the root of the secrets volume (i.e. /vault/secrets/token). This is helpful when other containers communicate directly with Vault but require auto-authentication provided by Vault Agent. This should be set to a true or false value. Defaults to false.

  • vault.hashicorp.com/agent-limits-cpu - configures the CPU limits on the Vault Agent containers. Defaults to 500m. Setting this to an empty string disables CPU limits.

  • vault.hashicorp.com/agent-limits-mem - configures the memory limits on the Vault Agent containers. Defaults to 128Mi. Setting this to an empty string disables memory limits.

  • vault.hashicorp.com/agent-requests-cpu - configures the CPU requests on the Vault Agent containers. Defaults to 250m. Setting this to an empty string disables CPU requests.

  • vault.hashicorp.com/agent-requests-mem - configures the memory requests on the Vault Agent containers. Defaults to 64Mi. Setting this to an empty string disables memory requests.

  • vault.hashicorp.com/agent-revoke-on-shutdown - configures whether the sidecar will revoke it's own token before shutting down. This setting will only be applied to the Vault Agent sidecar container. This should be set to a true or false value. Defaults to false.

  • vault.hashicorp.com/agent-revoke-grace - configures the grace period, in seconds, for revoking it's own token before shutting down. This setting will only be applied to the Vault Agent sidecar container. Defaults to 5s.

  • vault.hashicorp.com/agent-pre-populate - configures whether an init container is included to pre-populate the shared memory volume with secrets prior to the containers starting.

  • vault.hashicorp.com/agent-pre-populate-only - configures whether an init container is the only injected container. If true, no sidecar container will be injected at runtime of the pod. Enabling this option is recommended for workloads of type CronJob or Job to ensure a clean pod termination.

  • vault.hashicorp.com/preserve-secret-case - configures Vault Agent to preserve the secret name case when creating the secret files. This should be set to a true or false value. Defaults to false.

  • vault.hashicorp.com/agent-run-as-user - sets the user (uid) to run Vault agent as. Also available as a command-line option (-run-as-user) or environment variable (AGENT_INJECT_RUN_AS_USER) for the injector. Defaults to 100.

  • vault.hashicorp.com/agent-run-as-group - sets the group (gid) to run Vault agent as. Also available as a command-line option (-run-as-group) or environment variable (AGENT_INJECT_RUN_AS_GROUP) for the injector. Defaults to 1000.

  • vault.hashicorp.com/agent-set-security-context - controls whether SecurityContext is set in injected containers. Also available as a command-line option (-set-security-context) or environment variable (AGENT_INJECT_SET_SECURITY_CONTEXT). Defaults to true.

  • vault.hashicorp.com/agent-run-as-same-user - run the injected Vault agent containers as the User (uid) of the first application container in the pod. Requires Spec.Containers[0].SecurityContext.RunAsUser to be set in the pod spec. Also available as a command-line option (-run-as-same-user) or environment variable (AGENT_INJECT_RUN_AS_SAME_USER). Defaults to false.

    Note: If the first application container in the pod is running as root (uid 0), the run-as-same-user annotation will fail injection with an error.

  • vault.hashicorp.com/agent-cache-enable - configures Vault Agent to enable caching. In Vault 1.7+ this annotation will also enable a Vault Agent persistent cache. This persistent cache will be shared between the init and sidecar container to reuse tokens and leases retrieved by the init container. Defaults to false.

  • vault.hashicorp.com/agent-cache-use-auto-auth-token - configures Vault Agent cache to authenticate on behalf of the requester. Set to force to enable. Disabled by default.

  • vault.hashicorp.com/agent-cache-listener-port - configures Vault Agent cache listening port. Defaults to 8200.

  • vault.hashicorp.com/agent-copy-volume-mounts - copies the mounts from the specified container and mounts them to the Vault Agent containers. The service account volume is ignored.

  • vault.hashicorp.com/agent-service-account-token-volume-name - the optional name of a projected volume containing a service account token for use with auto-auth against Vault's Kubernetes auth method. If the volume is mounted to another container in the deployment, the token volume will be mounted to the same location in the vault-agent containers. Otherwise it will be mounted at the default location of /var/run/secrets/vault.hashicorp.com/serviceaccount/.

  • vault.hashicorp.com/agent-enable-quit - enable the /agent/v1/quit endpoint on an injected agent. This option defaults to false, and if true will be set on the existing cache listener, or a new localhost listener with a basic cache stanza configured. The agent-cache-listener-port annotation can be used to change the port.

  • vault.hashicorp.com/go-max-procs - set the GOMAXPROCS environment variable for injected agents

Vault Annotations

Vault annotations change how the Vault Agent containers communicate with Vault. For example, Vault's address, TLS certificates to use, client parameters such as timeouts, etc.