Merge pull request #7891 from hashicorp/docs-improve-connect-examples

docs: improve some connect examples

website/pages/docs/job-specification/connect.mdx

@@ -12,34 +12,37 @@ description: The "connect" stanza allows specifying options for Consul Connect i
 The `connect` stanza allows configuring various options for
 [Consul Connect](/docs/integrations/consul-connect). It is
 valid only within the context of a service definition at the task group
-level.
+level. For using `connect` when Consul ACLs are enabled, be sure to read through
+the [Secure Nomad Jobs with Consul Connect](https://learn.hashicorp.com/nomad/consul-integration/nomad-connect-acl)
+guide.
 
 ```hcl
- job "countdash" {
-   datacenters = ["dc1"]
-   group "api" {
-     network {
-       mode = "bridge"
-     }
-
-     service {
-       name = "count-api"
-       port = "9001"
-
-       connect {
-         sidecar_service {}
-       }
-     }
-
-     task "web" {
-       driver = "docker"
-       config {
-         image = "test/test:v1"
-       }
-     }
-   }
- }
-
+job "countdash" {
+  datacenters = ["dc1"]
+
+  group "api" {
+    network {
+      mode = "bridge"
+    }
+
+    service {
+      name = "count-api"
+      port = "9001"
+
+      connect {
+        sidecar_service {}
+      }
+    }
+
+    task "web" {
+      driver = "docker"
+
+      config {
+        image = "hashicorpnomad/counter-api:v2"
+      }
+    }
+  }
+}
 ```
 
 ## `connect` Parameters
@@ -77,10 +80,91 @@ The following example includes specifying [`upstreams`][upstreams].
   }
 ```
 
+The following is the complete `countdash` example. It includes an API service
+and a frontend Dashboard service which connects to the API service as a Connect
+upstream. Once running, the dashboard is accessible at `localhost:9002`.
+
+```hcl
+job "countdash" {
+  datacenters = ["dc1"]
+
+  group "api" {
+    network {
+      mode = "bridge"
+    }
+
+    service {
+      name = "count-api"
+      port = "9001"
+
+      connect {
+        sidecar_service {}
+      }
+
+      check {
+        expose   = true
+        type     = "http"
+        name     = "api-health"
+        path     = "/health"
+        interval = "10s"
+        timeout  = "3s"
+      }
+    }
+
+    task "web" {
+      driver = "docker"
+
+      config {
+        image = "hashicorpnomad/counter-api:v2"
+      }
+    }
+  }
+
+  group "dashboard" {
+    network {
+      mode = "bridge"
+
+      port "http" {
+        static = 9002
+        to     = 9002
+      }
+    }
+
+    service {
+      name = "count-dashboard"
+      port = "9002"
+
+      connect {
+        sidecar_service {
+          proxy {
+            upstreams {
+              destination_name = "count-api"
+              local_bind_port  = 8080
+            }
+          }
+        }
+      }
+    }
+
+    task "dashboard" {
+      driver = "docker"
+
+      env {
+        COUNTING_SERVICE_URL = "http://${NOMAD_UPSTREAM_ADDR_count_api}"
+      }
+
+      config {
+        image = "hashicorpnomad/counter-dashboard:v2"
+      }
+    }
+  }
+}
+```
+
 ### Limitations
 
 [Consul Connect Native services][native] and [Nomad variable
-interpolation][interpolation] are _not_ supported in Nomad 0.10.0.
+interpolation][interpolation] are _not_ yet supported.
 
 [job]: /docs/job-specification/job 'Nomad job Job Specification'
 [group]: /docs/job-specification/group 'Nomad group Job Specification'

website/pages/docs/job-specification/expose.mdx

@@ -16,7 +16,7 @@ description: |-
 The `expose` stanza allows configuration of additional listeners for the default Envoy sidecar
 proxy managed by Nomad for [Consul Connect](/guides/integrations/consul-connect). These
 listeners create a bypass of the Connect TLS and network namespace isolation, enabling
-non-Connect enabled services to make requests to specific paths through the sidecar proxy.
+non-Connect enabled services to make requests to specific HTTP paths through the sidecar proxy.
 
 The `expose` configuration is valid within the context of a `proxy` stanza. Additional
 information about Expose Path configurations for Envoy can be found in Consul's
@@ -26,46 +26,100 @@ Service [check](https://nomadproject.io/docs/job-specification/service/#check-pa
 configurations can use their [expose](/docs/job-specification/service#expose)
 parameter to automatically generate expose path configurations for HTTP and gRPC checks.
 
+```hcl
+job "expose-check-example" {
+  datacenters = ["dc1"]
+
+  group "api" {
+    network {
+      mode = "bridge"
+    }
+
+    service {
+      name = "count-api"
+      port = "9001"
+
+      connect {
+        sidecar_service {}
+      }
+
+      check {
+        expose   = true
+        name     = "api-health"
+        type     = "http"
+        path     = "/health"
+        interval = "10s"
+        timeout  = "3s"
+      }
+    }
+
+    task "web" {
+      driver = "docker"
+
+      config {
+        image = "hashicorpnomad/counter-api:v2"
+      }
+    }
+  }
+}
+```
+
+For uses other than Consul service checks, use the `expose` configuration in the
+`proxy` stanza. The example below effectively demonstrates exposing the `/health`
+endpoint similar to the example above, but using the fully flexible `expose`
+configuration.
+
 ```hcl
 job "expose-example" {
   datacenters = ["dc1"]
-  group "dashboard" {
+
+  group "api" {
     network {
       mode = "bridge"
-      port "expose" {
+
+      port "api_expose_healthcheck" {
         to = -1
       }
     }
 
     service {
-      name = "count-dashboard"
+      name = "count-api"
       port = "9001"
 
       connect {
         sidecar_service {
           proxy {
             expose {
               path {
-                path            = "/metrics"
+                path            = "/health"
                 protocol        = "http"
                 local_path_port = 9001
-                listener_port   = "expose"
+                listener_port   = "api_expose_healthcheck"
               }
             }
           }
         }
       }
 
       check {
-        name     = "dashboard-health"
+        name     = "api-health"
         type     = "http"
-        port     = "expose"
         path     = "/health"
+        port     = "api_expose_healthcheck"
         interval = "10s"
         timeout  = "3s"
-        expose   = true
       }
     }
+
+    task "web" {
+      driver = "docker"
+
+      config {
+        image = "hashicorpnomad/counter-api:v2"
+      }
+
+      # e.g. reference ${NOMAD_PORT_api_expose_healthcheck} for other uses
+    }
   }
 }
 ```
@@ -149,17 +203,17 @@ proxy {
 A common use case for `expose` is for exposing endpoints used in Consul service check
 definitions. For these cases the [expose](/docs/job-specification/service#expose)
 parameter in the service check stanza can be used to automatically generate the
-expose path configuration.
+expose path configuration. Configuring a port for use by the check is optional,
+as a dynamic port will be automatically generated if not provided.
 
 ```hcl
 check {
+  expose   = true
   type     = "http"
   name     = "dashboard-health"
-  port     = "expose"
   path     = "/health"
   interval = "10s"
   timeout  = "3s"
-  expose   = true
 }
 ```
 

website/pages/docs/job-specification/proxy.mdx

@@ -21,6 +21,7 @@ within the context of a `sidecar_service` stanza.
 ```hcl
 job "countdash" {
   datacenters = ["dc1"]
+
   group "api" {
     network {
       mode = "bridge"
@@ -36,10 +37,12 @@ job "countdash" {
         }
       }
     }
+
     task "web" {
       driver = "docker"
+
       config {
-        image = "test/test:v1"
+        image = "hashicorpnomad/counter-api:v2"
       }
     }
   }

website/pages/docs/job-specification/sidecar_service.mdx

@@ -17,30 +17,32 @@ Connect](/docs/integrations/consul-connect) integration. It is
 valid only within the context of a connect stanza.
 
 ```hcl
- job "countdash" {
-   datacenters = ["dc1"]
-   group "api" {
-     network {
-       mode = "bridge"
-     }
-
-     service {
-       name = "count-api"
-       port = "9001"
-
-       connect {
-         sidecar_service {}
-       }
-     }
-     task "web" {
-         driver = "docker"
-         config {
-           image = "test/test:v1"
-         }
-     }
-   }
- }
-
+job "countdash" {
+  datacenters = ["dc1"]
+
+  group "api" {
+    network {
+      mode = "bridge"
+    }
+
+    service {
+      name = "count-api"
+      port = "9001"
+
+      connect {
+        sidecar_service {}
+      }
+    }
+
+    task "web" {
+      driver = "docker"
+
+      config {
+        image = "hashicorpnomad/counter-api:v2"
+      }
+    }
+  }
+}
 ```
 
 ## `sidecar_service` Parameters