Cleans up some docs for the 1.0 release. (#3508)

* Cleans up information about file extensions, now that they are required.

* Removes references to deprecated configuration options.

* Adds docs for multiple bind address support.
This commit is contained in:
James Phillips 2017-09-27 15:30:30 -07:00 committed by GitHub
parent 07dea89f31
commit 7deed7162f
1 changed files with 13 additions and 76 deletions

View File

@ -22,9 +22,10 @@ Configuration precedence is evaluated in the following order:
When loading configuration, Consul loads the configuration from files and When loading configuration, Consul loads the configuration from files and
directories in lexical order. For example, configuration file directories in lexical order. For example, configuration file
`basic_config.json` will be processed before `extra_config.json`. Configuration `basic_config.json` will be processed before `extra_config.json`. Configuration
can be in either HCL or JSON format. Files with an `.hcl` extension are assumed can be in either [HCL](https://github.com/hashicorp/hcl#syntax) or JSON format.
to be in HCL format. All other files are considered to be in JSON format Available in Consul 1.0 and later, the HCL support now requires an `.hcl` or
however you should append a `.json` suffix to JSON config files for clarity. `.json` extension on all configuration files in order to specify their format.
Configuration specified later will be merged into configuration specified Configuration specified later will be merged into configuration specified
earlier. In most cases, "merge" means that the later version will override the earlier. In most cases, "merge" means that the later version will override the
earlier. In some cases, such as event handlers, merging appends the handlers to earlier. In some cases, such as event handlers, merging appends the handlers to
@ -101,7 +102,10 @@ will exit with an error at startup.
* <a name="_client"></a><a href="#_client">`-client`</a> - The address to which * <a name="_client"></a><a href="#_client">`-client`</a> - The address to which
Consul will bind client interfaces, including the HTTP and DNS servers. By default, Consul will bind client interfaces, including the HTTP and DNS servers. By default,
this is "127.0.0.1", allowing only loopback connections. this is "127.0.0.1", allowing only loopback connections. In Consul 1.0 and later
this can be set to a space-separated list of addresses to bind to, or a
[go-sockaddr](https://github.com/hashicorp/go-sockaddr#go-sockaddr) that can potentially
resolve to multiple addresses.
* <a name="_config_file"></a><a href="#_config_file">`-config-file`</a> - A configuration file * <a name="_config_file"></a><a href="#_config_file">`-config-file`</a> - A configuration file
to load. For more information on to load. For more information on
@ -256,10 +260,8 @@ will exit with an error at startup.
combined with static IP or DNS addresses or even multiple configurations combined with static IP or DNS addresses or even multiple configurations
for different providers. for different providers.
~> This replaces the previous `-retry-join-ec2-*`, `-retry-join-azure-*`, The following sections give the options specific to each supported cloud
and `-retry-join-gce-*` configuration options. provider.
Here are the supported cloud provider specific auto joining options:
### Amazon EC2 ### Amazon EC2
@ -377,24 +379,6 @@ will exit with an error at startup.
- `username` (required) - the username to use for auth. - `username` (required) - the username to use for auth.
- `api_key` (required) - the api key to use for auth. - `api_key` (required) - the api key to use for auth.
* `-retry-join-ec2-tag-key` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-ec2-tag-value` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-ec2-region` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-gce-tag-value` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-gce-project-name` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-gce-zone-pattern` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-gce-credentials-file` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-azure-tag-name` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `-retry-join-azure-tag-value`- This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* <a name="_retry_interval"></a><a href="#_retry_interval">`-retry-interval`</a> - Time * <a name="_retry_interval"></a><a href="#_retry_interval">`-retry-interval`</a> - Time
to wait between join attempts. Defaults to 30s. to wait between join attempts. Defaults to 30s.
@ -656,7 +640,9 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
are not actively invalidated, ACL policy may be stale up to the TTL value. are not actively invalidated, ACL policy may be stale up to the TTL value.
* <a name="addresses"></a><a href="#addresses">`addresses`</a> - This is a nested object that allows * <a name="addresses"></a><a href="#addresses">`addresses`</a> - This is a nested object that allows
setting bind addresses. setting bind addresses. In Consul 1.0 and later these can be set to a space-separated list of
addresses to bind to, or a [go-sockaddr](https://github.com/hashicorp/go-sockaddr#go-sockaddr)
that can potentially resolve to multiple addresses.
`http` supports binding to a Unix domain socket. A socket can be `http` supports binding to a Unix domain socket. A socket can be
specified in the form `unix:///path/to/socket`. A new domain socket will be specified in the form `unix:///path/to/socket`. A new domain socket will be
@ -895,23 +881,6 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
PEM-encoded private key. The key is used with the certificate to verify the agent's authenticity. PEM-encoded private key. The key is used with the certificate to verify the agent's authenticity.
This must be provided along with [`cert_file`](#cert_file). This must be provided along with [`cert_file`](#cert_file).
* <a name="http_api_response_headers"></a><a href="#http_api_response_headers">`http_api_response_headers`</a>
This object allows adding headers to the HTTP API
responses. For example, the following config can be used to enable
[CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on
the HTTP API endpoints:
```javascript
{
"http_api_response_headers": {
"Access-Control-Allow-Origin": "*"
}
}
```
This has been deprecated in Consul 0.8.5. Setting this value will set `http_config.response_headers`
instead for backwards compatibility.
* <a name="http_config"></a><a href="#http_config">`http_config`</a> * <a name="http_config"></a><a href="#http_config">`http_config`</a>
This object allows setting options for the HTTP API. This object allows setting options for the HTTP API.
@ -1015,8 +984,6 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
* <a name="dns_port"></a><a href="#dns_port">`dns`</a> - The DNS server, -1 to disable. Default 8600. * <a name="dns_port"></a><a href="#dns_port">`dns`</a> - The DNS server, -1 to disable. Default 8600.
* <a name="http_port"></a><a href="#http_port">`http`</a> - The HTTP API, -1 to disable. Default 8500. * <a name="http_port"></a><a href="#http_port">`http`</a> - The HTTP API, -1 to disable. Default 8500.
* <a name="https_port"></a><a href="#https_port">`https`</a> - The HTTPS API, -1 to disable. Default -1 (disabled). * <a name="https_port"></a><a href="#https_port">`https`</a> - The HTTPS API, -1 to disable. Default -1 (disabled).
* <a name="rpc_port"></a><a href="#rpc_port">`rpc`</a> - The CLI RPC endpoint. Default 8400. This is deprecated
in Consul 0.8 and later.
* <a name="serf_lan_port"></a><a href="#serf_lan_port">`serf_lan`</a> - The Serf LAN port. Default 8301. * <a name="serf_lan_port"></a><a href="#serf_lan_port">`serf_lan`</a> - The Serf LAN port. Default 8301.
* <a name="serf_wan_port"></a><a href="#serf_wan_port">`serf_wan`</a> - The Serf WAN port. Default 8302. * <a name="serf_wan_port"></a><a href="#serf_wan_port">`serf_wan`</a> - The Serf WAN port. Default 8302.
* <a name="server_rpc_port"></a><a href="#server_rpc_port">`server`</a> - Server RPC address. Default 8300. * <a name="server_rpc_port"></a><a href="#server_rpc_port">`server`</a> - Server RPC address. Default 8300.
@ -1050,10 +1017,6 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
controls how long it takes for a failed server to be completely removed from the WAN pool. This also controls how long it takes for a failed server to be completely removed from the WAN pool. This also
defaults to 72 hours, and must be >= 8 hours. defaults to 72 hours, and must be >= 8 hours.
* <a name="recursor"></a><a href="#recursor">`recursor`</a> Provides a single recursor address.
This has been deprecated, and the value is appended to the [`recursors`](#recursors) list for
backwards compatibility.
* <a name="recursors"></a><a href="#recursors">`recursors`</a> This flag provides addresses of * <a name="recursors"></a><a href="#recursors">`recursors`</a> This flag provides addresses of
upstream DNS servers that are used to recursively resolve queries if they are not inside the service upstream DNS servers that are used to recursively resolve queries if they are not inside the service
domain for Consul. For example, a node can use Consul directly as a DNS server, and if the record is domain for Consul. For example, a node can use Consul directly as a DNS server, and if the record is
@ -1064,12 +1027,6 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
* `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag. * `retry_join` - Equivalent to the [`-retry-join`](#retry-join) command-line flag.
* `retry_join_ec2`- This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `retry_join_gce` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* `retry_join_azure` - This parameter has been deprecated as of Consul 0.9.1. See [-retry-join](#retry-join) for details.
* <a name="retry_interval"></a><a href="#retry_interval">`retry_interval`</a> Equivalent to the * <a name="retry_interval"></a><a href="#retry_interval">`retry_interval`</a> Equivalent to the
[`-retry-interval` command-line flag](#_retry_interval). [`-retry-interval` command-line flag](#_retry_interval).
@ -1222,21 +1179,6 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
for aggregation. This can be used to capture runtime information. This streams via TCP and can only be used with for aggregation. This can be used to capture runtime information. This streams via TCP and can only be used with
statsite. statsite.
* <a name="statsd_addr"></a><a href="#statsd_addr">`statsd_addr`</a> Deprecated, see
the <a href="#telemetry">telemetry</a> structure
* <a name="statsite_addr"></a><a href="#statsite_addr">`statsite_addr`</a> Deprecated, see
the <a href="#telemetry">telemetry</a> structure
* <a name="statsite_prefix"></a><a href="#statsite_prefix">`statsite_prefix`</a> Deprecated, see
the <a href="#telemetry">telemetry</a> structure
* <a name="dogstatsd_addr"></a><a href="#dogstatsd_addr">`dogstatsd_addr`</a> Deprecated, see
the <a href="#telemetry">telemetry</a> structure
* <a name="dogstatsd_tags"></a><a href="#dogstatsd_tags">`dogstatsd_tags`</a> Deprecated, see
the <a href="#telemetry">telemetry</a> structure
* <a name="syslog_facility"></a><a href="#syslog_facility">`syslog_facility`</a> When * <a name="syslog_facility"></a><a href="#syslog_facility">`syslog_facility`</a> When
[`enable_syslog`](#enable_syslog) is provided, this controls to which [`enable_syslog`](#enable_syslog) is provided, this controls to which
facility messages are sent. By default, `LOCAL0` will be used. facility messages are sent. By default, `LOCAL0` will be used.
@ -1359,11 +1301,6 @@ port.
the LAN interface as well for the WAN Join Flooding feature. See also: the LAN interface as well for the WAN Join Flooding feature. See also:
[Consul 0.8.0 CHANGELOG](https://github.com/hashicorp/consul/blob/master/CHANGELOG.md#080-april-5-2017) and [GH-3058](https://github.com/hashicorp/consul/issues/3058) [Consul 0.8.0 CHANGELOG](https://github.com/hashicorp/consul/blob/master/CHANGELOG.md#080-april-5-2017) and [GH-3058](https://github.com/hashicorp/consul/issues/3058)
* CLI RPC (Default 8400). This is used by all agents to handle RPC
from the CLI, but is deprecated in Consul 0.8 and later. TCP only.
In Consul 0.8 all CLI commands were changed to use the HTTP API and
the RPC interface was completely removed.
* HTTP API (Default 8500). This is used by clients to talk to the HTTP * HTTP API (Default 8500). This is used by clients to talk to the HTTP
API. TCP only. API. TCP only.