Skip to content

Commit

Permalink
docs: Consul Workload Identity integration (#18685)
Browse files Browse the repository at this point in the history
Documentation updates to support the new Consul integration with Nomad Workload
Identity. Included:

* Added a large section to the Consul integration docs to explain how to set up
  auth methods and binding rules (by hand, assuming we don't ship a `nomad
  setup-consul` tool for now), and how to safely migrate from the existing
  workflow to the new one.
* Move `consul` block out of `group` and onto its own page now that we have it
  available at the `task` scope, and expanded examples of its use.
* Added the `service_identity` and `task_identity` blocks to the Nomad agent
  configuration, and provided a recommended default.
* Added the `identity` block to the `service` block page.
* Added a rough compatibility matrix to the Consul integration page.
  • Loading branch information
tgross authored Oct 23, 2023
1 parent 4d9cc73 commit 8a31125
Show file tree
Hide file tree
Showing 7 changed files with 596 additions and 74 deletions.
52 changes: 51 additions & 1 deletion website/content/docs/configuration/consul.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,15 @@ value for the [`name`](#name) field.
Consul service name defined in the `server_service_name` option. This search
only happens if the server does not have a leader.

- `service_auth_method` `(string: "nomad-workloads")` - Specifies the name of the
Consul [authentication method][auth-method] that will be used to login with a
Nomad JWT for services.

- `service_identity` <code>([Identity][identity_block]: nil)</code> - Specifies
a default Workload Identity to use when obtaining Service Identity tokens from
Consul to register services. Refer to [Workload Identity](#workload-identity)
for a recommended configuration.

- `share_ssl` `(bool: true)` - Specifies whether the Nomad client should share
its Consul SSL configuration with Connect Native applications. Includes values
of `ca_file`, `cert_file`, `key_file`, `ssl`, and `verify_ssl`. Does not include
Expand All @@ -144,6 +153,15 @@ value for the [`name`](#name) field.
- `tags` `(array<string>: [])` - Specifies optional Consul tags to be
registered with the Nomad server and agent services.

- `task_auth_method` `(string: "nomad-tasks")` - Specifies the name of the
Consul [authentication method][auth-method] that will be used to login with a
Nomad JWT for tasks.

- `task_identity` <code>([Identity][identity_block]: nil)</code> - Specifies a
default Workload Identity to use when obtaining Consul tokens from Consul to
support [`template`][] blocks. Refer to [Workload
Identity](#workload-identity) for a recommended configuration.

- `timeout` `(string: "5s")` - Specifies a time limit for requests made against
Consul. This is specified using a label suffix like "10s".

Expand Down Expand Up @@ -179,6 +197,33 @@ consul {
}
```

### Workload Identity

The `service_identity` and `task_identity` blocks accept all the same values as
the job specification's [`identity`][identity_block]. By ensuring these blocks
are set on the Nomad servers, you can automatically migrate your existing jobs
to use Workload Identity without modifying the job specification and
resubmitting them.

The recommended configuration for `service_identity` and `task_identity` is as
follows. See [Migrating to Using Workload Identity with Consul][] for details on
how to configure Consul to accept these identities. Note that the `ttl` field
here refers to the TTL of the Nomad identity and not the Consul token.

```hcl
consul {
service_identity {
aud = ["consul.io"]
ttl = "1h"
}
task_identity {
aud = ["consul.io"]
ttl = "1h"
}
}
```

### Custom Address and Port

This example shows pointing the Nomad agent at a different Consul address. Note
Expand Down Expand Up @@ -217,7 +262,7 @@ as a `namespace` block with the other relevant permissions for running Nomad
in the intended namespace. The Consul policy below shows an example policy
configuration for a Nomad server:

```
```hcl
agent_prefix "" {
policy = "read"
}
Expand All @@ -239,10 +284,15 @@ namespace "nomad-ns" {
}
```


[consul]: https://www.consul.io/ 'Consul by HashiCorp'
[bootstrap]: /nomad/tutorials/manage-clusters/clustering 'Automatic Bootstrapping'
[go-sockaddr/template]: https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template
[grpc_port]: /consul/docs/agent/config/config-files#grpc_port
[grpctls_port]: /consul/docs/agent/config/config-files#grpc_tls_port
[`consul.cluster`]: /nomad/docs/job-specification/group#cluster
[`service.cluster`]: /nomad/docs/job-specification/service#cluster
[identity_block]: /nomad/docs/job-specification/identity
[`template`]: /nomad/docs/job-specification/template
[Migrating to Using Workload Identity with Consul]: /nomad/docs/integrations/consul-integration#migrating-to-using-workload-identity-with-consul
[auth-method]: /consul/docs/security/acl/auth-methods/jwt
Loading

0 comments on commit 8a31125

Please sign in to comment.