luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #6287 from hashicorp/docs-connect-updates 

docs: add more detail to connect stanzas
This commit is contained in:
Michael Schurter 2019-09-06 13:52:17 -07:00 committed by GitHub
parent 3469c50275 6930bb8c43
commit 37a1b8ed2c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 125 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -51,9 +51,6 @@ level.
## `connect` Parameters
- `native` `(bool: false)` native should be set to true if a service implements Connect directly
and does not need a sidecar. This is not common.
- `sidecar_service` - <code>([sidecar_service][]: nil)</code> - This is used to configure the sidecar
service injected by Nomad for Consul Connect.
@ -62,7 +59,9 @@ level.
## `connect` Examples
The following example is a minimal connect stanza with defaults
The following example is a minimal connect stanza with defaults and is
sufficient to start an Envoy proxy sidecar for allowing incoming connections
via Consul Connect.
```hcl
connect {
@ -70,7 +69,7 @@ The following example is a minimal connect stanza with defaults
}
```
The following example includes specifying upstreams.
The following example includes specifying [`upstreams`][upstreams].
```hcl
connect {
@ -85,13 +84,16 @@ The following example includes specifying upstreams.
}
```
### Interpolation
### Limitations
TODO do we need this
[Consul Connect Native services][native] and [Nomad variable
interpolation][interpolation] are *not* supported in Nomad 0.10.0.
[job]: /docs/job-specification/job.html "Nomad job Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
[sidecar_service]: /docs/job-specification/sidecar_service.html "Nomad sidecar service Specification"
[sidecar_task]: /docs/job-specification/sidecar_task.html "Nomad sidecar task config Specification"
[sidecar_task]: /docs/job-specification/sidecar_task.html "Nomad sidecar task config Specification"
[upstreams]: /docs/job-specification/upstreams.html "Nomad sidecar service upstreams Specification"
[native]: https://www.consul.io/docs/connect/native.html

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

