diff --git a/website/source/docs/agent/configuration/cloud-auto-join.html.md b/website/source/docs/agent/cloud_auto_join.html.md similarity index 97% rename from website/source/docs/agent/configuration/cloud-auto-join.html.md rename to website/source/docs/agent/cloud_auto_join.html.md index 71c9bc847d4..d733fe7066e 100644 --- a/website/source/docs/agent/configuration/cloud-auto-join.html.md +++ b/website/source/docs/agent/cloud_auto_join.html.md @@ -8,7 +8,9 @@ description: |- # Cloud Auto-joining -As of Nomad 0.8.4, `retry-join` accepts a unified interface using the +As of Nomad 0.8.4, +[`retry_join`](/docs/agent/configuration/server_join.html#retry_join) accepts a +unified interface using the [go-discover](https://github.com/hashicorp/go-discover) library for doing automatic cluster joining using cloud metadata. To use retry-join with a supported cloud provider, specify the configuration on the command line or diff --git a/website/source/docs/agent/configuration/client.html.md b/website/source/docs/agent/configuration/client.html.md index 7cee5601a59..2ba20be5b3a 100644 --- a/website/source/docs/agent/configuration/client.html.md +++ b/website/source/docs/agent/configuration/client.html.md @@ -90,7 +90,7 @@ client { receive work. This may be specified as an IP address or DNS, with or without the port. If the port is omitted, the default port of `4647` is used. -- `server_join` ([server_join](#server-join): nil) - Specifies +- `server_join` ([server_join][server-join]: nil) - Specifies how the Nomad client will connect to Nomad servers. The `start_join` field is not supported on the client. The retry_join fields may directly specify the server address or use go-discover syntax for auto-discovery. See the diff --git a/website/source/docs/agent/configuration/server.html.md b/website/source/docs/agent/configuration/server.html.md index d1919872d11..6da8ab88e85 100644 --- a/website/source/docs/agent/configuration/server.html.md +++ b/website/source/docs/agent/configuration/server.html.md @@ -135,10 +135,10 @@ server { cluster again when starting. This flag allows the previous state to be used to rejoin the cluster. -- `server_join` ([server_join](#server-join): nil) - Specifies - how the Nomad client will connect to Nomad servers. The retry_join fields may - directly specify the server address or use go-discover syntax for - auto-discovery. See the documentation for more detail. +- `server_join` ([server_join][server-join]: nil) - Specifies + how the Nomad server will connect to other Nomad servers. The `retry_join` + fields may directly specify the server address or use go-discover syntax for + auto-discovery. See the [server_join documentation][server-join] for more detail. - `upgrade_version` `(string: "")` - A custom version of the format X.Y.Z to use in place of the Nomad version when custom upgrades are enabled in Autopilot. @@ -153,25 +153,25 @@ server { succeeds. After one succeeds, no further addresses will be contacted. This is useful for cases where we know the address will become available eventually. Use `retry_join` with an array as a replacement for `start_join`, **do not use - both options**. See the [server_join](#server-join) + both options**. See the [server_join][server-join] section for more information on the format of the string. This field is - deprecated in favor of [server_join](#server-join). + deprecated in favor of the [server_join stanza][server-join]. - `retry_interval` `(string: "30s")` - Specifies the time to wait between retry - join attempts. This field is deprecated in favor of - [server_join](#server-join). + join attempts. This field is deprecated in favor of the [server_join + stanza][server-join]. - `retry_max` `(int: 0)` - Specifies the maximum number of join attempts to be made before exiting with a return code of 1. By default, this is set to 0 - which is interpreted as infinite retries. This field is deprecated in favor - of [server_join](#server-join). + which is interpreted as infinite retries. This field is deprecated in favor of + the [server_join stanza][server-join]. - `start_join` `(array: [])` - Specifies a list of server addresses to join on startup. If Nomad is unable to join with any of the specified - addresses, agent startup will fail. See the - [server address format](#server-address-format) section for more information - on the format of the string. This field is deprecated in favor of - [server_join](#server-join). + addresses, agent startup will fail. See the [server address + format](/docs/agent/configuration/server_join.html#server-address-format) + section for more information on the format of the string. This field is + deprecated in favor of the [server_join stanza][server-join]. ## `server` Examples @@ -219,4 +219,4 @@ server { ``` [encryption]: /docs/agent/encryption.html "Nomad Agent Encryption" -[server-join]: /docs/agent/configuration/server_join.html.md "Server Join" +[server-join]: /docs/agent/configuration/server_join.html "Server Join" diff --git a/website/source/docs/agent/configuration/server_join.html.md b/website/source/docs/agent/configuration/server_join.html.md index 4fa823e2356..82620a781c2 100644 --- a/website/source/docs/agent/configuration/server_join.html.md +++ b/website/source/docs/agent/configuration/server_join.html.md @@ -1,14 +1,26 @@ --- layout: "docs" page_title: "server_join Stanza - Agent Configuration" -sidebar_current: "docs-agent-configuration-server_join" +sidebar_current: "docs-agent-configuration--server-join" description: |- - The server_join stanza specifies how the Nomad agent will discover and connect to Nomad servers. + The "server_join" stanza specifies how the Nomad agent will discover and connect to Nomad servers. --- # `server_join` Stanza -The server_join stanza specifies how the Nomad agent will discover and connect to Nomad servers. + + + + + +
Placement + server -> **server_join** +
+ client -> **server_join** +
+ +The `server_join` stanza specifies how the Nomad agent will discover and connect +to Nomad servers. ```hcl server_join { @@ -20,46 +32,46 @@ server_join { ## `server_join` Parameters -- `retry_join` `(array: [])` - Specifies a list of server - addresses to retry joining if the first attempt fails. This is similar to - [`start_join`](#start_join), but only invokes if the initial join attempt - fails, and is available to both Nomad servers and clients, while - `start_join` is only defined for Nomad servers. The list of addresses will - be tried in the order specified, until one succeeds. After one succeeds, no - further addresses will be contacted. This is - useful for cases where we know the address will become available eventually. - Use `retry_join` with an array as a replacement for `start_join`, **do not use - both options**. - - Address format includes both using IP addresses as well as an interface to the +- `retry_join` `(array: [])` - Specifies a list of server addresses to + join. This is similar to [`start_join`](#start_join), but will continue to + be attempted even if the initial join attempt fails, up to + [retry_max](#retry_max). Further, `retry_join` is available to + both Nomad servers and clients, while `start_join` is only defined for Nomad + servers. This is useful for cases where we know the address will become + available eventually. Use `retry_join` with an array as a replacement for + `start_join`, **do not use both options**. + + Address format includes both using IP addresses as well as an interface to the [go-discover](https://github.com/hashicorp/go-discover) library for doing - automated cluster joining using cloud metadata. - See Cloud Auto Join`([CloudAutoJoin][cloud_auto_join]: nil). + automated cluster joining using cloud metadata. See [Cloud + Auto-join][cloud_auto_join] for more information. - ``` + ``` server_join { retry_join = [ "1.1.1.1", "2.2.2.2" ] } ``` - Using the `go-discover` interface, this can be defined both in a client or + Using the `go-discover` interface, this can be defined both in a client or server configuration as well as provided as a command-line argument. - ``` + + ``` server_join { retry_join = [ "provider=aws tag_key=..." ] } ``` - See the [server address format](#server-address-format) for more information + + See the [server address format](#server-address-format) for more information about expected server address formats. -- `retry_interval` `(string: "30s")` - Specifies the time to wait between retry +- `retry_interval` `(string: "30s")` - Specifies the time to wait between retry join attempts. -- `retry_max` `(int: 0)` - Specifies the maximum number of join attempts to be +- `retry_max` `(int: 0)` - Specifies the maximum number of join attempts to be made before exiting with a return code of 1. By default, this is set to 0 which is interpreted as infinite retries. -- `start_join` `(array: [])` - Specifies a list of server addresses to +- `start_join` `(array: [])` - Specifies a list of server addresses to join on startup. If Nomad is unable to join with any of the specified addresses, agent startup will fail. See the [server address format](#server-address-format) section for more information @@ -67,13 +79,13 @@ server_join { will result in a configuration parse error if included in a client configuration. -### Server Address Format +## Server Address Format This section describes the acceptable syntax and format for describing the location of a Nomad server. There are many ways to reference a Nomad server, including directly by IP address and resolving through DNS. -#### Directly via IP Address +### Directly via IP Address It is possible to address another Nomad server using its IP address. This is done in the `ip:port` format, such as: @@ -89,7 +101,7 @@ unless configured otherwise: 1.2.3.4 => 1.2.3.4:4648 ``` -#### Via Domains or DNS +### Via Domains or DNS It is possible to address another Nomad server using its DNS address. This is done in the `address:port` format, such as: @@ -105,14 +117,15 @@ unless configured otherwise: nomad-01.company.local => nomad-01.company.local:4648 ``` -#### Via the go-discover interface +### Via the go-discover interface As of Nomad 0.8.4, `retry_join` accepts a unified interface using the [go-discover](https://github.com/hashicorp/go-discover) library for doing -automated cluster joining using cloud metadata. +automated cluster joining using cloud metadata. See [Cloud +Auto-join][cloud_auto_join] for more information. ``` "provider=aws tag_key=..." => 1.2.3.4:4648 - -See ([CloudAutoJoin][cloud_auto_join]: nil) for further information. ``` + +[cloud_auto_join]: /docs/agent/cloud_auto_join.html "Nomad Cloud Auto-join" diff --git a/website/source/docs/commands/agent.html.md.erb b/website/source/docs/commands/agent.html.md.erb index ea3b4f40b64..4afb7717802 100644 --- a/website/source/docs/commands/agent.html.md.erb +++ b/website/source/docs/commands/agent.html.md.erb @@ -71,13 +71,14 @@ via CLI arguments. The `agent` command accepts the following arguments: * `-region=`: Equivalent to the [region](#region) config option. * `-rejoin`: Equivalent to the [rejoin_after_leave](#rejoin_after_leave) config option. * `-retry-interval`: Equivalent to the [retry_interval](#retry_interval) config option. -* `-retry-join`: Similar to `-join` but allows retrying a join if the first attempt fails. +* `-retry-join`: Similar to `-join` but allows retrying a join if the first attempt fails. -Note that `retry_join` can be defined for only servers as a command-line -flag (clients are only able to define via the client configuration). -```sh -$ nomad agent -retry-join "127.0.0.1:4648" -` + ```sh + $ nomad agent -retry-join "127.0.0.1:4648" + ``` + + Note that `retry_join` can be defined for only servers as a command-line + flag (clients are only able to define via the client configuration). * `-retry-max`: Similar to the [retry_max](#retry_max) config option. * `-server`: Enable server mode on the local agent. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 2fa5684181f..eea874b8f7e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -396,6 +396,9 @@ Nomad Agent