open-nomad/website/content/docs/configuration/server_join.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

228 lines
8.2 KiB
Plaintext
Raw Normal View History

2018-05-22 21:30:13 +00:00
---
2020-02-06 23:45:31 +00:00
layout: docs
page_title: server_join Block - Agent Configuration
2020-02-06 23:45:31 +00:00
description: >-
The "server_join" block specifies how the Nomad agent will discover and
2020-02-06 23:45:31 +00:00
connect to Nomad servers.
2018-05-22 21:30:13 +00:00
---
# `server_join` Block
2018-05-22 21:30:13 +00:00
2020-02-06 23:45:31 +00:00
<Placement
groups={[
['server', 'server_join'],
2020-09-30 13:48:40 +00:00
['client', 'server_join'],
2020-02-06 23:45:31 +00:00
]}
/>
2018-05-31 17:49:19 +00:00
The `server_join` block specifies how the Nomad agent will discover and connect
2018-05-31 17:49:19 +00:00
to Nomad servers.
2018-05-22 21:30:13 +00:00
```hcl
server_join {
retry_join = [ "1.1.1.1", "2.2.2.2" ]
retry_max = 3
retry_interval = "15s"
}
```
## `server_join` Parameters
2020-02-06 23:45:31 +00:00
- `retry_join` `(array<string>: [])` - Specifies a list of server addresses to
2018-05-31 17:49:19 +00:00
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
2020-02-06 23:45:31 +00:00
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
2018-05-31 17:49:19 +00:00
`start_join`, **do not use both options**.
2020-02-06 23:45:31 +00:00
Address format includes both using IP addresses as well as an interface to the
2018-05-25 20:04:32 +00:00
[go-discover](https://github.com/hashicorp/go-discover) library for doing
2020-02-06 23:45:31 +00:00
automated cluster joining using cloud metadata. See the [Cloud Auto-join](#cloud-auto-join)
2018-06-22 20:47:33 +00:00
section below for more information.
2018-05-25 20:04:32 +00:00
2020-02-06 23:45:31 +00:00
```
2018-05-25 20:04:32 +00:00
server_join {
2020-02-06 23:45:31 +00:00
retry_join = [ "1.1.1.1", "2.2.2.2" ]
2018-05-25 20:04:32 +00:00
}
```
2020-02-06 23:45:31 +00:00
Using the `go-discover` interface, this can be defined both in a client or
2018-05-25 20:04:32 +00:00
server configuration as well as provided as a command-line argument.
2018-05-31 17:49:19 +00:00
2020-02-06 23:45:31 +00:00
```
2018-05-25 20:04:32 +00:00
server_join {
2020-02-06 23:45:31 +00:00
retry_join = [ "provider=aws tag_key=..." ]
2018-05-25 20:04:32 +00:00
}
```
2018-05-31 17:49:19 +00:00
2020-02-06 23:45:31 +00:00
See the [server address format](#server-address-format) for more information about expected
server address formats.
2018-05-22 21:30:13 +00:00
2018-05-31 17:49:19 +00:00
- `retry_interval` `(string: "30s")` - Specifies the time to wait between retry
2018-05-22 21:30:13 +00:00
join attempts.
2018-05-31 17:49:19 +00:00
- `retry_max` `(int: 0)` - Specifies the maximum number of join attempts to be
2018-05-22 21:30:13 +00:00
made before exiting with a return code of 1. By default, this is set to 0
which is interpreted as infinite retries.
2018-05-31 17:49:19 +00:00
- `start_join` `(array<string>: [])` - Specifies a list of server addresses to
2018-05-22 21:30:13 +00:00
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 defined only for Nomad servers and
will result in a configuration parse error if included in a client
configuration.
2018-05-31 17:49:19 +00:00
## Server Address Format
2018-05-22 21:30:13 +00:00
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.
2018-05-31 17:49:19 +00:00
### Directly via IP Address
2018-05-22 21:30:13 +00:00
It is possible to address another Nomad server using its IP address. This is
done in the `ip:port` format, such as:
```
1.2.3.4:5678
```
If the port option is omitted, it defaults to the Serf port, which is 4648
unless configured otherwise:
```
1.2.3.4 => 1.2.3.4:4648
```
2018-05-31 17:49:19 +00:00
### Via Domains or DNS
2018-05-22 21:30:13 +00:00
It is possible to address another Nomad server using its DNS address. This is
done in the `address:port` format, such as:
```
nomad-01.company.local:5678
```
If the port option is omitted, it defaults to the Serf port, which is 4648
unless configured otherwise:
```
nomad-01.company.local => nomad-01.company.local:4648
```
2018-05-31 17:49:19 +00:00
### Via the go-discover interface
2018-05-22 21:30:13 +00:00
As of Nomad 0.8.4, `retry_join` accepts a unified interface using the
2018-05-22 21:30:13 +00:00
[go-discover](https://github.com/hashicorp/go-discover) library for doing
2018-05-31 17:49:19 +00:00
automated cluster joining using cloud metadata. See [Cloud
Auto-join](#cloud-auto-join) for more information.
2018-05-22 21:30:13 +00:00
```
"provider=aws tag_key=..." => 1.2.3.4:4648
```
2018-05-31 17:49:19 +00:00
2018-06-22 20:47:33 +00:00
## Cloud Auto-join
2020-02-06 23:45:31 +00:00
The following sections describe the Cloud Auto-join `retry_join` options that are specific
to a subset of supported cloud providers. For information on all providers, see further
2018-06-22 20:47:33 +00:00
documentation in [go-discover](https://github.com/hashicorp/go-discover).
### Amazon EC2
This returns the first private IP address of all servers in the given
region which have the given `tag_key` and `tag_value`.
```json
{
"retry_join": ["provider=aws tag_key=... tag_value=..."]
}
```
- `provider` (required) - the name of the provider ("aws" in this case).
- `tag_key` (required) - the key of the tag to auto-join on.
- `tag_value` (required) - the value of the tag to auto-join on.
- `region` (optional) - the AWS region to authenticate in.
- `addr_type` (optional) - the type of address to discover: `private_v4`, `public_v4`, `public_v6`. Default is `private_v4`. (>= 1.0)
- `access_key_id` (optional) - the AWS access key for authentication (see below for more information about authenticating).
- `secret_access_key` (optional) - the AWS secret access key for authentication (see below for more information about authenticating).
#### Authentication &amp; Precedence
- Static credentials `access_key_id=... secret_access_key=...`
- Environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`)
- Shared credentials file (`~/.aws/credentials` or the path specified by `AWS_SHARED_CREDENTIALS_FILE`)
- ECS task role metadata (container-specific).
- EC2 instance role metadata.
The only required IAM permission is `ec2:DescribeInstances`, and it is
recommended that you make a dedicated key used only for auto-joining. If the
region is omitted it will be discovered through the local instance's [EC2
metadata
endpoint](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html).
### Microsoft Azure
2020-02-06 23:45:31 +00:00
This returns the first private IP address of all servers in the given region
which have the given `tag_key` and `tag_value` in the tenant and subscription, or in
the given `resource_group` of a `vm_scale_set` for Virtual Machine Scale Sets.
2018-06-22 20:47:33 +00:00
2020-02-06 23:45:31 +00:00
```json
2018-06-22 20:47:33 +00:00
{
2020-02-06 23:45:31 +00:00
"retry_join": [
"provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."
]
2018-06-22 20:47:33 +00:00
}
```
- `provider` (required) - the name of the provider ("azure" in this case).
- `tenant_id` (required) - the tenant to join machines in.
- `client_id` (required) - the client to authenticate with.
- `secret_access_key` (required) - the secret client key.
Use these configuration parameters when using tags:
2020-02-06 23:45:31 +00:00
2018-06-22 20:47:33 +00:00
- `tag_name` - the name of the tag to auto-join on.
- `tag_value` - the value of the tag to auto-join on.
Use these configuration parameters when using Virtual Machine Scale Sets (Consul 1.0.3 and later):
2020-02-06 23:45:31 +00:00
2018-06-22 20:47:33 +00:00
- `resource_group` - the name of the resource group to filter on.
- `vm_scale_set` - the name of the virtual machine scale set to filter on.
2020-02-06 23:45:31 +00:00
When using tags the only permission needed is the `ListAll` method for `NetworkInterfaces`. When using
Virtual Machine Scale Sets the only role action needed is `Microsoft.Compute/virtualMachineScaleSets/*/read`.
2018-06-22 20:47:33 +00:00
### Google Compute Engine
This returns the first private IP address of all servers in the given
project which have the given `tag_value`.
2020-02-06 23:45:31 +00:00
2018-06-22 20:47:33 +00:00
```json
{
"retry_join": ["provider=gce project_name=... tag_value=..."]
2018-06-22 20:47:33 +00:00
}
```
2018-06-22 20:47:33 +00:00
- `provider` (required) - the name of the provider ("gce" in this case).
- `tag_value` (required) - the value of the tag to auto-join on.
- `project_name` (optional) - the name of the project to auto-join on. Discovered if not set.
- `zone_pattern` (optional) - the list of zones can be restricted through an RE2 compatible regular expression. If omitted, servers in all zones are returned.
- `credentials_file` (optional) - the credentials file for authentication. See below for more information.
#### Authentication &amp; Precedence
- Use credentials from `credentials_file`, if provided.
- Use JSON file from `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
- Use JSON file in a location known to the gcloud command-line tool.
- On Windows, this is `%APPDATA%/gcloud/application_default_credentials.json`.
- On other systems, `$HOME/.config/gcloud/application_default_credentials.json`.
- On Google Compute Engine, use credentials from the metadata
2020-02-06 23:45:31 +00:00
server. In this final case any provided scopes are ignored.
2018-06-22 20:47:33 +00:00
Discovery requires a [GCE Service
Account](https://cloud.google.com/compute/docs/access/service-accounts).
Credentials are searched using the following paths, in order of precedence.