Skip to content

Commit

Permalink
Backport docs: keyring support prepublishing keys
Browse files Browse the repository at this point in the history
Backports required documentation bits from #23577 because the PR was only
automatically backported to the 1.7.x+ent branch.
  • Loading branch information
tgross committed Jul 19, 2024
1 parent fc3cf09 commit 350bb61
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 14 deletions.
31 changes: 23 additions & 8 deletions website/content/docs/commands/operator/root/keyring-rotate.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,34 @@ nomad operator root keyring rotate [options]
## Rotate Options

- `-full`: Decrypt all existing variables and re-encrypt with the new key. This
command will immediately return and the re-encryption process will run
asynchronously on the leader.
command will immediately return and the re-encryption process will run
asynchronously on the leader.

- `-now`: Publish the new key immediately without prepublishing. One of `-now`
or `-prepublish` must be set.

- `-prepublish`: Set a duration for which to prepublish the new key
(ex. "1h"). The currently active key will be unchanged but the new public key
will be available in the JWKS endpoint. Multiple keys can be prepublished and
they will be promoted to active in order of publish time, at most once every
[`root_key_gc_interval`][]. One of `-now` or `-prepublish` must be set.

- `-verbose`: Enable verbose output

## Examples

```shell-session
$ nomad operator root keyring rotate
Key State Create Time
f19f6029 active 2022-07-11T19:14:36Z
$ nomad operator root keyring rotate -now
Key State Create Time Publish Time
f19f6029 active 2022-07-11T19:14:36Z <none>
$ nomad operator root keyring rotate -verbose
Key State Create Time
53186ac1-9002-c4b6-216d-bb19fd37a791 active 2022-07-11T19:14:47Z
$ nomad operator root keyring rotate -now -verbose
Key State Create Time Publish Time
53186ac1-9002-c4b6-216d-bb19fd37a791 active 2022-07-11T19:14:47Z <none>
$ nomad operator root keyring rotate -prepublish 1h
Key State Create Time Publish Time
7f15e4e9 active 2022-07-11T19:15:10Z 2022-07-11T20:15:10Z
```

[`root_key_gc_interval`]: /nomad/docs/configuration/server#root_key_gc_interval
16 changes: 10 additions & 6 deletions website/content/docs/configuration/server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -238,13 +238,16 @@ server {
- `root_key_gc_interval` `(string: "10m")` - Specifies the interval between
[encryption key][] metadata garbage collections.

- `root_key_gc_threshold` `(string: "1h")` - Specifies the minimum time that an
[encryption key][] must exist before it can be eligible for garbage
collection.
- `root_key_gc_threshold` `(string: "1h")` - Specifies the minimum time after
the `root_key_rotation_threshold` has passed that an [encryption key][] must
exist before it can be eligible for garbage collection.

- `root_key_rotation_threshold` `(string: "720h")` - Specifies the minimum time
that an [encryption key][] must exist before it is automatically rotated on
the next garbage collection interval.
- `root_key_rotation_threshold` `(string: "720h")` - Specifies the lifetime of
an active [encryption key][] before it is automatically rotated on the next
garbage collection interval. Nomad will prepublish the replacement key at half
the `root_key_rotation_threshold` time so external consumers of Workload
Identity have time to obtain the new public key from the [JWKS URL][] before
it is used.

- `server_join` <code>([server_join][server-join]: nil)</code> - Specifies
how the Nomad server will connect to other Nomad servers. The `retry_join`
Expand Down Expand Up @@ -519,3 +522,4 @@ work.
[wi]: /nomad/docs/concepts/workload-identity
[Configure for multiple regions]: /nomad/tutorials/access-control/access-control-bootstrap#configure-for-multiple-regions
[top_level_data_dir]: /nomad/docs/configuration#data_dir
[JWKS URL]: /nomad/api-docs/operator/keyring#list-active-public-keys

0 comments on commit 350bb61

Please sign in to comment.