kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-01 16:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Separate agent configuration into its own pages

Browse Source 
I apologize in advance for the rather long PR, but unfortunately there
is not an easy way to break this up into smaller chunks. This separates
the agent configuration into smaller, more consumable pieces just like
the job specification.
This commit is contained in:
Seth Vargo
2016-11-01 08:53:13 -04:00
parent 6cd6b5d7f6
commit c86a07d834
48 changed files with 1497 additions and 814 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@@ -13,7 +13,7 @@ branches:
only:
- master
before_install:
before_install:
- sudo apt-get update
- sudo apt-get install -y docker-engine liblxc1 lxc-dev lxc
- sudo apt-get install -y qemu

4
command/agent/agent.go
View File

@@ -241,8 +241,8 @@ func (a *Agent) clientConfig() (*clientconfig.Config, error) {
}
if len(invalidConsulKeys) > 0 {
a.logger.Printf("[WARN] agent: Invalid keys: %v", strings.Join(invalidConsulKeys, ","))
a.logger.Printf(`Nomad client ignores consul related configuration in client options.
Please refer to the guide https://www.nomadproject.io/docs/agent/config.html#consul_options
a.logger.Printf(`Nomad client ignores consul related configuration in client options.
Please refer to the guide https://www.nomadproject.io/docs/agent/configuration/consul.html
to configure Nomad to work with Consul.`)
}

4
command/agent/config.go
View File

@@ -288,7 +288,7 @@ type Telemetry struct {
// Default: none
CirconusAPIToken string `mapstructure:"circonus_api_token"`
// CirconusAPIApp is an app name associated with API token.
// Default: "consul"
// Default: "nomad"
CirconusAPIApp string `mapstructure:"circonus_api_app"`
// CirconusAPIURL is the base URL to use for contacting the Circonus API.
// Default: "https://api.circonus.com/v2"
@@ -317,7 +317,7 @@ type Telemetry struct {
CirconusCheckInstanceID string `mapstructure:"circonus_check_instance_id"`
// CirconusCheckSearchTag is a special tag which, when coupled with the instance id, helps to
// narrow down the search results when neither a Submission URL or Check ID is provided.
// Default: service:app (e.g. service:consul)
// Default: service:app (e.g. service:nomad)
CirconusCheckSearchTag string `mapstructure:"circonus_check_search_tag"`
// CirconusBrokerID is an explicit broker to use when creating a new check. The numeric portion
// of broker._cid. If metric management is enabled and neither a Submission URL nor Check ID

4
dist/README.md vendored
View File

@@ -15,7 +15,7 @@ The following example configuration files are provided:
Place one of these under `/etc/nomad` depending on the node's role. You should use `server.hcl` to configure a node as a server (which is responsible for scheduling) or `client.hcl` to configure a node as a client (which is responsible for running workloads).
Read <https://nomadproject.io/docs/agent/config.html> to learn which options are available and how to configure them.
Read <https://nomadproject.io/docs/agent/configuration/index.html> to learn which options are available and how to configure them.
## Upstart
@@ -27,4 +27,4 @@ You can control Nomad with `start|stop|restart nomad`.
On systems using systemd the basic systemd unit file under `systemd/nomad.service` starts and stops the nomad agent. Place it under `/etc/systemd/system/nomad.service`.
You can control Nomad with `systemctl start|stop|restart nomad`.
You can control Nomad with `systemctl start|stop|restart nomad`.

2
website/Gemfile
View File

@@ -1,3 +1,3 @@
source "https://rubygems.org"
gem "middleman-hashicorp", "0.3.4"
gem "middleman-hashicorp", "0.3.5"

6
website/Gemfile.lock
View File

@@ -78,7 +78,7 @@ GEM
rack (>= 1.4.5, < 2.0)
thor (>= 0.15.2, < 2.0)
tilt (~> 1.4.1, < 2.0)
middleman-hashicorp (0.3.4)
middleman-hashicorp (0.3.5)
bootstrap-sass (~> 3.3)
builder (~> 3.2)
middleman (~> 3.4)
@@ -148,7 +148,7 @@ PLATFORMS
ruby
DEPENDENCIES
middleman-hashicorp (= 0.3.4)
middleman-hashicorp (= 0.3.5)
BUNDLED WITH
1.13.5
1.13.6

2
website/Makefile
View File

@@ -1,4 +1,4 @@
VERSION?="0.3.4"
VERSION?="0.3.5"
website:
@echo "==> Starting website in Docker..."

2
website/packer.json
View File

@@ -8,7 +8,7 @@
"builders": [
{
"type": "docker",
"image": "hashicorp/middleman-hashicorp:0.3.4",
"image": "hashicorp/middleman-hashicorp:0.3.5",
"discard": "true",
"run_command": ["-d", "-i", "-t", "{{ .Image }}", "/bin/sh"]
}

11
website/source/assets/stylesheets/_docs.scss
View File

@@ -248,10 +248,6 @@ body.layout-intro{
@include open-sb();
}
h1{
font-size: 36px;
}
h2 {
padding-bottom: 3px;
border-bottom: 1px solid $gray-light;
@@ -272,9 +268,6 @@ body.layout-intro{
@media (max-width: 768px) {
.bs-docs-section{
padding-top: 0;
h1{
margin-top: 0;
}
}
}
@@ -283,9 +276,5 @@ body.layout-intro{
img{
max-width: 450px;
}
h1{
font-size: 32px;
}
}
}

33
website/source/assets/stylesheets/_global.scss
View File

@@ -20,17 +20,14 @@ body {
h1, h2, h3, h4, h5 {
-webkit-font-smoothing: antialiased;
}
h1{
font-size: 42px;
line-height: 42px;
font-family: $font-family-open-sans;
font-weight: $font-weight-reg;
margin-bottom: 24px;
}
h3, h4{
font-size: 24px;
line-height: 24px;
font-family: $font-family-open-sans;
font-weight: $font-weight-reg;
}
@@ -91,31 +88,3 @@ pre {
max-width: 970px;
}
}
@media (max-width: 768px) {
body {
font-size: 14px;
}
h1{
font-size: $font-size-m !important;
line-height: $font-size-m;
font-weight: $font-weight-reg;
margin-bottom: 24px;
}
h2{
font-size: $font-size-m !important;
font-weight: $font-weight-reg;
}
h3{
font-size: $font-size-m !important;
font-weight: $font-weight-reg;
}
h4{
font-size: $font-size-reg !important;
font-weight: $font-weight-reg;
}
}

8
website/source/data/vault/nomad-server-policy.hcl
View File

@@ -1,20 +1,20 @@
# Allow creating tokens under the role
path "auth/token/create/nomad-server" {
capabilities = ["create", "update"]
capabilities = ["create", "update"]
}
# Allow looking up the role
path "auth/token/roles/nomad-server" {
capabilities = ["read"]
capabilities = ["read"]
}
# Allow looking up incoming tokens to validate they have permissions to
# access the tokens they are requesting
path "auth/token/lookup/*" {
capabilities = ["read"]
capabilities = ["read"]
}
# Allow revoking tokens that should no longer exist
path "/auth/token/revoke-accessor/*" {
capabilities = ["update"]
capabilities = ["update"]
}

12
website/source/data/vault/nomad-server-role.json
View File

@@ -1,8 +1,8 @@
{
"allowed_policies": "nomad-server",
"explicit_max_ttl": 0,
"name": "nomad-server",
"orphan": false,
"period": 259200,
"renewable": true
"allowed_policies": "nomad-server",
"explicit_max_ttl": 0,
"name": "nomad-server",
"orphan": false,
"period": 259200,
"renewable": true
}

684
website/source/docs/agent/config.html.md
View File

@@ -1,684 +0,0 @@
---
layout: "docs"
page_title: "Configuration"
sidebar_current: "docs-agent-config"
description: |-
Learn about the configuration options available for the Nomad agent.
---
# Configuration
Nomad agents have a variety of options that can be specified via configuration
files or command-line flags. Config files must be written in
[HCL](https://github.com/hashicorp/hcl) or JSON syntax. Nomad can read and
combine options from multiple configuration files or directories to configure
the Nomad agent.
## Loading Configuration Files
When specifying multiple config file options on the command-line, the files are
loaded in the order they are specified. For example:
```shell
$ nomad agent -config=server.conf -config=/etc/nomad -config=extra.json
```
Will load configuration from `server.conf`, from `.hcl` and `.json` files under
`/etc/nomad`, and finally from `extra.json`.
Configuration files in directories are loaded alphabetically. With the
directory option, only files ending with the `.hcl` or `.json` extensions are
used. Directories are not loaded recursively.
As each file is processed, its contents are merged into the existing
configuration. When merging, any non-empty values from the latest config file
will append or replace options in the current configuration. An empty value
means `""` for strings, `0` for integer or float values, and `false` for
booleans. Since empty values are ignored you cannot disable an option like
server mode once you've enabled it.
Complex data types like arrays or maps are usually merged. [Some configuration
options](#cli) can also be specified using the command-line interface. Please
refer to the sections below for the details of each option.
## Configuration Syntax
The preferred configuration syntax is HCL, which supports comments, but you can
also use JSON. Below is an example configuration file in HCL syntax.
```hcl
bind_addr = "0.0.0.0"
data_dir = "/var/lib/nomad"
advertise {
# We need to specify our host's IP because we can't
# advertise 0.0.0.0 to other nodes in our cluster.
rpc = "1.2.3.4:4647"
}
server {
enabled = true
bootstrap_expect = 3
}
client {
enabled = true
network_speed = 10
options {
"driver.raw_exec.enable" = "1"
}
}
consul {
address = "1.2.3.4:8500"
}
atlas {
infrastructure = "hashicorp/mars"
token = "atlas.v1.AFE84330943"
}
```
Note that it is strongly recommended _not_ to operate a node as both `client`
and `server`, although this is supported to simplify development and testing.
## General Options
The following configuration options are available to both client and server
nodes, unless otherwise specified:
* <a id="region">`region`</a>: Specifies the region the Nomad agent is a
member of. A region typically maps to a geographic region, for example `us`,
with potentially multiple zones, which map to [datacenters](#datacenter) such
as `us-west` and `us-east`. Defaults to `global`.
* `datacenter`: Datacenter of the local agent. All members of a datacenter
should share a local LAN connection. Defaults to `dc1`.
* <a id="name">`name`</a>: The name of the local node. This value is used to
identify individual nodes in a given datacenter and must be unique
per-datacenter. By default this is set to the local host's name.
* `data_dir`: A local directory used to store agent state. Client nodes use this
directory by default to store temporary allocation data as well as cluster
information. Server nodes use this directory to store cluster state, including
the replicated log and snapshot data. This option is required to start the
Nomad agent and must be specified as an absolute path.
* `log_level`: Controls the verbosity of logs the Nomad agent will output. Valid
log levels include `WARN`, `INFO`, or `DEBUG` in increasing order of
verbosity. Defaults to `INFO`.
* <a id="bind_addr">`bind_addr`</a>: Used to indicate which address the Nomad
agent should bind to for network services, including the HTTP interface as
well as the internal gossip protocol and RPC mechanism. This should be
specified in IP format, and can be used to easily bind all network services to
the same address. It is also possible to bind the individual services to
different addresses using the [addresses](#addresses) configuration option.
Defaults to the local loopback address `127.0.0.1`.
* `enable_debug`: Enables the debugging HTTP endpoints. These endpoints can be
used with profiling tools to dump diagnostic information about Nomad's
internals. It is not recommended to leave this enabled in production
environments. Defaults to `false`.
* `ports`: Controls the network ports used for different services required by
the Nomad agent. The value is a key-value mapping of port numbers, and accepts
the following keys:
<br>
* `http`: The port used to run the HTTP server. Applies to both client and
server nodes. Defaults to `4646`.
* `rpc`: The port used for internal RPC communication between agents and
servers, and for inter-server traffic for the consensus algorithm (raft).
Defaults to `4647`. Only used on server nodes.
* `serf`: The port used for the gossip protocol for cluster membership. Both
TCP and UDP should be routable between the server nodes on this port.
Defaults to `4648`. Only used on server nodes.
* <a id="addresses">`addresses`</a>: Controls the bind address for individual
network services. Any values configured in this block take precedence over the
default [bind_addr](#bind_addr). The value is a map of IP addresses and
supports the following keys:
<br>
* `http`: The address the HTTP server is bound to. This is the most common
bind address to change. Applies to both clients and servers.
* `rpc`: The address to bind the internal RPC interfaces to. Should be exposed
only to other cluster members if possible. Used only on server nodes, but
must be accessible from all agents.
* `serf`: The address used to bind the gossip layer to. Both a TCP and UDP
listener will be exposed on this address. Should be restricted to only
server nodes from the same datacenter if possible. Used only on server
nodes.
* `advertise`: Controls the advertise address for individual network services.
This can be used to advertise a different address to the peers of a server or
a client node to support more complex network configurations such as NAT. This
configuration is optional, and defaults to the bind address of the specific
network service if it is not provided. The value is a map of IP addresses and
ports and supports the following keys:
<br>
* `http`: The address to advertise for the HTTP interface. This should be
reachable by all the nodes from which end users are going to use the Nomad
CLI tools.
```
advertise {
http = "1.2.3.4:4646"
}
```
* `rpc`: The address to advertise for the RPC interface. This address should
be reachable by all of the agents in the cluster. For example:
```
advertise {
rpc = "1.2.3.4:4647"
}
```
* `serf`: The address advertised for the gossip layer. This address must be
reachable from all server nodes. It is not required that clients can reach
this address.
* `consul`: The `consul` configuration block changes how Nomad interacts with
Consul. Nomad can automatically advertise Nomad services via Consul, and can
automatically bootstrap itself using Consul. For more details see the [`consul`
section](#consul_options).
<a id="telemetry_config"></a>
* `telemetry`: Used to control how the Nomad agent exposes telemetry data to
external metrics collection servers. This is a key-value mapping and supports
the following keys:
<br>
* `statsite_address`: Address of a
[statsite](https://github.com/armon/statsite) server to forward metrics data
to.
* `statsd_address`: Address of a [statsd](https://github.com/etsy/statsd)
server to forward metrics to.
* `datadog_address`: Address of a [DataDog statsd](https://github.com/DataDog/dd-agent)
server to forward metrics to.
* `disable_hostname`: A boolean indicating if gauge values should not be
prefixed with the local hostname.
* `publish_allocation_metrics`: Enables publishing runtime metrics of
individual allocations. Default is `false`.
* `publish_node_metrics`: Enables publishing client-specific runtime metrics. Default
is `false`.
* `circonus_api_token`
A valid [Circonus](http://circonus.com/) API Token used to create/manage check. If provided, metric management is enabled.
* `circonus_api_app`
A valid app name associated with the API token. By default, this is set to "consul".
* `circonus_api_url`
The base URL to use for contacting the Circonus API. By default, this is set to "https://api.circonus.com/v2".
* `circonus_submission_interval`
The interval at which metrics are submitted to Circonus. By default, this is set to "10s" (ten seconds).
* `circonus_submission_url`
The `check.config.submission_url` field, of a Check API object, from a previously created HTTPTRAP check.
* `circonus_check_id`
The Check ID (not **check bundle**) from a previously created HTTPTRAP check. The numeric portion of the `check._cid` field in the Check API object.
* `circonus_check_force_metric_activation`
Force activation of metrics which already exist and are not currently active. If check management is enabled, the default behavior is to add new metrics as they are encountered. If the metric already exists in the check, it will **not** be activated. This setting overrides that behavior. By default, this is set to "false".
* `circonus_check_instance_id`
Serves to uniquely identify the metrics coming from this *instance*. It can be used to maintain metric continuity with transient or ephemeral instances as they move around within an infrastructure. By default, this is set to hostname:application name (e.g. "host123:consul").
* `circonus_check_search_tag`
A special tag which, when coupled with the instance id, helps to narrow down the search results when neither a Submission URL or Check ID is provided. By default, this is set to service:app (e.g. "service:consul").
* `circonus_broker_id`
The ID of a specific Circonus Broker to use when creating a new check. The numeric portion of `broker._cid` field in a Broker API object. If metric management is enabled and neither a Submission URL nor Check ID is provided, an attempt will be made to search for an existing check using Instance ID and Search Tag. If one is not found, a new HTTPTRAP check will be created. By default, this is not used and a random Enterprise Broker is selected, or, the default Circonus Public Broker.
* `circonus_broker_select_tag`
A special tag which will be used to select a Circonus Broker when a Broker ID is not provided. The best use of this is to as a hint for which broker should be used based on *where* this particular instance is running (e.g. a specific geo location or datacenter, dc:sfo). By default, this is not used.
* `leave_on_interrupt`: Enables gracefully leaving when receiving the
interrupt signal. By default, the agent will exit forcefully on any signal.
* `leave_on_terminate`: Enables gracefully leaving when receiving the
terminate signal. By default, the agent will exit forcefully on any signal.
* `enable_syslog`: Enables logging to syslog. This option only works on
Unix based systems.
* `syslog_facility`: Controls the syslog facility that is used. By default,
`LOCAL0` will be used. This should be used with `enable_syslog`.
* `disable_update_check`: Disables automatic checking for security bulletins
and new version releases.
* `disable_anonymous_signature`: Disables providing an anonymous signature
for de-duplication with the update check. See `disable_update_check`.
* `http_api_response_headers`: This object allows adding headers to the
HTTP API responses. For example, the following config can be used to enable
CORS on the HTTP API endpoints:
```
http_api_response_headers {
Access-Control-Allow-Origin = "*"
}
```
* `atlas`: See the [`atlas` options](#atlas_options) for more details.
## <a id="consul_options"></a>Consul Options
The following options are used to configure [Consul](https://www.consul.io)
integration and are entirely optional.
* `consul`: The top-level config key used to contain all Consul-related
configuration options. The value is a key-value map which supports the
following keys:
<br>
* `address`: The address to the local Consul agent given in the format of
`host:port`. Defaults to `127.0.0.1:8500`, which is the same as the Consul
default HTTP address.
* `token`: Token is used to provide a per-request ACL token. This option
overrides the Consul Agent's default token.
* `auth`: The auth information to use for HTTP access to the Consul Agent
given as `username:password`.
* `ssl`: This boolean option sets the transport scheme to talk to the Consul
Agent as `https`. Defaults to `false`.
* `verify_ssl`: This option enables SSL verification when the transport
scheme for the Consul API client is `https`. Defaults to `true`.
* `ca_file`: Optional path to the CA certificate used for Consul
communication, defaults to the system bundle if not specified.
* `cert_file`: The path to the certificate used for Consul communication. If
this is set then you need to also set `key_file`.
* `key_file`: The path to the private key used for Consul communication. If
this is set then you need to also set `cert_file`.
* `server_service_name`: The name of the service that Nomad registers servers
with. Defaults to `nomad`.
* `client_service_name`: The name of the service that Nomad registers clients
with. Defaults to `nomad-client`.
* `auto_advertise`: When enabled Nomad advertises its services to Consul. The
services are named according to `server_service_name` and
`client_service_name`. Nomad Servers and Clients advertise their respective
services, each tagged appropriately with either `http` or `rpc` tag. Nomad
Servers also advertise a `serf` tagged service. Defaults to `true`.
* `checks_use_advertise`: By default, Nomad will use the configured bind
address as the target for its consul checks. This boolean option allows you
to request that the advertise address be used instead.
* `server_auto_join`: Servers will automatically discover and join other
Nomad Servers by searching for the Consul service name defined in the
`server_service_name` option. This search only happens if the Server does
not have a leader. Defaults to `true`.
* `client_auto_join`: Client will automatically discover Servers in the
Client's region by searching for the Consul service name defined in the
`server_service_name` option. The search occurs if the Client is not
registered with any Servers or it is unable to heartbeat to the leader of
the region, in which case it may be partitioned and searches for other
Servers. Defaults to `true`
When `server_auto_join`, `client_auto_join` and `auto_advertise` are all
enabled, which is by default, and Consul is available, the Nomad cluster will
self-bootstrap.
## Vault Options
The following options are used to configure [Vault](https://www.vaultproject.io)
integration and are entirely optional.
* `vault`: The top-level config key used to contain all Vault-related
configuration options. The value is a key-value map which supports the
following keys:
<br>
* `enabled`: A boolean option that enables or disables Vault integration.
Defaults to `false`.
* `address`: The address to the Vault server given in the format of
`protocol://host:port`. Defaults to `https://vault.service.consul:8200`.
* `token`: Token is used by Servers to derive child token's for jobs
requesting tokens. As such it does not need to be specified by the Client.
Visit the [Vault Integration](/docs/vault-integration/index.html)
documentation to see how to generate an appropriate token. The VAULT_TOKEN
environment variable is used when starting the agent. If a flag or
configuration specifies a value they take precedence.
* `allow_unauthenticated`: allows users to submit jobs requiring Vault tokens
without providing a Vault token proving they have access to these policies.
* `task_token_ttl`: Sets the TTL of created tokens when using a root token.
* `tls_ca_file`: Optional path to the CA certificate used for Vault
communication, defaults to the system bundle if not specified.
* `tls_ca_path`: Optional path to a folder containing CA certificate to be
used for Vault communication, defaults to the system bundle if not
specified.
* `tls_cert_file`: The path to the certificate used for Vault communication. If
this is set then you need to also set `tls_key_file`.
* `tls_key_file`: The path to the private key used for Consul communication. If
this is set then you need to also set `tls_cert_file`.
* `tls_skip_verify`: Enables or disables SSL verifaction. Defaults to `false`.
* `tls_server_name`: Optional parameter used to set the SNI host when
connecting to Vault via TLS.
## <a id="atlas_options"></a>Atlas Options
**NOTE**: Nomad integration with Atlas is awaiting release of Atlas features
for Nomad support. Nomad currently only validates configuration options for
Atlas but does not use them.
See [#183](https://github.com/hashicorp/nomad/issues/183) for more details.
The following options are used to configure [Atlas](https://atlas.hashicorp.com)
integration and are entirely optional.
* `atlas`: The top-level config key used to contain all Atlas-related
configuration options. The value is a key-value map which supports the
following keys:
<br>
* <a id="infrastructure">`infrastructure`</a>: The Atlas infrastructure name to
connect this agent to. This value should be of the form
`<org>/<infrastructure>`, and requires a valid [token](#token) authorized on
the infrastructure.
* <a id="token">`token`</a>: The Atlas token to use for authentication. This
token should have access to the provided [infrastructure](#infrastructure).
* <a id="join">`join`</a>: A boolean indicating if the auto-join feature of
Atlas should be enabled. Defaults to `false`.
* `endpoint`: The address of the Atlas instance to connect to. Defaults to the
public Atlas endpoint and is only used if both
[infrastructure](#infrastructure) and [token](#token) are provided.
## <a id="tls_options"></a>TLS Options
The following options are used to configure TLS for the RPC, Raft and HTTP
traffic for Nomad
* `tls`: The top-level config key used to contain all TLS-related
configuration options. The value is a key-value map which supports the
following keys:
<br>
* `http`: Setting this to `true` enables TLS for the HTTP endpoints on the
Nomad Agent. Default is `false`.
* `rpc`: Setting this to `true` enables TLS for the RPC endpoints and the Raft
traffic in Nomad Servers. Setting this to `true` on Nomad client makes the
client use TLS for making RPC requests to the Nomad servers. Default is
`false`.
* `verify_server_hostname`: Setting this to true causes the outgoing TLS
connections to verify the server's hostname. Default is `false`.
* `ca_file`: Path to the CA certificate used for Nomad's TLS configuration.
* `cert_file`: Path to the Cert file used for Nomad's TLS configuration.
* `key_file`: Path to the Key file used for Nomad's TLS configuration.
Incorrect configuration of the TLS related configuration will result to
startup errors of the Nomad agent.
Please see the [Agent's Gossip and RPC
Encryption](/docs/agent/encryption.html) documentation for how certificates
should be signed.
## Server-specific Options
The following options are applicable to server agents only and need not be
configured on client nodes.
* `server`: This is the top-level key used to define the Nomad server
configuration. It is a key-value mapping which supports the following keys:
<br>
* `enabled`: A boolean indicating if server mode should be enabled for the
local agent. All other server options depend on this value being set.
Defaults to `false`.
* <a id="bootstrap_expect">`bootstrap_expect`</a>: This is an integer
representing the number of server nodes to wait for before bootstrapping. It
is most common to use the odd-numbered integers `3` or `5` for this value,
depending on the cluster size. A value of `1` does not provide any fault
tolerance and is not recommended for production use cases.
* `data_dir`: This is the data directory used for server-specific data,
including the replicated log. By default, this directory lives inside of the
[data_dir](#data_dir) in the "server" sub-path.
* `protocol_version`: The Nomad protocol version spoken when communicating
with other Nomad servers. This value is typically not required as the agent
internally knows the latest version, but may be useful in some upgrade
scenarios.
* `num_schedulers`: The number of parallel scheduler threads to run. This
can be as many as one per core, or `0` to disallow this server from making
any scheduling decisions. This defaults to the number of CPU cores.
* `enabled_schedulers`: This is an array of strings indicating which
sub-schedulers this server will handle. This can be used to restrict the
evaluations that worker threads will dequeue for processing. This
defaults to all available schedulers.
* `node_gc_threshold` This is a string with a unit suffix, such as "300ms",
"1.5h" or "25m". Valid time units are "ns", "us" (or "µs"), "ms", "s",
"m", "h". Controls how long a node must be in a terminal state before it is
garbage collected and purged from the system.
* <a id="rejoin_after_leave">`rejoin_after_leave`</a> When provided, Nomad will ignore a previous leave and
attempt to rejoin the cluster when starting. By default, Nomad treats leave
as a permanent intent and does not attempt to join the cluster again when
starting. This flag allows the previous state to be used to rejoin the
cluster.
* <a id="retry_join">`retry_join`</a> Similar to [`start_join`](#start_join) but allows retrying a join
if the first attempt fails. 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.
* <a id="retry_interval">`retry_interval`</a> The time to wait between join attempts. Defaults to 30s.
* <a id="retry_max">`retry_max`</a> 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.
* <a id="start_join">`start_join`</a> An array of strings specifying addresses
of nodes to join upon startup. If Nomad is unable to join with any of the
specified addresses, agent startup will fail. By default, the agent won't
join any nodes when it starts up. Addresses can be given as an IP, a domain
name, or an IP:Port pair. If the port isn't specified the default Serf port,
4648, is used. DNS names may also be used.
* <a id="encrypt">`encrypt`</a> Specifies the secret key to use for encryption
of Nomad server's gossip network traffic. This key must be 16-bytes that are
Base64-encoded. The easiest way to create an encryption key is to use nomad
keygen. All the servers within a cluster must share the same encryption key
to communicate. The provided key is automatically persisted to the data
directory and loaded automatically whenever the agent is restarted. This
means that to encrypt Nomad server's gossip protocol, this option only needs
to be provided once on each agent's initial startup sequence. If it is
provided after Nomad has been initialized with an encryption key, then the
provided key is ignored and a warning will be displayed.
## Client-specific Options
The following options are applicable to client agents only and need not be
configured on server nodes.
* `client`: This is the top-level key used to define the Nomad client
configuration. Like the server configuration, it is a key-value mapping which
supports the following keys:
<br>
* `enabled`: A boolean indicating if client mode is enabled. All other client
configuration options depend on this value. Defaults to `false`.
* <a id="state_dir">`state_dir`</a>: This is the state dir used to store
client state. By default, it lives inside of the [data_dir](#data_dir), in
the "client" sub-path. It must be specified as an absolute path.
* <a id="alloc_dir">`alloc_dir`</a>: A directory used to store allocation data.
Depending on the workload, the size of this directory can grow arbitrarily
large as it is used to store downloaded artifacts for drivers (QEMU images,
JAR files, etc.). It is therefore important to ensure this directory is
placed some place on the filesystem with adequate storage capacity. By
default, this directory lives under the [data_dir](#data_dir) at the
"alloc" sub-path. It must be specified as an absolute path.
* <a id="servers">`servers`</a>: An array of server addresses. This list is
used to register the client with the server nodes and advertise the
available resources so that the agent can receive work. If a port is not specified
in the array of server addresses, the default port `4647` will be used.
* <a id="node_class">`node_class`</a>: A string used to logically group client
nodes by class. This can be used during job placement as a filter. This
option is not required and has no default.
* <a id="meta">`meta`</a>: This is a key-value mapping of metadata pairs. This
is a free-form map and can contain any string values.
* <a id="options">`options`</a>: This is a key-value mapping of internal
configuration for clients, such as for driver configuration. Please see
[here](#options_map) for a description of available options.
* <a id="chroot_env">`chroot_env`</a>: This is a key-value mapping that
defines the chroot environment for jobs using the Exec and Java drivers.
Please see [here](#chroot_env_map) for an example and further information.
* <a id="network_interface">`network_interface`</a>: This is a string to force
network fingerprinting to use a specific network interface
* <a id="network_speed">`network_speed`</a>: This is an int that sets the
default link speed of network interfaces, in megabits, if their speed can
not be determined dynamically.
* `max_kill_timeout`: `max_kill_timeout` is a time duration that can be
specified using the `s`, `m`, and `h` suffixes, such as `30s`. If a job's
task specifies a `kill_timeout` greater than `max_kill_timeout`,
`max_kill_timeout` is used. This is to prevent a user being able to set an
unreasonable timeout. If unset, a default is used.
<a id="reserved"></a>
* `reserved`: `reserved` is used to reserve a portion of the node's resources
from being used by Nomad when placing tasks. It can be used to target
a certain capacity usage for the node. For example, 20% of the node's CPU
could be reserved to target a CPU utilization of 80%. The block has the
following format:
```
reserved {
cpu = 500
memory = 512
disk = 1024
reserved_ports = "22,80,8500-8600"
}
```
* `cpu`: `cpu` is given as MHz to reserve.
* `memory`: `memory` is given as MB to reserve.
* `disk`: `disk` is given as MB to reserve.
* `reserved_ports`: `reserved_ports` is a comma-separated list of ports
to reserve on all fingerprinted network devices. Ranges can be
specified by using a hyphen separated the two inclusive ends.
### <a id="options_map"></a>Client Options Map
The following is not an exhaustive list of options that can be passed to the
Client, but rather the set of options that configure the Client and not the
drivers. To find the options supported by an individual driver, see the drivers
documentation [here](/docs/drivers/index.html)
* `driver.whitelist`: A comma-separated list of whitelisted drivers (e.g.
"docker,qemu"). If specified, drivers not in the whitelist will be disabled.
If the whitelist is empty, all drivers are fingerprinted and enabled where
applicable.
* `env.blacklist`: Nomad passes the host environment variables to `exec`,
`raw_exec` and `java` tasks. `env.blacklist` is a comma-separated list of
environment variable keys not to pass to these tasks. If specified, the
defaults are overridden. The following are the default:
* `CONSUL_TOKEN`
* `VAULT_TOKEN`
* `ATLAS_TOKEN`
* `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
* `GOOGLE_APPLICATION_CREDENTIALS`
* `user.blacklist`: An operator specifiable blacklist of users which a task is
not allowed to run as when using a driver in `user.checked_drivers`.
Defaults to:
* `root`
* `Administrator`
* `user.checked_drivers`: An operator specifiable list of drivers to enforce
the `user.blacklist`. For drivers using containers, this enforcement often
doesn't make sense and as such the default is set to:
* `exec`
* `qemu`
* `java`
* `fingerprint.whitelist`: A comma-separated list of whitelisted fingerprinters.
If specified, fingerprinters not in the whitelist will be disabled. If the
whitelist is empty, all fingerprinters are used.
### <a id="chroot_env_map"></a>Client Chroot Map
Drivers based on [Isolated Fork/Exec](/docs/drivers/exec.html) implement file
system isolation using chroot on Linux. The `chroot_env` map allows the chroot
environment to be configured using source paths on the host operating system.
The mapping format is: `source_path -> dest_path`.
The following example specifies a chroot which contains just enough to run the
`ls` utility, and not much else:
```
chroot_env {
"/bin/ls" = "/bin/ls"
"/etc/ld.so.cache" = "/etc/ld.so.cache"
"/etc/ld.so.conf" = "/etc/ld.so.conf"
"/etc/ld.so.conf.d" = "/etc/ld.so.conf.d"
"/lib" = "/lib"
"/lib64" = "/lib64"
}
```
When `chroot_env` is unspecified, the `exec` driver will use a default chroot
environment with the most commonly used parts of the operating system. See
`exec` documentation for the full list [here](/docs/drivers/exec.html#chroot).
## <a id="cli"></a>Command-line Options
A subset of the available Nomad agent configuration can optionally be passed in
via CLI arguments. The `agent` command accepts the following arguments:
* `-alloc-dir=<path>`: Equivalent to the Client [alloc_dir](#alloc_dir) config
option.
* `-atlas=<infrastructure>`: Equivalent to the Atlas
[infrastructure](#infrastructure) config option.
* `-atlas-join`: Equivalent to the Atlas [join](#join) config option.
* `-atlas-token=<token>`: Equivalent to the Atlas [token](#token) config option.
* `-bind=<address>`: Equivalent to the [bind_addr](#bind_addr) config option.
* `-bootstrap-expect=<num>`: Equivalent to the
[bootstrap_expect](#bootstrap_expect) config option.
* `-client`: Enable client mode on the local agent.
* `-config=<path>`: Specifies the path to a configuration file or a directory of
configuration files to load. Can be specified multiple times.
* `-data-dir=<path>`: Equivalent to the [data_dir](#data_dir) config option.
* `-dc=<datacenter>`: Equivalent to the [datacenter](#datacenter) config option.
* `-dev`: Start the agent in development mode. This enables a pre-configured
dual-role agent (client + server) which is useful for developing or testing
Nomad. No other configuration is required to start the agent in this mode.
* `-join=<address>`: Address of another agent to join upon starting up. This can
be specified multiple times to specify multiple agents to join.
* `-log-level=<level>`: Equivalent to the [log_level](#log_level) config option.
* `-meta=<key=value>`: Equivalent to the Client [meta](#meta) config option.
* `-network-interface=<interface>`: Equivalent to the Client
[network_interface](#network_interface) config option.
* `-network-speed=<MBits>`: Equivalent to the Client
[network_speed](#network_speed) config option.
* `-node=<name>`: Equivalent to the [name](#name) config option.
* `-node-class=<class>`: Equivalent to the Client [node_class](#node_class)
config option.
* `-region=<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-max`: Similar to the [retry_max](#retry_max) config option.
* `-server`: Enable server mode on the local agent.
* `-servers=<host:port>`: Equivalent to the Client [servers](#servers) config
option.
* `-state-dir=<path>`: Equivalent to the Client [state_dir](#state_dir) config
option.
* `-vault-enabled`: Whether to enable or disabled Vault integration.
* `-vault-address=<addr>`: The address to communicate with Vault.
* `-vault-token=<token>`: The Vault token used to derive tokens. Only needs to
be set on Servers. Overrides the Vault token read from the VAULT_TOKEN
environment variable.
* `-vault-ca-file=<path>`: Path to a PEM-encoded CA cert file used to verify the
Vault server SSL certificate.
* `-vault-ca-path=<path>`: Path to a directory of PEM-encoded CA cert files used
to verify the Vault server SSL certificate.Whether to enable or disabled Vault
integration.
* `vault-cert-file=<path>`: The path to the certificate for Vault communication.
* `vault-key-file=<path>`: The path to the private key for Vault communication.
* `vault-tls-skip-verify`: A boolean that determines whether to skip SSL
certificate verification.
* `vault-tls-server-name=<name>`: Used to set the SNI host when connecting to
Vault over TLS.

85
website/source/docs/agent/configuration/atlas.html.md Normal file
View File

@@ -0,0 +1,85 @@
---
layout: "docs"
page_title: "atlas Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-atlas"
description: |-
The `atlas` stanza configures Nomad's integration with HashiCorp's Atlas and
Nomad Enterprise.
---
# `atlas` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**atlas**</code>
</td>
</tr>
</table>
The `atlas` stanza configures Nomad's integration with
[HashiCorp's Atlas][atlas] and Nomad Enterprise.
```hcl
atlas {
infrastructure = "hashicorp/example"
join = true
}
```
~> Nomad integration with Atlas is **currently in private beta** and only
available to select users. As the functionality becomes more widely available,
additional examples and documented will be listed here.
## `atlas` Parameters
- `endpoint` `(string: "https://atlas.hashicorp.com")` - Specifies the address
of the Atlas service to connect.
- `infrastructure` `(string: <required>)` - Specifies the name of the Atlas
infrastructure to connect the agent. This should be of the form
`<organization>/<infrastructure>`, and requires a valid `token`
- `join` `(bool: false)` - Specifies if the auto-join functionality should be
enabled.
- `token` `(string: <required>)` - Specifies the Atlas token to use for
authentication. This token must have access to the provided `infrastructure`.
This can also optionally be specified using the `ATLAS_TOKEN` environment
variable.
## `atlas` Examples
The following examples only show the `atlas` stanzas. Remember that the
`atlas` stanza is only valid in the placements listed above.
### Nomad Enterprise SaaS
This example connects to the public Nomad Enterprise service to the
infrastructure named "hashicorp/example". The provided token must have
permissions to manage the infrastructure or access will be denied.
```hcl
atlas {
infrastructure = "hashicorp/example"
token = "abcd.atlasv1.efghi...."
join = true
}
```
### On-Premise Nomad Enterprise
This example connects to a custom Nomad Enterprise server, such as an on-premise
installation.
```hcl
atlas {
endpoint = "https://corp.atlas.local/"
infrastructure = "acme/example"
join = true
}
```
[atlas]: https://atlas.hashicorp.com/ "Atlas by HashiCorp"

278
website/source/docs/agent/configuration/client.html.md Normal file
View File

@@ -0,0 +1,278 @@
---
layout: "docs"
page_title: "client Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-client"
description: |-
The "client" stanza configures the Nomad agent to accept jobs as assigned by
the Nomad server, join the cluster, and specify driver-specific configuration.
---
# `client` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**client**</code>
</td>
</tr>
</table>
The `client` stanza configures the Nomad agent to accept jobs as assigned by
the Nomad server, join the cluster, and specify driver-specific configuration.
```hcl
client {
enabled = true
servers = ["1.2.3.4:4647", "5.6.7.8:4647"]
}
```
## `client` Parameters
- `alloc_dir` `(string: "[data_dir]/alloc")` - Specifies the directory to use
to allocation data. By default, this is - the top-level
[data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with
"alloc", like `"/opt/nomad/alloc"`. This must be an absolute path
- `chroot_env` <code>([ChrootEnv](#chroot_env-parameters): nil)</code> - Specififes
a key-value mapping that defines the chroot environment for jobs using the
Exec and Java drivers.
- `enabled` `(bool: false)` - Specifies if client mode is enabled. All other
client configuration options depend on this value.
- `max_kill_timeout` `(string: "30s")` - Specifies the maximum amount of time a
job is allowed to wait to exit. Individual jobs may customize their own kill
timeout, but it may not exceed this value.
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `network_interface` `(string: "lo | lo0")` - Specifies the name of the
interface to force network fingerprinting on. This defaults to the loopback
interface.
- `network_speed` `(int: 100)` - Specifies the default link speed of network
interfaces, in megabits. Most clients can determine their speed automatically,
but will fallback to this value if they cannot.
- `node_class` `(string: "")` - Specifies an arbitrary string used to logically
group client nodes by user-defined class. This can be used during job
placement as a filter.
- `options` <code>([Options](#options-parameters): nil)</code> - Specifies a
key-value mapping of internal configuration for clients, such as for driver
configuration.
- `reserved` <code>([Reserved](#reserved-parameters): nil)</code> - Specifies
that Nomad should reserve a portion of the node's resources from receiving
tasks. This can be used to target a certain capacity usage for the node. For
example, 20% of the node's CPU could be reserved to target a CPU utilization
of 80%.
- `servers` `(array<string>: [])` - Specifies an array of addresses to the Nomad
servers this client should join. This list is used to register the client with
the server nodes and advertise the available resources so that the agent can
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.
- `state_dir` `(string: "[data_dir]/client")` - Specifies the directory to use
to store client state. By default, this is - the top-level
[data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with
"client", like `"/opt/nomad/client"`. This must be an absolute path.
### `chroot_env` Parameters
Drivers based on [isolated fork/exec](/docs/drivers/exec.html) implement file
system isolation using chroot on Linux. The `chroot_env` map allows the chroot
environment to be configured using source paths on the host operating system.
The mapping format is:
```text
source_path -> dest_path
```
The following example specifies a chroot which contains just enough to run the
`ls` utility:
```hcl
client {
chroot_env {
"/bin/ls" = "/bin/ls"
"/etc/ld.so.cache" = "/etc/ld.so.cache"
"/etc/ld.so.conf" = "/etc/ld.so.conf"
"/etc/ld.so.conf.d" = "/etc/ld.so.conf.d"
"/lib" = "/lib"
"/lib64" = "/lib64"
}
}
```
When `chroot_env` is unspecified, the `exec` driver will use a default chroot
environment with the most commonly used parts of the operating system. Please
see the [Nomad `exec` driver documentation](/docs/drivers/exec.html#chroot) for
the full list.
### `options` Parameters
The following is not an exhaustive list of options for **only** the Nomad
client. To find the options supported by each individual Nomad driver, please
see the [drivers documentation](/docs/drivers/index.html).
- `"driver.whitelist"` `(string: "")` - Specifies a comma-separated list of
whitelisted drivers . If specified, drivers not in the whitelist will be
disabled. If the whitelist is empty, all drivers are fingerprinted and enabled
where applicable.
```hcl
client {
options = {
"driver.whitelist" = "docker,qemu"
}
}
```
- `"env.blacklist"` `(string: see below)` - Specifies a comma-separated list of
environment variable keys not to pass to these tasks. Nomad passes the host
environment variables to `exec`, `raw_exec` and `java` tasks. If specified,
the defaults are overridden. If a value is provided, **all** defaults are
overridden (they are not merged).
```hcl
client {
options = {
"env.blacklist" = "MY_CUSTOM_ENVVAR"
}
}
```
The default list is:
```text
CONSUL_TOKEN
VAULT_TOKEN
ATLAS_TOKEN
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
GOOGLE_APPLICATION_CREDENTIALS
```
- `"user.blacklist"` `(string: see below)` - Specifies a comma-separated
blacklist of usernames for which a task is not allowed to run. This only
applies if the driver is included in `"user.checked_drivers"`. If a value is
provided, **all** defaults are overridden (they are not merged).
```hcl
client {
options = {
"user.blacklist" = "root,ubuntu"
}
}
```
The default list is:
```text
root
Administrator
```
- `"user.checked_drivers"` `(string: see below)` - Specifies a comma-separated
list of drivers for which to enforce the `"user.blacklist"`. For drivers using
containers, this enforcement is usually unnecessary. If a value is provided,
**all** defaults are overridden (they are not merged).
```hcl
client {
options = {
"user.checked_drivers" = "exec,raw_exec"
}
}
```
The default list is:
```text
exec
qemu
java
```
- `"fingerprint.whitelist"` `(string: "")` - Specifies a comma-separated list of
whitelisted fingerprinters. If specified, any fingerprinters not in the
whitelist will be disabled. If the whitelist is empty, all fingerprinters are
used.
```hcl
client {
options = {
"fingerprint.whitelist" = "network"
}
}
```
### `reserved` Parameters
- `cpu` `(int: 0)` - Specifies the amount of CPU to reserve, in MHz.
- `memory` `(int: 0)` - Specifies the amount of memory to reserve, in MB.
- `disk` `(int: 0)` - Specifies the amount of disk to reserve, in MB.
- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to
reserve on all fingerprinted network devices. Ranges can be specified by using
a hyphen separated the two inclusive ends.
## `client` Examples
### Common Setup
This example shows the most basic configuration for a Nomad client joined to a
cluster.
```hcl
client {
enabled = true
servers = ["1.2.3.4:4647", "5.6.7.8:4647"]
}
```
### Reserved Resources
This example shows a sample configuration for reserving resources to the client.
This is useful if you want to allocate only a portion of the client's resources
to jobs.
```hcl
client {
enabled = true
reserved {
cpu = 500
memory = 512
disk = 1024
reserved_ports = "22,80,8500-8600"
}
}
```
### Custom Metadata, Network Speed, and Node Class
This example shows a client configuration which customizes the metadata, network
speed, and node class.
```hcl
client {
enabled = true
network_speed = 500
node_class = "prod"
meta {
"owner" = "ops"
}
}
```
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"

146
website/source/docs/agent/configuration/consul.html.md Normal file
View File

@@ -0,0 +1,146 @@
---
layout: "docs"
page_title: "consul Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-consul"
description: |-
The "consul" stanza configures the Nomad agent's communication with
Consul for service discovery and key-value integration. When
configured, tasks can register themselves with Consul, and the Nomad cluster
can automatically bootstrap itself.
---
# `consul` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**consul**</code>
</td>
</tr>
</table>
The `consul` stanza configures the Nomad agent's communication with
[Consul][consul] for service discovery and key-value integration. When
configured, tasks can register themselves with Consul, and the Nomad cluster can
[automatically bootstrap][bootstrap] itself.
```hcl
consul {
address = "127.0.0.1:8500"
auth = "admin:password"
token = "abcd1234"
}
```
A default `consul` stanza is automatically merged with all Nomad agent
configurations. These sane defaults automatically enable Consul integration if
Consul is detected on the system. This allows for seamless bootstrapping of the
cluster with zero configuration. To put it another way: if you have a Consul
agent running on the same host as the Nomad agent with the default
configuration, Nomad will automatically connect and configure with Consul.
## `consul` Parameters
- `address` `(string: "127.0.0.1:8500")` - Specifies the address to the local
Consul agent, given in the format `host:port`.
- `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
use for access to the Consul Agent, given in the format `username:password`.
- `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
services in Consul. The services are named according to `server_service_name`
and `client_service_name`. Nomad servers and clients advertise their
respective services, each tagged appropriately with either `http` or `rpc`
tag. Nomad servers also advertise a `serf` tagged service.
- `ca_file` `(string: "")` - Specifies an optional path to the CA certificate
used for Consul communication. This defaults to the system bundle if
unspecified.
- `cert_file` `(string: "")` - Specifies the path to the certificate used for
Consul communication. If this is set then you need to also set `key_file`.
- `checks_use_advertise` `(bool: false)` - Specifies if Consul heath checks
should bind to the advertise address. By default, this is the bind address.
- `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should
automatically discover servers in the same region by searching for the Consul
service name defined in the `server_service_name` option. The search occurs if
the client is not registered with any servers or it is unable to heartbeat to
the leader of the region, in which case it may be partitioned and searches for
other servers.
- `client_service_name` `(string: "nomad-client")` - Specifies the name of the
service in Consul for the Nomad clients.
- `key_file` `(string: "")` - Specifies the path to the private key used for
Consul communication. If this is set then you need to also set `cert_file`.
- `server_service_name` `(string: "nomad")` - Specifies the name of the service
in Consul for the Nomad servers.
- `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
automatically discover and join other Nomad servers by searching for the
Consul service name defined in the `server_service_name` option. This search
only happens if the server does not have a leader.
- `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
communicate with the Consul agent.
- `token` `(string: "")` - Specifies the token used to provide a per-request ACL
token. This option overrides the Consul Agent's default token.
- `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
when communicating to the Consul API client over HTTPS
If the local Consul agent is configured and accessible by the Nomad agents, the
Nomad cluster will [automatically bootstrap][bootstrap] provided
`server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
(which is the default).
## `consul` Examples
### Default
This example shows the default Consul integration:
```hcl
```
That is not a mistake - it is intentionally empty. If a local Consul agent is
running at the default address, Nomad will automatically connect and use the
default values listed above.
### Custom Address and Port
This example shows pointing the Nomad agent at a different Consul address. Note
that you should **never** point directly at a Consul server; always point to a
local client. In this example, the Consul server is bound and listening on the
node's private IP address instead of localhost, so we use that:
```hcl
consul {
address = "10.0.2.4:8500"
}
```
### Custom SSL
This example shows configuring custom SSL certificates to communicate with
the Consul agent. The Consul agent should be configured to accept certificates
similarly, but that is not discussed here:
```hcl
consul {
ssl = true
ca_file = "/var/ssl/bundle/ca.bundle"
cert_file = "/etc/ssl/consul.crrt"
key_file = "/etc/ssl/consul.key"
}
```
[consul]: https://www.consul.io/ "Consul by HashiCorp"
[bootstrap]: /docs/cluster/automatic.html "Automatic Bootstrapping"

254
website/source/docs/agent/configuration/index.html.md Normal file
View File

@@ -0,0 +1,254 @@
---
layout: "docs"
page_title: "Agent Configuration"
sidebar_current: "docs-agent-configuration"
description: |-
Learn about the configuration options available for the Nomad agent.
---
# Agent Configuration
Nomad agents have a variety of parameters that can be specified via
configuration files or command-line flags. Configuration files are written in
[HCL][hcl]. Nomad can read and combine parameters from multiple configuration
files or directories to configure the Nomad agent.
## Load Order and Merging
The Nomad agent supports multiple configuration files, which can be provided
using the `-config` CLI flag. The flag can accept either a file or folder:
```shell
$ nomad agent -config=server.conf -config=/etc/nomad -config=extra.json
```
This will load configuration from `server.conf`, from `.hcl` and `.json` files
under `/etc/nomad`, and finally from `extra.json`. Files are loaded and merged
in lexicographical order. Directories are not loaded recursively.
As each file is processed, its contents are merged into the existing
configuration. When merging, any non-empty values from the latest config file
will append or replace parameters in the current configuration. An empty value
means `""` for strings, `0` for integer or float values, and `false` for
booleans. Since empty values are ignored you cannot disable an parameter like
`server` mode once you've enabled it.
Here is an example Nomad agent configuration that runs in both client and server
mode.
```hcl
bind_addr = "0.0.0.0"
data_dir = "/var/lib/nomad"
advertise {
# We need to specify our host's IP because we can't
# advertise 0.0.0.0 to other nodes in our cluster.
rpc = "1.2.3.4:4647"
}
server {
enabled = true
bootstrap_expect = 3
}
client {
enabled = true
network_speed = 10
options {
"driver.raw_exec.enable" = "1"
}
}
consul {
address = "1.2.3.4:8500"
}
atlas {
infrastructure = "hashicorp/mars"
token = "atlas.v1.AFE84330943"
}
```
~> Note that it is strongly recommended **not** to operate a node as both
`client` and `server`, although this is supported to simplify development and
testing.
## General Parameters
- `addresses` `(Addresses: see below)` - Specifies the bind address for
individual network services. Any values configured in this stanza take
precedence over the default [bind_addr](#bind_addr). If provided, **all
network addresses must be defined** (you cannot override just one address).
- `http` - The address the HTTP server is bound to. This is the most common
bind address to change.
- `rpc` - The address to bind the internal RPC interfaces to. Should be
exposed only to other cluster members if possible.
- `serf` - The address used to bind the gossip layer to. Both a TCP and UDP
listener will be exposed on this address. Should be restricted to only
server nodes from the same datacenter if possible.
The default values are:
```hcl
ports {
http = "127.0.0.1"
rpc = "127.0.0.1"
serf = "127.0.0.1"
}
```
- `advertise` `(Advertise: see below)` - Specifies the advertise address for
individual network services. This can be used to advertise a different address
to the peers of a server or a client node to support more complex network
configurations such as NAT. This configuration is optional, and defaults to
the bind address of the specific network service if it is not provided. If
provided, **all advertise addresses must be defined** (you cannot override
just one property).
- `http` - The address to advertise for the HTTP interface. This should be
reachable by all the nodes from which end users are going to use the Nomad
CLI tools.
- `rpc` - The address to advertise for the RPC interface. This address should
be reachable by all of the agents in the cluster.
- `serf` - The address advertised for the gossip layer. This address must be
reachable from all server nodes. It is not required that clients can reach
this address.
The default values are:
```hcl
advertise {
http = "127.0.0.1:4646"
rpc = "127.0.0.1:4647"
serf = "127.0.0.1:4648"
}
```
- `atlas` <code>([Atlas][atlas]: nil)</code> - Specifies if Nomad should connect
to Nomad Enterprise and Atlas.
- `bind_addr` `(string: "127.0.0.1")` - Specifies which address the Nomad
agent should bind to for network services, including the HTTP interface as
well as the internal gossip protocol and RPC mechanism. This should be
specified in IP format, and can be used to easily bind all network services to
the same address. It is also possible to bind the individual services to
different addresses using the [addresses](#addresses) configuration option.
- `client` <code>([Client][client]: nil)</code> - Specifies configuration which is specific to the Nomad client.
- `consul` <code>([Consul][consul]: nil)</code> - Specifies configuration for
connecting to Consul.
- `datacenter` `(string: "dc1")` - Specifies the data center of the local agent.
All members of a datacenter should share a local LAN connection.
- `data_dir` `(string: required)` - Specifies a local directory used to store
agent state. Client nodes use this directory by default to store temporary
allocation data as well as cluster information. Server nodes use this
directory to store cluster state, including the replicated log and snapshot
data. This must be specified as an absolute path.
- `disable_anonymous_signature` `(bool: false)` - Specifies if Nomad should
provide an anonymous signature for de-duplication with the update check.
- `disable_update_check` `(bool: false)` - Specifies if Nomad should not check for updates and security bulletins.
- `enable_debug` `(bool: false)` - Specifies if the debugging HTTP endpoints
should be enabled. These endpoints can be used with profiling tools to dump
diagnostic information about Nomad's internals. It is not recommended to leave
this enabled in production environments.
- `enable_syslog` `(bool: false)` - Specifies if the agent should log to syslog.
This option only works on Unix based systems.
- `http_api_response_headers` `(map<string|string>: nil)` - Specifies
user-defined headers to add to the HTTP API responses.
- `leave_on_interrupt` `(bool: false)` - Specifies if the agent should
gracefully leave when receiving the interrupt signal. By default, the agent
will exit forcefully on any signal.
- `leave_on_terminate` `(bool: false)` - Specifies if the agent should
gracefully leave when receiving the terminate signal. By default, the agent
will exit forcefully on any signal.
- `log_level` `(string: "INFO")` - Specifies the verbosity of logs the Nomad
agent will output. Valid log levels include `WARN`, `INFO`, or `DEBUG` in
increasing order of verbosity.
- `name` `(string: [hostname])` - Specifies the name of the local node. This
value is used to identify individual nodes in a given datacenter and must be
unique per-datacenter.
- `ports` `(Port: see below)` - Specifies the network ports used for different
services required by the Nomad agent. If provided, **all network ports must
be defined** (you cannot override just one port).
- `http` - The port used to run the HTTP server.
- `rpc` - The port used for internal RPC communication between
agents and servers, and for inter-server traffic for the consensus algorithm
(raft).
- `serf` - The port used for the gossip protocol for cluster
membership. Both TCP and UDP should be routable between the server nodes on
this port.
The default values are:
```hcl
ports {
http = 4646
rpc = 4647
serf = 4648
}
```
- `region` `(string: "global")` - Specifies the region the Nomad agent is a
member of. A region typically maps to a geographic region, for example `us`,
with potentially multiple zones, which map to [datacenters](#datacenter) such
as `us-west` and `us-east`.
- `server` <code>([Server][server]: nil)</code> - Specifies configuration which is specific to the Nomad server.
- `syslog_facility` `(string: "LOCAL0")` - Specifies the syslog facility to write to. This has no effect unless `enable_syslog` is true.
- `tls` <code>([TLS][tls]: nil)</code> - Specifies configuration for TLS.
- `vault` <code>([Vault][vault]: nil)</code> - Specifies configuration for
connecting to Vault.
## Examples
### Custom Region and Datacenter
This example shows configuring a custom region and data center for the Nomad
agent:
```hcl
region = "europe"
datacenter = "ams"
```
### Enable CORS
This example shows how to enable CORS on the HTTP API endpoints:
```hcl
http_api_response_headers {
"Access-Control-Allow-Origin" = "*"
}
```
[hcl]: https://github.com/hashicorp/hcl "HashiCorp Configuration Language"
[consul]: /docs/agent/configuration/consul.html "Nomad Agent consul Configuration"
[atlas]: /docs/agent/configuration/atlas.html "Nomad Agent atlas Configuration"
[vault]: /docs/agent/configuration/vault.html "Nomad Agent vault Configuration"
[tls]: /docs/agent/configuration/tls.html "Nomad Agent tls Configuration"
[client]: /docs/agent/configuration/client.html "Nomad Agent client Configuration"
[server]: /docs/agent/configuration/server.html "Nomad Agent server Configuration"

183
website/source/docs/agent/configuration/server.html.md Normal file
View File

@@ -0,0 +1,183 @@
---
layout: "docs"
page_title: "server Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-server"
description: |-
The "server" stanza configures the Nomad agent to operate in server mode to
participate in scheduling decisions, register with service discovery, handle
join failures, and more.
---
# `server` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**server**</code>
</td>
</tr>
</table>
The `server` stanza configures the Nomad agent to operate in server mode to
participate in scheduling decisions, register with service discovery, handle
join failures, and more.
```hcl
server {
enabled = true
bootstrap_expect = 5
retry_join = ["1.2.3.4", "5.6.7.8"]
}
```
## `server` Parameters
- `bootstrap_expect` `(int: required)` - Specifies the number of server nodes to
wait for before bootstrapping. It is most common to use the odd-numbered
integers `3` or `5` for this value, depending on the cluster size. A value of
`1` does not provide any fault tolerance and is not recommended for production
use cases.
- `data_dir` `(string: "[data_dir]/server")` - Specifies the directory to use -
for server-specific data, including the replicated log. By default, this is -
the top-level [data_dir](/docs/agent/configuration/index.html#data_dir)
suffixed with "server", like `"/opt/nomad/server"`. This must be an absolute
path.
- `enabled` `(bool: false)` - Specifies if this agent should run in server mode.
All other server options depend on this value being set.
- `enabled_schedulers` `(array<string>: [all])` - Specifies which sub-schedulers
this server will handle. This can be used to restrict the evaluations that
worker threads will dequeue for processing.
- `encrypt` `(string: "")` - Specifies the secret key to use for encryption of
Nomad server's gossip network traffic. This key must be 16-bytes that are
base64-encoded. The provided key is automatically persisted to the data
directory and loaded automatically whenever the agent is restarted. This means
that to encrypt Nomad server's gossip protocol, this option only needs to be
provided once on each agent's initial startup sequence. If it is provided
after Nomad has been initialized with an encryption key, then the provided key
is ignored and a warning will be displayed. See the
[Nomad encryption documentation][encryption] for more details on this option
and its impact on the cluster.
- `node_gc_threshold` `(string: "24h")` - Specifies how long a node must be in a
terminal state before it is garbage collected and purged from the system. This
is specified using a label suffix like "30s" or "1h".
- `num_schedulers` `(int: [num-cores])` - Specifies the number of parallel
scheduler threads to run. This can be as many as one per core, or `0` to
disallow this server from making any scheduling decisions. This defaults to
the number of CPU cores.
- `protocol_version` `(int: 1)` - Specifies the Nomad protocol version to use
when communicating with other Nomad servers. This value is typically not
required as the agent internally knows the latest version, but may be useful
in some upgrade scenarios.
- `rejoin_after_leave` `(bool: false)` - Specifies if Nomad will ignore a
previous leave and attempt to rejoin the cluster when starting. By default,
Nomad treats leave as a permanent intent and does not attempt to join the
cluster again when starting. This flag allows the previous state to be used to
rejoin the cluster.
- `retry_join` `(array<string>: [])` - 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. 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**. See the [server address format](#server-address-format)
section for more information on the format of the string.
- `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
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<string>: [])` - 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.
### 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
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
```
#### 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:
```
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
```
## `server` Examples
### Common Setup
This example shows a common Nomad agent `server` configuration stanza. The two
IP addresses could also be DNS, and should point to the other Nomad servers in
the cluster
```hcl
server {
enabled = true
bootstrap_expect = 3
retry_join = ["1.2.3.4", "5.6.7.8"]
}
```
### Automatic Bootstrapping
The Nomad servers can automatically bootstrap if Consul is configured. For a
more detailed explanation, please see the
[automatic Nomad bootstrapping documentation](/docs/cluster/automatic.html).
### Restricting Schedulers
This example shows restricting the schedulers that are enabled as well as the
maximum number of cores to utilize when participating in scheduling decisions:
```hcl
server {
enabled = true
enabled_schedulers = ["batch", "service"]
num_schedulers = 7
}
```
[encryption]: /docs/agent/encryption.html "Nomad Agent Encryption"

150
website/source/docs/agent/configuration/telemetry.html.md Normal file
View File

@@ -0,0 +1,150 @@
---
layout: "docs"
page_title: "telemetry Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-telemetry"
description: |-
The "telemetry" stanza configures Nomad's publication of metrics and telemetry
to third-party systems.
---
# `telemetry` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**telemetry**</code>
</td>
</tr>
</table>
The `telemetry` stanza configures Nomad's publication of metrics and telemetry
to third-party systems.
```hcl
telemetry {
public_allocation_metrics = true
publish_node_metrics = true
}
```
This section of the documentation only covers the configuration options for
`telemetry` stanza. To understand the architecture and metrics themselves,
please see the [Nomad telemetry documentation](/docs/agent/telemetry.html).
## `telemetry` Parameters
Due to the number of configurable parameters to the `telemetry` stanza,
parameters on this page are grouped by the telemetry provider.
### Common
The following options are available on all telemetry configurations.
- `disable_hostname` `(bool: false)` - Specifies if gauge values should be
prefixed with the local hostname.
- `publish_allocation_metrics` `(bool: false)` - Specifies if Nomad should
publish runtime metrics of allocations.
- `publish_node_metrics` `(bool: false)` - Specifies if Nomad should publish
runtime metrics of nodes.
### `statsite`
These `telemetry` parameters apply to
[statsite](https://github.com/armon/statsite).
- `statsite_address` `(string: "")` - Specifies the address of a statsite server
to forward metrics data to.
```hcl
telemetry {
statsite_address = "statsite.company.local:8125"
}
```
### `statsd`
These `telemetry` parameters apply to
[statsd](https://github.com/etsy/statsd).
- `statsd_address` `(string: "")` - Specifies the address of a statsd server to
forward metrics to.
```hcl
telemetry {
statsd_address = "statsd.company.local:8125"
}
```
### `datadog`
These `telemetry` parameters apply to
[DataDog statsd](https://github.com/DataDog/dd-agent).
- `datadog_address` `(string: "")` - Specifies the address of a DataDog statsd
server to forward metrics to.
```hcl
telemetry {
datadog_address = "dogstatsd.company.local:8125"
}
```
### `circonus`
These `telemetry` parameters apply to
[Circonus](http://circonus.com/).
- `circonus_api_token` `(string: "")` - Specifies a valid Circonus API Token
used to create/manage check. If provided, metric management is enabled.
- `circonus_api_app` `(string: "nomad")` - Specifies a valid app name associated
with the API token.
- `circonus_api_url` `(string: "https://api.circonus.com/v2")` - Specifies the
base URL to use for contacting the Circonus API.
- `circonus_submission_interval` `(string: "10s")` - Specifies the interval at
which metrics are submitted to Circonus.
- `circonus_submission_url` `(string: "")` - Specifies the
`check.config.submission_url` field, of a Check API object, from a previously
created HTTPTRAP check.
- `circonus_check_id` `(string: "")` - Specifies the Check ID (**not check
bundle**) from a previously created HTTPTRAP check. The numeric portion of the
`check._cid` field in the Check API object.
- `circonus_check_force_metric_activation` `(bool: false)` - Specifies if force
activation of metrics which already exist and are not currently active. If
check management is enabled, the default behavior is to add new metrics as
they are encountered. If the metric already exists in the check, it will
not be activated. This setting overrides that behavior.
- `circonus_check_instance_id` `(string: "<hostname>:<application>")` - Serves
to uniquely identify the metrics coming from this *instance*. It can be used
to maintain metric continuity with transient or ephemeral instances as they
move around within an infrastructure. By default, this is set to
hostname:application name (e.g. "host123:nomad").
- `circonus_check_search_tag` `(string: <service>:<application>)` - Specifies a
special tag which, when coupled with the instance id, helps to narrow down the
search results when neither a Submission URL or Check ID is provided. By
default, this is set to service:app (e.g. "service:nomad").
- `circonus_broker_id` `(string: "")` - Specifies the ID of a specific Circonus
Broker to use when creating a new check. The numeric portion of `broker._cid`
field in a Broker API object. If metric management is enabled and neither a
Submission URL nor Check ID is provided, an attempt will be made to search for
an existing check using Instance ID and Search Tag. If one is not found, a new
HTTPTRAP check will be created. By default, this is a random
Enterprise Broker is selected, or, the default Circonus Public Broker.
- `circonus_broker_select_tag` `(string: "")` - Specifies a special tag which
will be used to select a Circonus Broker when a Broker ID is not provided. The
best use of this is to as a hint for which broker should be used based on
*where* this particular instance is running (e.g. a specific geo location or
datacenter, dc:sfo).

94
website/source/docs/agent/configuration/tls.html.md Normal file
View File

@@ -0,0 +1,94 @@
---
layout: "docs"
page_title: "tls Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-tls"
description: |-
The "tls" stanza configures Nomad's TLS communication via HTTP and RPC to
enforce secure cluster communication between servers, clients, and between.
---
# `tls` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**tls**</code>
</td>
</tr>
</table>
The `tls` stanza configures Nomad's TLS communication via HTTP and RPC to
enforce secure cluster communication between servers, clients, and between.
```hcl
tls {
http = true
rpc = true
}
```
~> Incorrect configuration of the TLS configuration can result in failure to
start the Nomad agent.
This section of the documentation only covers the configuration options for
`tls` stanza. To understand how to setup the certificates themselves, please see
the [Agent's Gossip and RPC Encryption](/docs/agent/encryption.html).
## `tls` Parameters
- `ca_file` `(string: "")` - Specifies the path to the CA certificate to use for
Nomad's TLS communication.
- `cert_file` `(string: "")` - Specifies the path to the certificate file used
for Nomad's TLS communication.
- `key_file` `(string: "")` - Specifies the path to the key file to use for
Nomad's TLS communication.
- `http` `(bool: false)` - Specifies if TLS should be enabled on the HTTP
endpoints on the Nomad agent, including the API.
- `rpc` `(bool: false)` - Specifies if TLS should be enabled on the RPC
endpoints and [Raft][raft] traffic between the Nomad servers. Enabling this on
a Nomad client makes the client use TLS for making RPC requests to the Nomad
servers.
- `verify_server_hostname` `(bool: false)` - Specifies if outgoing TLS
connections should verify the server's hostname.
## `tls` Examples
The following examples only show the `tls` stanzas. Remember that the
`tls` stanza is only valid in the placements listed above.
### Default Configuration
This example shows the default TLS configuration. This enables TLS communication
between all servers and clients using the default system CA bundle and
certificates.
```hcl
tls {
http = true
rpc = true
}
```
### Custom Certificates
This example shows configuring Nomad to communicate via TLS over HTTP and RPC
using a custom certificate and CA bundle.
```hcl
tls {
http = true
rpc = true
ca_file = "/etc/certs/ca.crt"
cert_file = "/etc/certs/nomad.crt"
key_file = "/etc/certs/nomad.key"
}
```
[raft]: https://github.com/hashicorp/serf "Serf by HashiCorp"

133
website/source/docs/agent/configuration/vault.html.md Normal file
View File

@@ -0,0 +1,133 @@
---
layout: "docs"
page_title: "vault Stanza - Agent Configuration"
sidebar_current: "docs-agent-configuration-vault"
description: |-
The "vault" stanza configures Nomad's integration with HashiCorp's Vault.
When configured, Nomad can create and distribute secrets to tasks
automatically.
---
# `vault` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**vault**</code>
</td>
</tr>
</table>
The `vault` stanza configures Nomad's integration with
[HashiCorp's Vault][vault]. When configured, Nomad can create and distribute
secrets to tasks automatically. For more information on the architecture and
setup, please see the [Nomad and Vault integration documentation][nomad-vault].
```hcl
vault {
enabled = true
address = "https://vault.company.internal:8200"
}
```
## `vault` Parameters
- `address` - `(string: "https://vault.service.consul:8200")` - Specifies the
address to the Vault server. This must include the protocol, host/ip, and port
given in the format `protocol://host:port`. If your Vault installation is
behind a load balancer, this should be the address of the load balancer.
- `allow_unauthenticated` `(bool: false)` - Specifies if users submitting jobs
to the Nomad server should be required to provide their own Vault token,
proving they have access to the policies listed in the job. If enabled, users
could easily escalate privilege in a job.
- `enabled` `(bool: false)` - Specifies if the Vault integration should be
activated.
- `task_token_ttl` `(string: "")` - Specifies the TTL of created tokens when
using a root token. This is specified using a label suffix like "30s" or "1h".
- `tls_ca_file` `(string: "")` - Specifies an optional path to the CA
certificate used for Vault communication. If unspecified, this will fallback
to the default system CA bundle, which varies by OS and version.
- `tls_ca_path` `(string: "")` - Specifies an optional path to a folder
containing CA certificates to be used for Vault communication. If unspecified,
this will fallback to the default system CA bundle, which varies by OS and
version.
- `tls_cert_file` `(string: "")` - Specifies the path to the certificate used
for Vault communication. If this is set then you need to also set
`tls_key_file`.
- `tls_key_file` `(string: "")` - Specifies the path to the private key used for
Vault communication. If this is set then you need to also set `tls_cert_file`.
- `tls_server_name` `(string: "")` - Specifies an optional string used to set
the SNI host when connecting to Vault via TLS.
- `tls_skip_verify` `(bool: false)` - Specifies if SSL peer validation should be
enforced.
!> It is **strongly discouraged** to disable SSL verification. Instead, you
should install a custom CA bundle and validate against it. Disabling SSL
verification can allow an attacker to easily compromise your cluster.
- `token` `(string: "")` - Specifies the parent Vault token to use to derive child tokens for jobs
requesting tokens.
Visit the [Vault Integration](/docs/vault-integration/index.html)
documentation to see how to generate an appropriate token in Vault.
!> It is **strongly discouraged** to place the token as a configuration
parameter like this, since the token could be checked into source control
accidentally. Users should set the `VAULT_TOKEN` environment variable when
starting the agent instead.
## `vault` Examples
The following examples only show the `vault` stanzas. Remember that the
`vault` stanza is only valid in the placements listed above.
### Default Configuration
This example shows the most basic Vault integration configuration. If all
defaults are correct, simply include the Vault stanza to enable the integration:
```hcl
vault {
enabled = true
}
```
### Custom Address
This example shows using a custom Vault address:
```hcl
vault {
enabled = true
address = "https://vault.company.internal:8200"
}
```
### TLS Configuration
This example shows utilizing a custom CA bundle and key to authenticate between
Nomad and Vault:
```hcl
vault {
enabled = true
tls_ca_path = "/etc/certs/ca"
tls_cert_file = "/var/certs/vault.crt"
tls_key_file = "/var/certs/vault.key"
tls_server_name = "nomad.service.consul"
}
```
[vault]: https://www.vaultproject.io/ "Vault by HashiCorp"
[nomad-vault]: /docs/vault-integration/index.html "Nomad Vault Integration"

6
website/source/docs/agent/encryption.html.md
View File

@@ -16,8 +16,8 @@ two separate encryption systems, one for gossip traffic, and one for RPC.
Enabling gossip encryption only requires that you set an encryption key when
starting the Nomad server. The key can be set via the
[`encrypt`](/docs/agent/config.html#encrypt) parameter: the value of this
setting is a server configuration file containing the encryption key.
[`encrypt`](/docs/agent/configuration/server.html#encrypt) parameter: the value
of this setting is a server configuration file containing the encryption key.
The key must be 16-bytes, base64 encoded. As a convenience, Nomad provides the
[`nomad keygen`](/docs/commands/keygen.html) command to generate a cryptographically suitable key:
@@ -51,4 +51,4 @@ TLS is used to secure the RPC calls between agents, but gossip between nodes is
done over UDP and is secured using a symmetric key. See above for enabling
gossip encryption.
[tls]: http://127.0.0.1:4567/docs/agent/config.html#tls-options "Nomad TLS Configuration"
[tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration"

34
website/source/docs/agent/index.html.md
View File

@@ -1,9 +1,10 @@
---
layout: "docs"
page_title: "Nomad Agent"
sidebar_current: "docs-agent-basics"
sidebar_current: "docs-agent"
description: |-
The Nomad agent is a long running process which can be used either in a client or server mode.
The Nomad agent is a long running process which can be used either in
a client or server mode.
---
# Nomad Agent
@@ -27,9 +28,10 @@ clustering of servers and multi-region federation. The higher burden on the
server nodes means that usually they should be run on dedicated instances --
they are more resource intensive than a client node.
Client nodes make up the majority of the cluster, and are very lightweight
as they interface with the server nodes and maintain very little state of their own.
Each cluster has usually 3 or 5 server mode agents and potentially thousands of clients.
Client nodes make up the majority of the cluster, and are very lightweight as
they interface with the server nodes and maintain very little state of their
own. Each cluster has usually 3 or 5 server mode agents and potentially
thousands of clients.
## Running an Agent
@@ -59,25 +61,25 @@ $ nomad agent -dev
There are several important messages that `nomad agent` outputs:
* **Atlas**: This shows the [Atlas infrastructure](https://atlas.hashicorp.com)
with which the node is registered, if any. It also indicates if auto-join is enabled.
The Atlas infrastructure is set using [`-atlas`](/docs/agent/config.html#_atlas)
and auto-join is enabled by setting [`-atlas-join`](/docs/agent/config.html#_atlas_join).
- **Atlas**: This shows the [Atlas infrastructure](https://atlas.hashicorp.com)
with which the node is registered, if any. It also indicates if auto-join is
enabled. The Atlas infrastructure is set using `-atlas` and auto-join is
enabled by setting `-atlas-join`.
* **Client**: This indicates whether the agent has enabled client mode.
- **Client**: This indicates whether the agent has enabled client mode.
Client nodes fingerprint their host environment, register with servers,
and run tasks.
* **Log Level**: This indicates the configured log level. Only messages with
- **Log Level**: This indicates the configured log level. Only messages with
an equal or higher severity will be logged. This can be tuned to increase
verbosity for debugging, or reduced to avoid noisy logging.
* **Region**: This is the region and datacenter in which the agent is configured to run.
Nomad has first-class support for multi-datacenter and multi-region configurations.
The [`-region` and `-dc`](/docs/agent/config.html#_region) flag can be used to set
the region and datacenter. The default is the `global` region in `dc1`.
- **Region**: This is the region and datacenter in which the agent is configured
to run. Nomad has first-class support for multi-datacenter and multi-region
configurations. The `-region` and `-dc` flags can be used to set the region
and datacenter. The default is the `global` region in `dc1`.
* **Server**: This indicates whether the agent has enabled server mode.
- **Server**: This indicates whether the agent has enabled server mode.
Server nodes have the extra burden of participating in the consensus protocol,
storing cluster state, and making scheduling decisions.

6
website/source/docs/agent/telemetry.html.md
View File

@@ -23,7 +23,7 @@ Telemetry information can be streamed to both [statsite](https://github.com/armo
as well as statsd based on providing the appropriate configuration options.
To configure the telemetry output please see the [agent
configuration](/docs/agent/config.html#telemetry_config).
configuration](/docs/agent/configuration/telemetry.html).
Below is sample output of a telemetry dump:
@@ -224,9 +224,9 @@ metrics can be turned on by setting the value of `publish_allocation_metrics`
By default the collection interval is 1 second but it can be changed by the
changing the value of the `collection_interval` key in the `telemetry`
configuration block.
configuration block.
Please see the [agent configuration](/docs/agent/config.html#telemetry_config)
Please see the [agent configuration](/docs/agent/configuration/telemetry.html)
page for more details.
## Host Metrics

2
website/source/docs/cluster/automatic.html.md
View File

@@ -112,5 +112,5 @@ consul {
```
Please refer to the [Consul
documentation](/docs/agent/config.html#consul_options) for the complete set of
documentation](/docs/agent/configuration/consul.html) for the complete set of
configuration options.

2
website/source/docs/cluster/requirements.html.md
View File

@@ -27,7 +27,7 @@ used by Nomad. This should be used to target a specific resource utilization per
node and to reserve resources for applications running outside of Nomad's
supervision such as Consul and the operating system itself.
Please see the [reservation configuration](/docs/agent/config.html#reserved) for
Please see the [reservation configuration](/docs/agent/configuration/client.html#reserved) for
more detail.
## Network Topology

60
website/source/docs/commands/agent.html.md.erb
View File

@@ -16,3 +16,63 @@ and running jobs.
Due to the power and flexibility of this command, the Nomad agent is documented
in its own section. See the [Nomad Agent](/docs/agent/index.html) section for
more information on how to use this command and the options it has.
## Command-line Options
A subset of the available Nomad agent configuration can optionally be passed in
via CLI arguments. The `agent` command accepts the following arguments:
* `-alloc-dir=<path>`: Equivalent to the Client [alloc_dir](#alloc_dir) config
option.
* `-atlas=<infrastructure>`: Equivalent to the Atlas
[infrastructure](#infrastructure) config option.
* `-atlas-join`: Equivalent to the Atlas [join](#join) config option.
* `-atlas-token=<token>`: Equivalent to the Atlas [token](#token) config option.
* `-bind=<address>`: Equivalent to the [bind_addr](#bind_addr) config option.
* `-bootstrap-expect=<num>`: Equivalent to the
[bootstrap_expect](#bootstrap_expect) config option.
* `-client`: Enable client mode on the local agent.
* `-config=<path>`: Specifies the path to a configuration file or a directory of
configuration files to load. Can be specified multiple times.
* `-data-dir=<path>`: Equivalent to the [data_dir](#data_dir) config option.
* `-dc=<datacenter>`: Equivalent to the [datacenter](#datacenter) config option.
* `-dev`: Start the agent in development mode. This enables a pre-configured
dual-role agent (client + server) which is useful for developing or testing
Nomad. No other configuration is required to start the agent in this mode.
* `-join=<address>`: Address of another agent to join upon starting up. This can
be specified multiple times to specify multiple agents to join.
* `-log-level=<level>`: Equivalent to the [log_level](#log_level) config option.
* `-meta=<key=value>`: Equivalent to the Client [meta](#meta) config option.
* `-network-interface=<interface>`: Equivalent to the Client
[network_interface](#network_interface) config option.
* `-network-speed=<MBits>`: Equivalent to the Client
[network_speed](#network_speed) config option.
* `-node=<name>`: Equivalent to the [name](#name) config option.
* `-node-class=<class>`: Equivalent to the Client [node_class](#node_class)
config option.
* `-region=<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-max`: Similar to the [retry_max](#retry_max) config option.
* `-server`: Enable server mode on the local agent.
* `-servers=<host:port>`: Equivalent to the Client [servers](#servers) config
option.
* `-state-dir=<path>`: Equivalent to the Client [state_dir](#state_dir) config
option.
* `-vault-enabled`: Whether to enable or disabled Vault integration.
* `-vault-address=<addr>`: The address to communicate with Vault.
* `-vault-token=<token>`: The Vault token used to derive tokens. Only needs to
be set on Servers. Overrides the Vault token read from the VAULT_TOKEN
environment variable.
* `-vault-ca-file=<path>`: Path to a PEM-encoded CA cert file used to verify the
Vault server SSL certificate.
* `-vault-ca-path=<path>`: Path to a directory of PEM-encoded CA cert files used
to verify the Vault server SSL certificate.Whether to enable or disabled Vault
integration.
* `vault-cert-file=<path>`: The path to the certificate for Vault communication.
* `vault-key-file=<path>`: The path to the private key for Vault communication.
* `vault-tls-skip-verify`: A boolean that determines whether to skip SSL
certificate verification.
* `vault-tls-server-name=<name>`: Used to set the SNI host when connecting to
Vault over TLS.

4
website/source/docs/commands/client-config.html.md.erb
View File

@@ -30,8 +30,8 @@ description below for specific usage information and requirements.
* `-servers`: List the client's known servers. Client nodes do not participate
in the gossip pool, and instead register with these servers periodically over
the network. The initial value of this list may come from configuration files
using the [servers](/docs/agent/config.html#servers) configuration option in
the client block.
using the [`servers`](/docs/agent/configuration/client.html#servers)
configuration option in the client block.
* `-update-servers`: Updates the client's server list using the provided
arguments. Multiple server addresses may be passed using multiple arguments.

2
website/source/docs/drivers/docker.html.md
View File

@@ -343,7 +343,7 @@ of the Linux Kernel and Docker daemon.
## Client Configuration
The `docker` driver has the following [client configuration
options](/docs/agent/config.html#options):
options](/docs/agent/configuration/client.html#options):
* `docker.endpoint` - Defaults to `unix:///var/run/docker.sock`. You will need
to customize this if you use a non-standard socket (HTTP or another

2
website/source/docs/drivers/exec.html.md
View File

@@ -126,4 +126,4 @@ machine:
```
This list is configurable through the agent client
[configuration file](/docs/agent/config.html#chroot_env).
[configuration file](/docs/agent/configuration/client.html#chroot_env).

4
website/source/docs/drivers/lxc.html.md
View File

@@ -84,8 +84,8 @@ The `lxc` driver requires the following:
## Client Configuration
* `lxc.enable` - The `lxc` driver may be disabled on hosts by setting this
[client configuration][/docs/agent/config.html#options] option to `false`
(defaults to `true`).
[client configuration][/docs/agent/configuration/client.html##options-parameters]
option to `false` (defaults to `true`).
## Client Attributes

2
website/source/docs/drivers/raw_exec.html.md
View File

@@ -79,7 +79,7 @@ task "example" {
The `raw_exec` driver can run on all supported operating systems. For security
reasons, it is disabled by default. To enable raw exec, the Nomad client
configuration must explicitly enable the `raw_exec` driver in the client's
[options](/docs/agent/config.html#options):
[options](/docs/agent/configuration/client.html#options):
```
client {

2
website/source/docs/drivers/rkt.html.md
View File

@@ -150,7 +150,7 @@ over HTTP.
## Client Configuration
The `rkt` driver has the following [client configuration
options](/docs/agent/config.html#options):
options](/docs/agent/configuration/client.html#options):
* `rkt.volumes.enabled`: Defaults to `true`. Allows tasks to bind host paths
(`volumes`) inside their container. Binding relative paths is always allowed

4
website/source/docs/faq.html.md
View File

@@ -16,8 +16,8 @@ Only anonymous information, which cannot be used to identify the user or host, i
sent to Checkpoint. An anonymous ID is sent which helps de-duplicate warning messages.
This anonymous ID can can be disabled. Using the Checkpoint service is optional and can be disabled.
See [`disable_anonymous_signature`](/docs/agent/config.html#disable_anonymous_signature)
and [`disable_update_check`](/docs/agent/config.html#disable_update_check).
See [`disable_anonymous_signature`](/docs/agent/configuration/index.html#disable_anonymous_signature)
and [`disable_update_check`](/docs/agent/configuration/index.html#disable_update_check).
## Q: How does Atlas integration work?

2
website/source/docs/job-specification/artifact.html.md
View File

@@ -50,7 +50,7 @@ before the starting the task.
artifact, relative to the root of the task's directory. If omitted, the
default value is to place the binary in `local/`.
- `source` `(string: required)` - Specifies the URL of the artifact to download.
- `source` `(string: <required>)` - Specifies the URL of the artifact to download.
The can be any URL as defined by the [`go-getter`][go-getter] library.
- `options` `(map<string|string>: nil)` - Specifies configuration parameters to

2
website/source/docs/job-specification/group.html.md
View File

@@ -49,7 +49,7 @@ job "docs" {
all tasks in this group. If omitted, a default policy exists for each job
type, which can be found in the [restart stanza documentation][restart].
- `task` <code>([Task][]: required)</code> - Specifies one or more tasks to run
- `task` <code>([Task][]: <required>)</code> - Specifies one or more tasks to run
within this group. This can be specified multiple times, to add a task as part
of the group.

13
website/source/docs/job-specification/job.html.md
View File

@@ -10,6 +10,15 @@ description: |-
# `job` Stanza
<table class="table table-bordered table-striped">
<tr>
<th width="120">Placement</th>
<td>
<code>**job**</code>
</td>
</tr>
</table>
The `job` stanza is the top-most configuration option in the job specification.
A job is a declarative specification of tasks that Nomad should run. Jobs have a
globally unique name, one or many task groups, which are themselves collections
@@ -62,10 +71,10 @@ job "docs" {
[Nomad constraint reference](/docs/job-specification/constraint.html) for more
details.
- `datacenters` `(array<string>: required)` - A list of datacenters in the region which are eligible
- `datacenters` `(array<string>: <required>)` - A list of datacenters in the region which are eligible
for task placement. This must be provided, and does not have a default.
- `group` <code>([Group][group]: required)</code> - Specifies the start of a
- `group` <code>([Group][group]: <required>)</code> - Specifies the start of a
group of tasks. This can be provided multiple times to define additional
groups. Group names must be unique within the job file.

2
website/source/docs/job-specification/network.html.md
View File

@@ -52,7 +52,7 @@ job "docs" {
## `network` Parameters
- `mbits` `(int: required)` - Specifies the bandwidth required in MBits.
- `mbits` `(int: <required>)` - Specifies the bandwidth required in MBits.
- `port` <code>([Port](#port-parameters): nil)</code> - Specifies a port
allocation and can be used to specify both dynamic ports and reserved ports.

2
website/source/docs/job-specification/periodic.html.md
View File

@@ -37,7 +37,7 @@ consistent evaluation when Nomad spans multiple time zones.
## `periodic` Parameters
- `cron` `(string: required)` - Specifies a cron expression configuring the
- `cron` `(string: <required>)` - Specifies a cron expression configuring the
interval to launch the job. In addition to [cron-specific formats][cron], this
option also includes predefined expressions such as `@daily` or `@weekly`.

2
website/source/docs/job-specification/resources.html.md
View File

@@ -54,7 +54,7 @@ job "docs" {
- `memory` `(int: 300)` - Specifies the memory required in MB
- `network` <code>([Network][]: required)</code> - Specifies the network
- `network` <code>([Network][]: <required>)</code> - Specifies the network
requirements, including static and dynamic port allocations.
## `resources` Examples

2
website/source/docs/job-specification/service.html.md
View File

@@ -84,7 +84,7 @@ does not automatically enable service discovery.
- `${TASK}` - the name of the task
- `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}`
- `port` `(string: required)` - Specifies the label of the port on which this
- `port` `(string: <required>)` - Specifies the label of the port on which this
service is running. Note this is the _label_ of the port and not the port
number. The port label must match one defined in the [`network`][network]
stanza.

2
website/source/docs/job-specification/task.html.md
View File

@@ -55,7 +55,7 @@ job "docs" {
- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
with user-defined metadata.
- `resources` <code>([Resources][]: required)</code> - Specifies the minimum
- `resources` <code>([Resources][]: <required>)</code> - Specifies the minimum
resource requirements such as RAM, CPU, disk, and network.
- `service` <code>([Service][]: nil)</code> - Specifies integrations with

2
website/source/docs/job-specification/template.html.md
View File

@@ -50,7 +50,7 @@ API template functions, please refer to the [Consul Template README][ct].
must exist on the machine prior to starting the task; it is not possible to
reference a template inside of a Docker container, for example.
- `destination` `(string: required)` - Specifies the location where the
- `destination` `(string: <required>)` - Specifies the location where the
resulting template should be rendered, relative to the task directory.
- `data` `(string: "")` - Specifies the raw template to execute. One of `source`

2
website/source/docs/service-discovery/index.html.md
View File

@@ -21,7 +21,7 @@ Nomad does not currently run Consul for you.
## Configuration
To enable Consul integration, please see the
[Nomad agent Consul integration](/docs/agent/config.html#consul_options)
[Nomad agent Consul integration](/docs/agent/configuration/consul.html)
configuration.

8
website/source/docs/vault-integration/index.html.md
View File

@@ -16,7 +16,7 @@ coordinate with Vault to derive a Vault token that has access to only the Vault
policies the tasks needs. Nomad clients make the token avaliable to the task and
handle the tokens renewal. Further, Nomad's [`template` block][template] can
retrieve secrets from Vault making it easier than ever to secure your
infrastructure.
infrastructure.
Note that in order to use Vault with Nomad, you will need to configure and
install Vault separately from Nomad. Nomad does not run Vault for you.
@@ -59,7 +59,7 @@ when creating the role with the Vault endpoint `/auth/token/roles/<role_name>`:
}
```
#### Parameters:
#### Parameters:
* `allowed_policies` - Specifies the list of allowed policies as a
comma-seperated string This list should contain all policies that jobs running
@@ -174,7 +174,7 @@ integration][config] configuration.
To configure a job to retrieve Vault tokens, please see the [`vault` job
specification documentation][vault-spec].
## Troubleshooting
## Troubleshooting
Upon startup, Nomad will attempt to connect to the specified Vault server. Nomad
will lookup the passed token and if the token is from a role, the role will be
@@ -188,7 +188,7 @@ the reasons the token is invalid and disable Vault integration.
- Nomad is given either a root token or a token created from an approriate role.
[auth]: https://www.vaultproject.io/docs/auth/token.html "Vault Authentication Backend"
[config]: /docs/agent/config.html#vault-options "Nomad Vault configuration block"
[config]: /docs/agent/configuration/vault.html "Nomad Vault configuration block"
[template]: /docs/job-specification/template.html "Nomad template Job Specification"
[vault]: https://www.vaultproject.io/ "Vault by HashiCorp"
[vault-spec]: /docs/job-specification/vault.html "Nomad Vault Job Specification"

4
website/source/intro/getting-started/running.html.md
View File

@@ -111,8 +111,8 @@ Additional metadata can be viewed by providing the `-detailed` flag.
You can use `Ctrl-C` (the interrupt signal) to halt the agent.
By default, all signals will cause the agent to forcefully shutdown.
The agent [can be configured](/docs/agent/config.html) to gracefully
leave on either the interrupt or terminate signals.
The agent [can be configured](/docs/agent/configuration/index.html) to
gracefully leave on either the interrupt or terminate signals.
After interrupting the agent, you should see it leave the cluster
and shut down:

7
website/source/intro/use-cases.html.markdown
View File

@@ -12,7 +12,7 @@ Before understanding use cases, it's useful to know [what Nomad is](/intro/index
This page lists some concrete use cases for Nomad, but the possible use cases are
much broader than what we cover.
#### Microservices Platform
## Microservices Platform
Microservices, or Service Oriented Architectures (SOA), are a design paradigm in which many
services with narrow scope, tight state encapsulation, and API driven interfaces interact together
@@ -20,14 +20,14 @@ to form a larger application. However, they add an operational challenge of mana
or thousands of services instead of a few large applications. Nomad provides a platform for
managing microservices, making it easier to adopt the paradigm.
#### Hybrid Cloud Deployments
## Hybrid Cloud Deployments
Nomad is designed to handle multi-datacenter and multi-region deployments and is cloud agnostic.
This allows Nomad to schedule in private datacenters running bare metal, OpenStack, or VMware
alongside an AWS, Azure, or GCE cloud deployment. This makes it easier to migrate workloads
incrementally, or to utilize the cloud for bursting.
#### E-Commerce
## E-Commerce
A typical E-Commerce website has a few types of workloads. There are long-lived services
used for web serving. These include the load balancer, web frontends, API servers, and OLTP databases.
@@ -35,4 +35,3 @@ Batch processing using Hadoop or Spark may run periodically for business reporti
or generating product recommendations. Nomad allows all these workloads to share an underlying cluster,
increasing utilization, reducing cost, simplifying scaling and providing a clean abstraction
for developers.

34
website/source/layouts/docs.erb
View File

@@ -177,7 +177,6 @@
</ul>
</li>
<li<%= sidebar_current("docs-commands") %>>
<a href="/docs/commands/index.html">Commands (CLI)</a>
<ul class="nav">
@@ -254,18 +253,35 @@
<a href="/docs/agent/index.html">Nomad Agent</a>
<ul class="nav">
<li<%= sidebar_current("docs-agent-basics") %>>
<a href="/docs/agent/index.html">Basics</a>
<li<%= sidebar_current("docs-agent-configuration") %>>
<a href="/docs/agent/configuration/index.html">Configuration</a>
<ul class="nav">
<li <%= sidebar_current("docs-agent-configuration-atlas") %>>
<a href="/docs/agent/configuration/atlas.html">atlas</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-client") %>>
<a href="/docs/agent/configuration/client.html">client</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-consul") %>>
<a href="/docs/agent/configuration/consul.html">consul</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-server") %>>
<a href="/docs/agent/configuration/server.html">server</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-telemetry") %>>
<a href="/docs/agent/configuration/telemetry.html">telemetry</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-tls") %>>
<a href="/docs/agent/configuration/tls.html">tls</a>
</li>
<li <%= sidebar_current("docs-agent-configuration-vault") %>>
<a href="/docs/agent/configuration/vault.html">vault</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-agent-config") %>>
<a href="/docs/agent/config.html">Configuration</a>
</li>
<li<%= sidebar_current("docs-agent-encryption") %>>
<a href="/docs/agent/encryption.html">Encryption</a>
</li>
<li<%= sidebar_current("docs-agent-telemetry") %>>
<a href="/docs/agent/telemetry.html">Telemetry</a>
</li>