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

docs: add more detail to connect stanzas

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` - <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

website/source/docs/job-specification/proxy.html.md

@@ -18,9 +18,10 @@ description: |-
   </tr>
 </table>
 
-The `proxy` stanza allows configuring various options for
+The `proxy` stanza allows configuring various options for the sidecar proxy
-the sidecar proxy managed by Nomad for Consul Connect integration.
+managed by Nomad for [Consul
-It is valid only within the context of a `sidecar_service` stanza.
+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.
+  this sidecar proxy communicates with.
-- `config` - (map: nil)</code> - Proxy configuration that's opaque to Nomad and passed directly to Consul.
+- `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"

website/source/docs/job-specification/sidecar_service.html.md

@@ -18,9 +18,10 @@ description: |-
   </tr>
 </table>
 
-The `sidecar_service` stanza allows configuring various options for
+The `sidecar_service` stanza allows configuring various options for the sidecar
-the sidecar proxy managed by Nomad for Consul Connect integration.
+proxy managed by Nomad for [Consul
-It is valid only within the context of a connect stanza.
+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"

website/source/docs/job-specification/sidecar_task.html.md

@@ -18,9 +18,11 @@ description: |-
   </tr>
 </table>
 
-The `sidecar_task` stanza allows configuring various options for
+The `sidecar_task` stanza allows configuring various options for the proxy
-the sidecar proxy managed by Nomad for Consul Connect integration.
+sidecar managed by Nomad for [Consul
-It is valid only within the context of a connect stanza.
+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
+- `shutdown_delay` `(string: "5s")` - Delay between deregistering the task from
-  signal to shutdown.
+  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

website/source/docs/job-specification/upstreams.html.md

@@ -18,9 +18,13 @@ description: |-
   </tr>
 </table>
 
-The `upstreams` stanza allows configuring various options for
+The `upstreams` stanza allows configuring various options for managing upstream
-managing upstream services that the proxy routes to.
+services that a [Consul
-It is valid only within the context of a `proxy` stanza.
+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.
+- `destination_name` `(string: <required>)` - Name of the upstream service.
-- `local_bind_port` - (int: nil)</code> - The port the proxy will receive
+- `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"

website/source/docs/runtime/_envvars.html.md.erb

@@ -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>