docs: improve gateway docs

hashicorp · Dec 17, 2020 · ac24722 · ac24722
1 parent 5adcfc4
commit ac24722
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 44 deletions.
diff --git a/website/pages/docs/job-specification/connect.mdx b/website/pages/docs/job-specification/connect.mdx
@@ -47,20 +47,41 @@ job "countdash" {
 
 ## `connect` Parameters
 
+Used to configure a connect service. Only one of `native`, `sidecar_service`,
+or `gateway` may be realized per `connect` block.
+
 - `native` - `(bool: false)` - This is used to configure the service as supporting
-  [Connect Native](https://www.consul.io/docs/connect/native) applications. If set,
-  the service definition must provide the name of the implementing task in the
-  [task][service_task] field.
-  Incompatible with `sidecar_service` and `sidecar_task`.
+  [Connect Native](https://www.consul.io/docs/connect/native) applications.
+
+- `sidecar_service` - <code>([sidecar_service][]: nil)</code> - This is used to
+  configure the sidecar service created by Nomad for Consul Connect.
 
-- `sidecar_service` - <code>([sidecar_service][]: nil)</code> - This is used to configure the sidecar
-  service injected by Nomad for Consul Connect. Incompatible with `native`.
+- `sidecar_task` - <code>([sidecar_task][]:nil)</code> - This modifies the
+  task configuration of the Envoy proxy created as a sidecar or gateway.
 
-- `sidecar_task` - <code>([sidecar_task][]:nil)</code> - This modifies the configuration of the Envoy
-  proxy task. Incompatible with `native`.
+- `gateway` - <code>([gateway][]:nil)</code> - This is used to configure the
+  gateway service created by Nomad for Consul Connect.
 
 ## `connect` Examples
 
+### Using Connect Native
+
+The following example is a minimal service stanza for a
+[Consul Connect Native](https://www.consul.io/docs/connect/native)
+application implemented by a task named `generate`.
+
+```hcl
+service {
+  name = "uuid-api"
+  port = "${NOMAD_PORT_api}"
+  task = "generate"
+
+  connect {
+    native = true
+  }
+}
+```
+
 ### Using Sidecar Service
 
 The following example is a minimal connect stanza with defaults and is
@@ -169,35 +190,64 @@ job "countdash" {
 }
 ```
 
-### Using Connect Native
+### Using a Gateway
 
-The following example is a minimal service stanza for a
-[Consul Connect Native](https://www.consul.io/docs/connect/native)
-application implemented by a task named `generate`.
+The following is an example service stanza for creating and using a connect ingress
+gateway. It includes a gateway service definition and an api service fronted by
+the gateway. Once running, the gateway can be used to reach the api service by first
+looking up the gateway Consul DNS address, e.g.
+
+```
+curl $(dig +short @127.0.0.1 -p 8600 uuid-api.ingress.dc1.consul. ANY):8080
+```
 
 ```hcl
-service {
-  name = "uuid-api"
-  port = "${NOMAD_PORT_api}"
-  task = "generate"
+job "ingress-demo" {
 
-  connect {
-    native = true
+  datacenters = ["dc1"]
+
+  group "ingress-group" {
+
+    network {
+      mode = "bridge"
+      port "inbound" {
+        static = 8080
+        to     = 8080
+      }
+    }
+
+    service {
+      name = "my-ingress-service"
+      port = "8080"
+
+      connect {
+        gateway {
+          ingress {
+            listener {
+              port     = 8080
+              protocol = "tcp"
+              service {
+                name = "uuid-api"
+              }
+            }
+          }
+        }
+      }
+    }
   }
 }
 ```
 
 ### Limitations
 
-[Nomad variable interpolation][interpolation] is _not_ yet supported ([gh-7221]).
-
+[gateway]: /docs/job-specification/gateway
 [gh-7221]: https://github.com/hashicorp/nomad/issues/7221
-[job]: /docs/job-specification/job 'Nomad job Job Specification'
 [group]: /docs/job-specification/group 'Nomad group Job Specification'
-[task]: /docs/job-specification/task 'Nomad task Job Specification'
 [interpolation]: /docs/runtime/interpolation 'Nomad interpolation'
+[job]: /docs/job-specification/job 'Nomad job Job Specification'
+[native]: https://www.consul.io/docs/connect/native
+[service_task]: /docs/job-specification/service#task-1 'Nomad service task'
 [sidecar_service]: /docs/job-specification/sidecar_service 'Nomad sidecar service Specification'
 [sidecar_task]: /docs/job-specification/sidecar_task 'Nomad sidecar task config Specification'
+[task]: /docs/job-specification/task 'Nomad task Job Specification'
 [upstreams]: /docs/job-specification/upstreams 'Nomad sidecar service upstreams Specification'
-[native]: https://www.consul.io/docs/connect/native
-[service_task]: /docs/job-specification/service#task-1 'Nomad service task'
diff --git a/website/pages/docs/job-specification/gateway.mdx b/website/pages/docs/job-specification/gateway.mdx
@@ -25,59 +25,102 @@ same network. For public ingress products like [NGINX](https://learn.hashicorp.c
 provide more suitable features.
 
 ```hcl
-job "ingress-example" {
+job "ingress-demo" {
 
   datacenters = ["dc1"]
 
+  # This group will have a task providing the ingress gateway automatically
+  # created by Nomad. The ingress gateway is based on the Envoy proxy being
+  # managed by the docker driver.
   group "ingress-group" {
 
     network {
       mode = "bridge"
 
+      # This example will enable plain HTTP traffic to access the uuid-api connect
+      # native example service on port 8080.
       port "inbound" {
         static = 8080
+        to     = 8080
       }
     }
 
     service {
-      name = "ingress-service"
+      name = "my-ingress-service"
       port = "8080"
 
       connect {
         gateway {
+
+          # Consul gateway [envoy] proxy options.
           proxy {
-            // Consul Gateway Proxy configuration options
-            connect_timeout = "500ms"
+            # The following options are automatically set by Nomad if not
+            # explicitly configured when using bridge networking.
+            #
+            # envoy_gateway_no_default_bind = true
+            # envoy_gateway_bind_addresses "uuid-api" {
+            #   address = "0.0.0.0"
+            #   port    = <associated listener.port>
+            # }
+            #
+            # Additional options are documented at
+            # https://www.nomadproject.io/docs/job-specification/gateway#proxy-parameters
           }
 
+          # Consul Ingress Gateway Configuration Entry.
           ingress {
-            // Consul Ingress Gateway Configuration Entry
-
-            tls {
-              enabled = false
-            }
-
+            # Nomad will automatically manage the Configuration Entry in Consul
+            # given the parameters in the ingress block.
+            #
+            # Additional options are documented at
+            # https://www.nomadproject.io/docs/job-specification/gateway#ingress-parameters
             listener {
               port     = 8080
-              protocol = "http"
-              service {
-                name  = "web"
-                hosts = ["example.com", "example.com:8080"]
-              }
-            }
-
-            listener {
-              port = 3306
               protocol = "tcp"
               service {
-                name = "database"
+                name = "uuid-api"
               }
             }
           }
         }
       }
     }
   }
+
+  # The UUID generator from the connect-native demo is used as an example service.
+  # The ingress gateway above makes access to the service possible over normal HTTP.
+  # For example,
+  #
+  # $ curl $(dig +short @127.0.0.1 -p 8600 uuid-api.ingress.dc1.consul. ANY):8080
+  group "generator" {
+    network {
+      mode = "host"
+      port "api" {}
+    }
+
+    service {
+      name = "uuid-api"
+      port = "${NOMAD_PORT_api}"
+
+      connect {
+        native = true
+      }
+    }
+
+    task "generate" {
+      driver = "docker"
+
+      config {
+        image        = "hashicorpnomad/uuid-api:v3"
+        network_mode = "host"
+      }
+
+      env {
+        BIND = "0.0.0.0"
+        PORT = "${NOMAD_PORT_api}"
+      }
+    }
+  }
 }
 ```