1--- 2layout: docs 3page_title: Agent Sidecar Injector Overview 4description: >- 5 The Vault Agent Sidecar Injector is a Kubernetes admission webhook that adds 6 Vault Agent containers to pods for consuming Vault secrets. 7--- 8 9# Agent Sidecar Injector 10 11The Vault Agent Injector alters pod specifications to include Vault Agent 12containers that render Vault secrets to a shared memory volume using 13[Vault Agent Templates](/docs/agent/template). 14By rendering secrets to a shared volume, containers within the pod can consume 15Vault secrets without being Vault aware. 16 17The injector is a [Kubernetes Mutation Webhook Controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/). 18The controller intercepts pod events and applies mutations to the pod if annotations exist within 19the request. This functionality is provided by the [vault-k8s](https://github.com/hashicorp/vault-k8s) 20project and can be automatically installed and configured using the 21[Vault Helm](https://github.com/hashicorp/vault-helm) chart. 22 23## Overview 24 25The Vault Agent Injector works by intercepting pod `CREATE` and `UPDATE` 26events in Kubernetes. The controller parses the event and looks for the metadata 27annotation `vault.hashicorp.com/agent-inject: true`. If found, the controller will 28alter the pod specification based on other annotations present. 29 30### Mutations 31 32At a minimum, every container in the pod will be configured to mount a shared 33memory volume. This volume is mounted to `/vault/secrets` and will be used by the Vault 34Agent containers for sharing secrets with the other containers in the pod. 35 36Next, two types of Vault Agent containers can be injected: init and sidecar. The 37init container will prepopulate the shared memory volume with the requested 38secrets prior to the other containers starting. The sidecar container will 39continue to authenticate and render secrets to the same location as the pod runs. 40Using annotations, the initialization and sidecar containers may be disabled. 41 42Last, two additional types of volumes can be optionally mounted to the Vault Agent 43containers. The first is secret volume containing TLS requirements such as client 44and CA (certificate authority) certificates and keys. This volume is useful when 45communicating and verifying the Vault server's authenticity using TLS. The second 46is a configuration map containing Vault Agent configuration files. This volume is 47useful to customize Vault Agent beyond what the provided annotations offer. 48 49### Authenticating with Vault 50 51The primary method of authentication with Vault when using the Vault Agent Injector 52is the service account attached to the pod. Other authentication methods can be configured 53using annotations. 54 55For Kubernetes authentication, the service account must be bound to a Vault role and a 56policy granting access to the secrets desired. 57 58A service account must be present to use the Vault Agent Injector with the Kubernetes 59authentication method. It is _not_ recommended to bind Vault roles to the default service 60account provided to pods if no service account is defined. 61 62### Requesting Secrets 63 64There are two methods of configuring the Vault Agent containers to render secrets: 65 66- the `vault.hashicorp.com/agent-inject-secret` annotation, or 67- a configuration map containing Vault Agent configuration files. 68 69Only one of these methods may be used at any time. 70 71#### Secrets via Annotations 72 73To configure secret injection using annotations, the user must supply: 74 75- one or more _secret_ annotations, and 76- the Vault role used to access those secrets. 77 78The annotation must have the format: 79 80```yaml 81vault.hashicorp.com/agent-inject-secret-<unique-name>: /path/to/secret 82``` 83 84The unique name will be the filename of the rendered secret and must be unique if 85multiple secrets are defined by the user. For example, consider the following 86secret annotations: 87 88```yaml 89vault.hashicorp.com/agent-inject-secret-foo: database/roles/app 90vault.hashicorp.com/agent-inject-secret-bar: consul/creds/app 91vault.hashicorp.com/role: 'app' 92``` 93 94The first annotation will be rendered to `/vault/secrets/foo` and the second 95annotation will be rendered to `/vault/secrets/bar`. 96 97It's possible to set the file format of the rendered secret using the annotation. For example the 98following secret will be rendered to `/vault/secrets/foo.txt`: 99 100```yaml 101vault.hashicorp.com/agent-inject-secret-foo.txt: database/roles/app 102vault.hashicorp.com/role: 'app' 103``` 104 105The secret unique name must consist of alphanumeric characters, `.`, `_` or `-`. 106 107##### Secret Templates 108 109~> Vault Agent uses the Consul Template project to render secrets. For more information 110on writing templates, see the [Consul Template documentation](https://github.com/hashicorp/consul-template). 111 112How the secret is rendered to the file is also configurable. To configure the template 113used, the user must supply a _template_ annotation using the same unique name of 114the secret. The annotation must have the following format: 115 116```yaml 117vault.hashicorp.com/agent-inject-template-<unique-name>: | 118 < 119 TEMPLATE 120 HERE 121 > 122``` 123 124For example, consider the following: 125 126```yaml 127vault.hashicorp.com/agent-inject-secret-foo: 'database/roles/app' 128vault.hashicorp.com/agent-inject-template-foo: | 129 {{- with secret "database/creds/db-app" -}} 130 postgres://{{ .Data.username }}:{{ .Data.password }}@postgres:5432/mydb?sslmode=disable 131 {{- end }} 132vault.hashicorp.com/role: 'app' 133``` 134 135The rendered secret would look like this within the container: 136 137```shell-session 138$ cat /vault/secrets/foo 139postgres://v-kubernet-pg-app-q0Z7WPfVN:A1a-BUEuQR52oAqPrP1J@postgres:5432/mydb?sslmode=disable 140``` 141 142~> The default left and right template delimiters are `{{` and `}}`. 143 144If no template is provided the following generic template is used: 145 146``` 147{{ with secret "/path/to/secret" }} 148 {{ range $k, $v := .Data }} 149 {{ $k }}: {{ $v }} 150 {{ end }} 151{{ end }} 152``` 153 154For example, the following annotation will use the default template to render 155PostgreSQL secrets found at the configured path: 156 157```yaml 158vault.hashicorp.com/agent-inject-secret-foo: 'database/roles/pg-app' 159vault.hashicorp.com/role: 'app' 160``` 161 162The rendered secret would look like this within the container: 163 164```shell-session 165$ cat /vault/secrets/foo 166password: A1a-BUEuQR52oAqPrP1J 167username: v-kubernet-pg-app-q0Z7WPfVNqqTJuoDqCTY-1576529094 168``` 169 170~> Some secrets such as KV are stored in maps. Their data can be accessed using `.Data.data.<NAME>` 171 172### Renewals and Updating Secrets 173 174For more information on when Vault Agent fetches and renews secrets, see the 175[Agent documentation](/docs/agent/template#renewals-and-updating-secrets). 176 177### Vault Agent Configuration Map 178 179For advanced use cases, it may be required to define Vault Agent configuration 180files to mount instead of using secret and template annotations. The Vault Agent 181Injector supports mounting ConfigMaps by specifying the name using the `vault.hashicorp.com/agent-configmap` 182annotation. The configuration files will be mounted to `/vault/configs`. 183 184The configuration map must contain either one or both of the following files: 185 186- **config-init.hcl** used by the init container. This must have `exit_after_auth` set to `true`. 187- **config.hcl** used by the sidecar container. This must have `exit_after_auth` set to `false`. 188 189An example of mounting a Vault Agent configmap [can be found here](/docs/platform/k8s/injector/examples#configmap-example). 190 191## Learn 192 193Refer to the [Injecting Secrets into Kubernetes Pods via Vault Helm 194Sidecar](https://learn.hashicorp.com/vault/getting-started-k8s/sidecar) guide 195for a step-by-step tutorial. 196