Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update agent template certificate section #16573

Merged
merged 3 commits into from
Aug 10, 2022
Merged

docs: update agent template certificate section #16573

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1b02556
docs: update agent template certificate section
calvn Aug 4, 2022
eebab4d
extend template language section
calvn Aug 8, 2022
b458a63
make recommendation to use pkiCert over secret
calvn Aug 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 47 additions & 14 deletions website/content/docs/agent/template.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,29 @@ The template output content can be provided directly as part of the `contents`
option in a `template` stanza or as a separate `.ctmpl` file and specified in
the `source` option of a `template` stanza.

In order to fetch secrets from Vault, whether those are static secrets, dynamic
credentials, or certificates, Vault Agent templates require the use of the
`secret`
[function](https://github.com/hashicorp/consul-template/blob/master/docs/templating-language.md#secret)
or `pkiCert`
[function](https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md#pkicert)
from Consul Template.

The `secret` function works for all types of secrets and depending on the type
of secret that's being rendered by this function, template will have different
renewal behavior as detailed in the [Renewals
section](#renewals-and-updating-secrets). The `pkiCert` function is intended to
work specifically for certificates issued by the [PKI Secrets
Engine](/docs/secrets/pki). Refer to the [Certificates](#certificates) section
for differences in certificate renewal behavior between `secret` and `pkiCert`.

The following links contain additional resources for the templating language used by Vault Agent templating.

- [Consul Templating Documentation][consul-templating-language]
- [Go Templating Language Documentation](https://pkg.go.dev/text/template#pkg-overview)

### Template Language Example

Template with Vault Agent requires the use of the `secret` [function](https://github.com/hashicorp/consul-template/blob/master/docs/templating-language.md#secret)
or `pkiCert` [function](https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md#pkicert)
from Consul Template.

The following is an example of a template that retrieves a generic secret from Vault's
KV store:
```
Expand Down Expand Up @@ -226,16 +238,37 @@ this by inspecting the secret's time-to-live (TTL).

### Certificates

If a secret is a [certificate](/docs/secrets/pki), Vault Agent template will fetch the new certificate
using the certificates `validTo` field.

This does not apply to certificates generated with `generate_lease: true`. If set
Vault Agent template will apply the non-renewable, leased secret rules.

-> **Note** When Agent's auto-auth re-authenticates, due to a token expiry for
example, it generates a new token for Agent's use. This triggers a template
server restart, which fetches and re-renders a new set of certificates even if
existing certificates are valid.
As of Vault 1.11, certificates can be rendered using either `pkiCert` or
`secret` template functions, although it is recommended to use `pkiCert` to
avoid unnecessarily generating certificates whenever Agent restarts or
re-authenticates.

#### Rendering using the `pkiCert` template function
calvn marked this conversation as resolved.
Show resolved Hide resolved

If a [certificate](/docs/secrets/pki) is rendered using the `pkiCert` template
function, Vault Agent template will have the following fetching and re-rendering
behaviors on certificates:

- Fetches a new certificate on Agent startup if none has been previously
rendered or the current rendered one has expired.
- On Agent's auto-auth re-authentication, due to a token expiry for example,
skip fetching unless the current rendered one has expired.

#### Rendering using the `secret` template function

If a [certificate](/docs/secrets/pki) is rendered using the `secret` template
function, Vault Agent template will have the following fetching and re-rendering
behaviors on certificates:

- Fetches a new certificate on Agent startup, even if previously rendered
certificates are still valid.
- If `generate_lease` is unset or set to `false`, it uses the certificate's
`validTo` field to determine re-fetch interval.
- If `generate_lease` is set to `true`, apply the non-renewable, leased secret
rules.
- On Agent's auto-auth re-authentication, due to a token expiry for example, it
fetches and re-renders a new certificate even if the existing certificate is
valid.

## Templating Configuration Example

Expand Down