diff --git a/website/source/docs/job-specification/connect.html.md b/website/source/docs/job-specification/connect.html.md index c7760afc6..e6baffafb 100644 --- a/website/source/docs/job-specification/connect.html.md +++ b/website/source/docs/job-specification/connect.html.md @@ -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` - ([sidecar_service][]: nil) - 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" \ No newline at end of file +[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 diff --git a/website/source/docs/job-specification/proxy.html.md b/website/source/docs/job-specification/proxy.html.md index c5c08a52b..5d4c952e5 100644 --- a/website/source/docs/job-specification/proxy.html.md +++ b/website/source/docs/job-specification/proxy.html.md @@ -18,9 +18,10 @@ description: |- -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` ([upstreams][]: nil) Used to configure details of each upstream service that - this sidecar proxy communicates with. -- `config` - (map: nil) - Proxy configuration that's opaque to Nomad and passed directly to Consul. - + this sidecar proxy communicates with. +- `config` - (map: nil) - 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" \ No newline at end of file +[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification" diff --git a/website/source/docs/job-specification/sidecar_service.html.md b/website/source/docs/job-specification/sidecar_service.html.md index 8a5efc372..2e864ec76 100644 --- a/website/source/docs/job-specification/sidecar_service.html.md +++ b/website/source/docs/job-specification/sidecar_service.html.md @@ -18,9 +18,10 @@ description: |- -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" \ No newline at end of file +[proxy]: /docs/job-specification/proxy.html "Nomad sidecar proxy config Specification" diff --git a/website/source/docs/job-specification/sidecar_task.html.md b/website/source/docs/job-specification/sidecar_task.html.md index 9b46dae37..13b6d5d95 100644 --- a/website/source/docs/job-specification/sidecar_task.html.md +++ b/website/source/docs/job-specification/sidecar_task.html.md @@ -18,9 +18,11 @@ description: |- -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-" + + 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-")` - 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` [resources][] - Resources needed by this task. +- `resources` ([Resources][resources]) - 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` ([Logs][]: nil) - 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" \ No newline at end of file +[logs]: /docs/job-specification/logs.html "Nomad logs Job Specification" +[nodemeta]: /docs/configuration/client.html#meta diff --git a/website/source/docs/job-specification/upstreams.html.md b/website/source/docs/job-specification/upstreams.html.md index b0ca10ae5..da42c0ec3 100644 --- a/website/source/docs/job-specification/upstreams.html.md +++ b/website/source/docs/job-specification/upstreams.html.md @@ -18,9 +18,13 @@ description: |- -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) - The port the proxy will receive +- `destination_name` `(string: )` - Name of the upstream service. +- `local_bind_port` - `(int: )` - The port the proxy will receive connections for the upstream on. +The `NOMAD_UPSTREAM_ADDR_` 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" \ No newline at end of file +[upstreams]: /docs/job-specification/upstreams.html "Nomad upstream config Specification" diff --git a/website/source/docs/runtime/_envvars.html.md.erb b/website/source/docs/runtime/_envvars.html.md.erb index 4cc2ec591..d729e66dc 100644 --- a/website/source/docs/runtime/_envvars.html.md.erb +++ b/website/source/docs/runtime/_envvars.html.md.erb @@ -140,4 +140,25 @@ in the same task group. + + NOMAD_UPSTREAM_IP_<service> + + IP for the given service when defined as a Consul Connect + upstream. + + + + NOMAD_UPSTREAM_PORT_<service> + + Port for the given service when defined as a Consul Connect + upstream. + + + + NOMAD_UPSTREAM_ADDR_<service> + + Host IP:Port for the given service when defined as a + Consul Connect upstream. + +