@ -18,9 +18,10 @@ description: |-
</tr>
</table>
The `proxy` stanza allows configuring various options for
the sidecar proxy managed by Nomad for Consul Connect integration.
It is valid only within the context of a `sidecar_service` stanza.
The `proxy` stanza allows configuring various options for the sidecar proxy
managed by Nomad for [Consul
Connect](/guides/integrations/consul-connect/index.html). It is valid only
within the context of a `sidecar_service` stanza.
```hcl
job "countdash" {
@ -52,9 +53,11 @@ It is valid only within the context of a `sidecar_service` stanza.
## `proxy` Parameters
- `upstreams` <code>([upstreams][]: nil)</code> Used to configure details of each upstream service that
this sidecar proxy communicates with.
- `config` - (map: nil)</code> - Proxy configuration that's opaque to Nomad and passed directly to Consul.
this sidecar proxy communicates with.
- `config` - (map: nil)</code> - Proxy configuration that's opaque to Nomad and
passed directly to Consul. See [Consul Connect's
documentation](https://www.consul.io/docs/connect/proxies/envoy.html#dynamic-configuration)
for details.
## `proxy` Examples
@ -77,4 +80,4 @@ The following example is a proxy specification that includes upstreams configura
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
[sidecar_service]: /docs/job-specification/sidecar_service.html "Nomad sidecar service Specification"
[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification"
[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification"

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

@ -18,9 +18,10 @@ description: |-
</tr>
</table>
The `sidecar_service` stanza allows configuring various options for
the sidecar proxy managed by Nomad for Consul Connect integration.
It is valid only within the context of a connect stanza.
The `sidecar_service` stanza allows configuring various options for the sidecar
proxy managed by Nomad for [Consul
Connect](/guides/integrations/consul-connect/index.html) integration. It is
valid only within the context of a connect stanza.
```hcl
job "countdash" {
@ -85,4 +86,4 @@ The following example includes specifying upstreams.
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
[sidecar_service]: /docs/job-specification/sidecar_service.html "Nomad sidecar service Specification"
[proxy]: /docs/job-specification/proxy.html "Nomad sidecar proxy config Specification"
[proxy]: /docs/job-specification/proxy.html "Nomad sidecar proxy config Specification"

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

@ -18,9 +18,11 @@ description: |-
</tr>
</table>
The `sidecar_task` stanza allows configuring various options for
the sidecar proxy managed by Nomad for Consul Connect integration.
It is valid only within the context of a connect stanza.
The `sidecar_task` stanza allows configuring various options for the proxy
sidecar managed by Nomad for [Consul
Connect](/guides/integrations/consul-connect/index.html) integration such as
resource requirements, kill timeouts and more as defined below. It is valid
only within the context of a [`connect`][connect] stanza.
```hcl
job "countdash" {
@ -55,29 +57,73 @@ It is valid only within the context of a connect stanza.
```
## Default Envoy proxy sidecar
Nomad automatically includes a default Envoy proxy sidecar task whenever a
group service has a [`sidecar_service`][sidecar_service] stanza.
The default sidecar task is equivalent to:
```hcl
sidecar_task {
name = "connect-proxy-<service>"
driver = "docker"
config {
image = "${meta.connect.sidecar_image}
args = [
"-c",
"${NOMAD_SECRETS_DIR}/envoy_bootstrap.json",
"-l",
"${meta.connect.log_level}"
]
}
logs {
max_files = 2
max_file_size = 2 # MB
}
resources {
cpu = 250 # MHz
memory = 128 # MB
}
shutdown_delay = "5s"
}
```
The `meta.connect.sidecar_image` and `meta.connect.log_level` are [*client*
configurable][nodemeta] variables with the following defaults:
- `sidecar_image` - `"envoyproxy/envoy:v1.11.1"` - The official upstream Envoy Docker image.
- `sidecar_log_level` - `"info"` - Debug is useful for debugging Connect related issues.
## `sidecar_task` Parameters
- `name` `(string: )` - Name of the task.
- `name` `(string: "connect-proxy-<service>")` - Name of the task. Defaults to
including the name of the service it is a proxy for.
- `driver` `(string: )` - Driver used for the sidecar task.
- `driver` `(string: "docker")` - Driver used for the sidecar task.
- `user` `(string:nil)` - Determines which user is used to run the task, defaults
- `user` `(string: nil)` - Determines which user is used to run the task, defaults
to the same user the Nomad client is being run as.
- `config` `(map:nil )` - Configuration provided to the driver for initialization.
- `config` `(map: nil)` - Configuration provided to the driver for initialization.
- `env` `(map:nil )` - Map of environment variables used by the driver.
- `env` `(map: nil)` - Map of environment variables used by the driver.
- `resources` <code>[resources][]</code> - Resources needed by this task.
- `resources` <code>([Resources][resources])</code> - Resources needed by the sidecar task.
- `meta` `(map:nil )` - Arbitrary metadata associated with this task that's opaque to Nomad.
- `meta` `(map: nil)` - Arbitrary metadata associated with this task that's opaque to Nomad.
- `logs` <code>([Logs][]: nil)</code> - Specifies logging configuration for the
`stdout` and `stderr` of the task.
- `kill_timeout` `(int:)` - Time between signalling a task that will be killed and killing it.
- `kill_timeout` `(string: "5s")` - Time between signalling a task that will be
killed and killing it.
- `shutdown_delay` `(int:)` - Delay between deregistering the task from Consul and sendint it a
signal to shutdown.
- `shutdown_delay` `(string: "5s")` - Delay between deregistering the task from
Consul and sending it a signal to shutdown.
- `kill_signal` `(string:SIGINT)` - Kill signal to use for the task, defaults to SIGINT.
@ -101,10 +147,12 @@ The following example configures resources for the sidecar task and other config
```
[connect]: /docs/job-specification/connect.html "Nomad connect Job Specification"
[job]: /docs/job-specification/job.html "Nomad job Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
[sidecar_service]: /docs/job-specification/sidecar_service.html "Nomad sidecar service Specification"
[resources]: /docs/job-specification/resources.html "Nomad resources Job Specification"
[logs]: /docs/job-specification/logs.html "Nomad logs Job Specification"
[logs]: /docs/job-specification/logs.html "Nomad logs Job Specification"
[nodemeta]: /docs/configuration/client.html#meta

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

@ -18,9 +18,13 @@ description: |-
</tr>
</table>
The `upstreams` stanza allows configuring various options for
managing upstream services that the proxy routes to.
It is valid only within the context of a `proxy` stanza.
The `upstreams` stanza allows configuring various options for managing upstream
services that a [Consul
Connect](/guides/integrations/consul-connect/index.html) proxy routes to. It
is valid only within the context of a `proxy` stanza.
For Consul-specific details see the [Consul Connect
Guide](https://learn.hashicorp.com/consul/getting-started/connect#register-a-dependent-service-and-proxy).
```hcl
job "countdash" {
@ -70,10 +74,17 @@ job "countdash" {
## `upstreams` Parameters
- `destination_name` `(string: nil)` - Name of the upstream service.
- `local_bind_port` - (int: nil)</code> - The port the proxy will receive
- `destination_name` `(string: <required>)` - Name of the upstream service.
- `local_bind_port` - `(int: <required>)` - The port the proxy will receive
connections for the upstream on.
The `NOMAD_UPSTREAM_ADDR_<destination_name>` environment variables may be used
to interpolate the upstream's `host:port` address.
Applications are encouraged to connect to `127.0.0.1` and a well defined port
(eg 6379 for Redis) by default. Then when using Consul Connect the application
can be deployed with the Redis upstream's `local_bind_port = 6379` and require
no explicit configuration.
## `upstreams` Examples
@ -92,4 +103,4 @@ and a local bind port.
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[interpolation]: /docs/runtime/interpolation.html "Nomad interpolation"
[sidecar_service]: /docs/job-specification/sidecar_service.html "Nomad sidecar service Specification"
[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification"
[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification"

21
website/source/docs/runtime/_envvars.html.md.erb
View File

@ -140,4 +140,25 @@
in the same task group.
</td>
</tr>
<tr>
<td><tt>NOMAD&lowbar;UPSTREAM&lowbar;IP&lowbar;&lt;service&gt;</tt></td>
<td>
IP for the given <tt>service</tt> when defined as a Consul Connect
<a href="/docs/job-specification/upstreams.html">upstream</a>.
</td>
</tr>
<tr>
<td><tt>NOMAD&lowbar;UPSTREAM&lowbar;PORT&lowbar;&lt;service&gt;</tt></td>
<td>
Port for the given <tt>service</tt> when defined as a Consul Connect
<a href="/docs/job-specification/upstreams.html">upstream</a>.
</td>
</tr>
<tr>
<td><tt>NOMAD&lowbar;UPSTREAM&lowbar;ADDR&lowbar;&lt;service&gt;</tt></td>
<td>
Host <tt>IP:Port</tt> for the given <tt>service</tt> when defined as a
Consul Connect <a href="/docs/job-specification/upstreams.html">upstream</a>.
</td>
</tr>
</table>