From 5b1ad83d828f81d849530316411197041f9e5cc6 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 29 Oct 2024 14:02:04 -0500 Subject: [PATCH] Docs: Add IPv6 support page (#24228) * initial content from Daniel's doc * Add IPv6 support doc to operations section. * daniel obsessively re-refactors his docs * Style guide edits * a few more style nits --------- Co-authored-by: Daniel Bennett --- .../content/docs/operations/ipv6-support.mdx | 145 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 2 files changed, 149 insertions(+) create mode 100644 website/content/docs/operations/ipv6-support.mdx diff --git a/website/content/docs/operations/ipv6-support.mdx b/website/content/docs/operations/ipv6-support.mdx new file mode 100644 index 00000000000..c13a9dc6d0a --- /dev/null +++ b/website/content/docs/operations/ipv6-support.mdx @@ -0,0 +1,145 @@ +--- +layout: docs +page_title: Support for IPv6 +description: |- + Nomad support for IPv6 +--- + +# IPv6 support in Nomad + +Nomad supports IPv6 as long as the underlying networks, host machines, +and operating systems running it support IPv6. + +This guide illustrates the different configuration settings you need for different connection contexts. + +## Advertise + +[Advertise][advertise] Nomad server and client addresses to specify what +address other servers, clients, or external systems should use to make +connections back to the agent. + +You can use [go-sockaddr][] templating to dynamically select a public IPv6 +address. In this example, for each protocol, fetch one IPv6 address from public +interfaces and assign it as the protocol's address. + +```hcl +advertise { + http = "{{ GetPublicInterfaces | include \"type\" \"IPv6\" \ + | limit 1 | attr \"address\" }}" + rpc = "{{ GetPublicInterfaces | include \"type\" \"IPv6\" \ + | limit 1 | attr \"address\" }}" + serf = "{{ GetPublicInterfaces | include \"type\" \"IPv6\" \ + | limit 1 | attr \"address\" }}" +} +``` + +## Nomad to Nomad + +Nomad agent processes connect to one another to make RPC calls for cluster operations. + +We recommend using IPv6 on Nomad with DNS that resolves to IPv6 or by +using cloud auto-join. The following server-to-server and client-to-server +examples use IPv6 addresses explicitly. + +### Server to server + +Use the [`server_join`][server_join] block to link servers together. + +```hcl +server { + enabled = true + server_join { + retry_join = ["[2001:db8::1]", "[2001:db8::2]"] + } +} +``` + +### Client to server + +Use the [`servers`][client.servers] parameter or the `server_join` parameter to +link clients. + +```hcl +client { + enabled = true + servers = ["[2001:db8::1]", "[2001:db8::2]", "[2001:db8::3]"] +} +``` + +```hcl +server { + enabled = true + server_join { + retry_join = ["[2001:db8::1]", "[2001:db8::2]", "[2001:db8::3]"] + } +} +``` + +## Nomad to external systems + +Most connections between Nomad and other external systems occur via HTTP. + +For example, when you set this `NOMAD_ADDR` environment variable: + +``` +export NOMAD_ADDR='http://[2001:db8::1]:4646' +``` + +You can do the following: + +- Use the Nomad CLI, which makes Nomad API calls. +- Open the Nomad web UI in a browser with the command `nomad ui`. +- Use [Workload identity][workload-identity]. + - Nomad can reach Consul and Vault at IPv6 addresses, if they are listening, + to register services or fetch secrets. + - Configure Consul with the [`nomad setup consul` command][setup-consul]. + + ``` + nomad setup consul -y -jwks-url="$NOMAD_ADDR/.well-known/jwks.json" + + - Configure Vault with the [`nomad setup vault` command][setup-vault]. + + ``` + nomad setup vault -y -jwks-url="$NOMAD_ADDR/.well-known/jwks.json" + ``` + +Various other third-party services that support OIDC connections should also be +able to reach Nomad at an IPv6 address, so long as the third-party services +support IPv6. + +## Workloads + +Nomad supports arbitrary IPv6 network calls to and from tasks on client nodes. + +With host networking, tasks use the same network as the host machine. + +- Use these options to register services with an IPv6 address: + - Set the [`preferred_address_family`][preferred_address_family-config] + client config to `"ipv6"`. + - Include a [`service`][service-block] block in your job specification with + either the "nomad" or "consul" provider as usual. +- Use [`bridge_network_subnet_ipv6`][bridge-network-subnet-ipv6] to configure + Nomad's [bridge network mode][bridge-network-mode] for IPv6. + +[CNI][cni] plugins can work with IPv6 as well. Nomad's bridge network does this. + +Some task drivers have their own IPv6 configuration options. If you have enabled +IPv6 support in the [Docker driver][docker-driver], you can configure IPv6 in +your job specification. Refer to [IPv6 Docker +containers][ipv6-docker-containers] for details. + + +[server_join]: /nomad/docs/configuration/server_join +[client.servers]: /nomad/docs/configuration/client#servers +[go-sockaddr]: https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template +[advertise]: /nomad/docs/configuration#advertise +[workload-identity]: /nomad/docs/concepts/workload-identity +[service-block]: /nomad/docs/job-specification/service +[preferred_address_family-config]: /nomad/docs/configuration/client#preferred_address_family +[bridge-network-mode]: /nomad/docs/job-specification/network#network-modes +[bridge-network-subnet-ipv6]: /nomad/docs/configuration/client#bridge_network_subnet_ipv6 +[cni]: /nomad/docs/networking/cni +[docker-driver]: /nomad/docs/drivers/docker +[ipv6-docker-containers]: /nomad/docs/job-specification/service#ipv6-docker-containers +[setup-consul]: /nomad/docs/commands/setup/consul +[setup-vault]: /nomad/docs/commands/setup/vault diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 4a624a060b3..b8730da65a7 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -2396,6 +2396,10 @@ { "title": "Federate AWS Access with Workload Identity", "path": "operations/aws-oidc-provider" + }, + { + "title": "IPv6 Support", + "path": "operations/ipv6-support" } ] },