Merge pull request #6297 from hashicorp/f-group-services-docs

Start of docs for group level service and network stanza.

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

@@ -4,7 +4,9 @@ page_title: "network Stanza - Job Specification"
 sidebar_current: "docs-job-specification-network"
 description: |-
   The "network" stanza specifies the networking requirements for the task,
-  including the minimum bandwidth and port allocations.
+  including the minimum bandwidth and port allocations. The network stanza
+  can be specified at the task group level to enable all tasks in the task
+  group to share the same network namespace.
 ---
 
 # `network` Stanza
@@ -12,6 +14,12 @@ description: |-
 <table class="table table-bordered table-striped">
   <tr>
     <th width="120">Placement</th>
+    <td>
+          <code>job -> group -> **network**</code>
+    </td>
+  </tr>
+  <tr>
+  <th width="120">Placement</th>
     <td>
       <code>job -> group -> task -> resources -> **network**</code>
     </td>
@@ -25,6 +33,15 @@ and services. Because you don't know in advance what host your job will be
 provisioned on, Nomad will provide your tasks with network configuration when
 they start up.
 
+Nomad 0.10 enables support for the `network` stanza at the task group level. When
+the `network` stanza is defined at the group level with `bridge` as the networking mode,
+all tasks in the task group share the same network namespace. This is a prerequisite for
+[Consul Connect](/guides/integrations/consul-connect/index.html). Tasks running within a
+network namespace are not visible to applications outside the namespace on the same host.
+This allows [Connect][] enabled applications to bind only to localhost within the shared network stack,
+and use the proxy for ingress and egress traffic.
+
+
 Note that this document only applies to services that want to _listen_ on a
 port. Batch jobs or services that only make outbound connections do not need to
 allocate ports, since they will use any available interface to make an outbound
@@ -57,10 +74,19 @@ job "docs" {
 - `port` <code>([Port](#port-parameters): nil)</code> - Specifies a TCP/UDP port
   allocation and can be used to specify both dynamic ports and reserved ports.
 
+- `mode`  `(string: "host")- Mode of the network. The following modes are available:
+
+ - “none” - Task group will have an isolated network without any network interfaces.
+ - “bridge” - Task group will have an isolated network namespace with an interface
+           that is bridged with the host.
+ - “host” - Each task will join the host network namespace and a shared network
+           namespace is not created. This matches the current behavior in Nomad 0.9.
+
 ### `port` Parameters
 
 - `static` `(int: nil)` - Specifies the static TCP/UDP port to allocate. If omitted, a dynamic port is chosen. We **do not recommend**  using static ports, except
   for `system` or specialized jobs like load balancers.
+- `to` `(string:nil)` - Applicable when using "bridge" mode to configure port to map to inside the task's network namespace.
 
 The label assigned to the port is used to identify the port in service
 discovery, and used in the name of the environment variable that indicates
@@ -167,6 +193,25 @@ When the task is started, it is passed an additional environment variable named
 `NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is
 bound to.
 
+### Bridge Mode
+
+The following example is a group level network stanza that uses bridge mode
+and port mapping.
+
+```hcl
+network {
+  mode = "bridge"
+    port "http" {
+      static = 9002
+      to     = 9002
+    }
+}
+```
 
 [docker-driver]: /docs/drivers/docker.html "Nomad Docker Driver"
 [qemu-driver]: /docs/drivers/qemu.html "Nomad QEMU Driver"
+[Connect]: /docs/job-specification/connect.html "Nomad Consul Connect Integration"
+
+### Limitations
+
+Only one `network` stanza can be specified, when it is defined at the task group level.
\ No newline at end of file

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

@@ -16,6 +16,11 @@ description: |-
       <code>job -> group -> task -> **service**</code>
     </td>
   </tr>
+  <th width="120">Placement</th>
+    <td>
+      <code>job -> group -> **service**</code>
+    </td>
+  </tr>
 </table>
 
 The `service` stanza instructs Nomad to register a service with Consul. This
@@ -67,6 +72,9 @@ This section of the documentation only cover the job file fields and stanzas
 for service discovery. For more details on using Nomad with Consul please see
 the [Consul integration documentation][service-discovery].
 
+Nomad 0.10 also allows specifying the `service` stanza at the task group level.
+This enables services in the same task group to opt into [Consul Connect][] integration.
+
 ## `service` Parameters
 
 - `check` <code>([Check](#check-parameters): nil)</code> - Specifies a health
@@ -628,3 +636,4 @@ system of a task for that driver.</small>
 [network]: /docs/job-specification/network.html "Nomad network Job Specification"
 [qemu]: /docs/drivers/qemu.html "Nomad qemu Driver"
 [restart_stanza]: /docs/job-specification/restart.html "restart stanza"
+[Connect]: /docs/job-specification/connect.html "Nomad Consul Connect Integration"