From 4596f00d40d8ffcb7797995d72b0109aa681444b Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 17:25:06 -0400 Subject: [PATCH 01/11] formatting paragraphs --- .../integrations/consul-connect/index.html.md | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index cbf8e07b3..20feeccc6 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -10,31 +10,34 @@ description: |- ~> **Note** This guide describes a new feature available in the [Nomad 0.10.0 Connect Technology Preview release][download] of Nomad for [Hashiconf EU - 2019][hashiconfeu]. This is not intended for production use and has many known - [limitations](#limitations). + 2019][hashiconfeu]. This is not intended for production use and has many + known [limitations](#limitations). [download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ [hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 -[Consul Connect](https://www.consul.io/docs/connect/index.html) provides service-to-service connection -authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh -configuration to automatically establish TLS connections for inbound and outbound connections -without being aware of Connect at all. +[Consul Connect](https://www.consul.io/docs/connect/index.html) provides +service-to-service connection authorization and encryption using mutual +Transport Layer Security (TLS). Applications can use sidecar proxies in a +service mesh configuration to automatically establish TLS connections for +inbound and outbound connections without being aware of Connect at all. # Nomad with Consul Connect Integration -Nomad integrates with Consul to provide secure service-to-service communication between -Nomad jobs and task groups. In order to support Consul Connect, Nomad adds a new networking -mode for jobs that enables tasks in the same task group to share their networking stack. With -a few changes to the job specification, job authors can opt into Connect integration. When Connect -is enabled, Nomad will launch a proxy alongside the application in the job file. The proxy (Envoy) +Nomad integrates with Consul to provide secure service-to-service communication +between Nomad jobs and task groups. In order to support Consul Connect, Nomad +adds a new networking mode for jobs that enables tasks in the same task group to +share their networking stack. With a few changes to the job specification, job +authors can opt into Connect integration. When Connect is enabled, Nomad will +launch a proxy alongside the application in the job file. The proxy (Envoy) provides secure communication with other applications in the cluster. -Nomad job specification authors can use Nomad's Consul Connect integration to implement -[service segmentation](https://www.consul.io/segmentation.html) in a -microservice architecture running in public clouds without having to directly manage -TLS certificates. This is transparent to job specification authors as security features -in Connect continue to work even as the application scales up or down or gets rescheduled by Nomad. +Nomad job specification authors can use Nomad's Consul Connect integration to +implement [service segmentation](https://www.consul.io/segmentation.html) in a +microservice architecture running in public clouds without having to directly +manage TLS certificates. This is transparent to job specification authors as +security features in Connect continue to work even as the application scales up +or down or gets rescheduled by Nomad. # Nomad Consul Connect Example From a98fe3c9caa92eb297039ef7c64cdca38180601a Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 17:30:45 -0400 Subject: [PATCH 02/11] remove reference to consul 1.6-beta and update nomad agent command --- .../integrations/consul-connect/index.html.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 20feeccc6..8affcc6ac 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -52,9 +52,11 @@ managed by Nomad, and handles mTLS communication to the Redis container. ### Consul -Connect integration with Nomad requires [Consul 1.6-beta1 or -later.](https://releases.hashicorp.com/consul/1.6.0-beta1/) The -Consul agent can be run in dev mode with the following command: +Connect integration with Nomad requires [Consul 1.6 or +later.](https://releases.hashicorp.com/consul/1.6.0/) The Consul agent can be +run in dev mode with the following command: + +**Note**: for this demo to work, consul must be in your $PATH ```sh $ consul agent -dev @@ -67,15 +69,7 @@ connect to each other. The following steps show how to start a Nomad dev agent configured for Connect. ```sh -$ go get -u github.com/hashicorp/go-sockaddr/cmd/sockaddr -$ export DEFAULT_IFACE=$(sockaddr eval 'GetAllInterfaces | sort "default" | unique "name" | attr "name"') -$ sudo nomad agent -dev -network-interface $DEFAULT_IFACE -``` - -Alternatively if you know the network interface Nomad should use: - -```sh -$ sudo nomad agent -dev -network-interface eth0 +$ sudo nomad agent -dev-connect ``` ### CNI Plugins From 1e904a28a9e1df691adcbf13617d0f873a67bfbe Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 17:46:02 -0400 Subject: [PATCH 03/11] remove tech preview status and update limitations --- .../integrations/consul-connect/index.html.md | 22 +++++-------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 8affcc6ac..4f2034e45 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -8,14 +8,6 @@ description: |- # Consul Connect -~> **Note** This guide describes a new feature available in the [Nomad 0.10.0 - Connect Technology Preview release][download] of Nomad for [Hashiconf EU - 2019][hashiconfeu]. This is not intended for production use and has many - known [limitations](#limitations). - -[download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ -[hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 - [Consul Connect](https://www.consul.io/docs/connect/index.html) provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a @@ -260,13 +252,11 @@ dashes (`-`) are converted to underscores (`_`) in environment variables so ## Limitations -Prior to Nomad 0.10.0's final release, the Consul Connect integration has -several limitations that have yet to be addressed: - - - Jobs with a `connect` stanza may not update properly. Workaround this by - stopping and starting Connect-enabled jobs. + - Consul Connect Native is not yet supported + - Consul Connect HTTP and gRPC checks are not yet supported + - Consul ACLs are not yet supported - Only the Docker, exec, and raw exec drivers support network namespaces and Connect. - - Not all Connect configuration options in Consul are available in Nomad. - - The Envoy proxy is not yet configurable and is hardcoded to use 100 MHz of - cpu and 300 MB of memory. + +[download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ +[hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 \ No newline at end of file From f8e010515bfb3f753a1c6909b9b7bc558d8b24c6 Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 17:48:23 -0400 Subject: [PATCH 04/11] remove beta tag in navigation --- website/source/layouts/guides.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index ef12a0bc9..716e3442e 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -51,7 +51,7 @@ Consul > - Consul Connect Beta + Consul Connect > Vault From ea7eb660ae7831ccff89fe0b973ffc598dad68a7 Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 18:00:49 -0400 Subject: [PATCH 05/11] add screenshot of count dashboard --- website/source/assets/images/count-dashboard.png | 3 +++ .../source/guides/integrations/consul-connect/index.html.md | 5 ++++- 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 website/source/assets/images/count-dashboard.png diff --git a/website/source/assets/images/count-dashboard.png b/website/source/assets/images/count-dashboard.png new file mode 100644 index 000000000..5aa315ad1 --- /dev/null +++ b/website/source/assets/images/count-dashboard.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bc969c9c2929e39d0de0c9e86596f664de892f52344ac82b88d3f69726602da0 +size 1011333 diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 4f2034e45..3fa54ff28 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -211,7 +211,9 @@ a host network interface. The `to = 9002` parameter forwards that host port to port 9002 inside the network namespace. This allows you to connect to the web frontend in a browser by visiting -`http://:9002`. +`http://:9002` as show below: + +[![Count Dashboard][count-dashboard]][count-dashboard] The web frontend connects to the API service via Consul Connect: @@ -258,5 +260,6 @@ dashes (`-`) are converted to underscores (`_`) in environment variables so - Only the Docker, exec, and raw exec drivers support network namespaces and Connect. +[count-dashboard]: /assets/images/count-dashboard.png [download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ [hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 \ No newline at end of file From deb2a250f041051876cc781f7354a8ec2685e91f Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 19:58:47 -0400 Subject: [PATCH 06/11] update example summary and remove redis references --- .../guides/integrations/consul-connect/index.html.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 3fa54ff28..e357fed52 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -34,11 +34,11 @@ or down or gets rescheduled by Nomad. # Nomad Consul Connect Example The following section walks through an example to enable secure communication -between a web application and a Redis container. The web application and the -Redis container are managed by Nomad. Nomad additionally configures Envoy -proxies to run along side these applications. The web application is configured -to connect to Redis via localhost and Redis's default port (6379). The proxy is -managed by Nomad, and handles mTLS communication to the Redis container. +between a web dashboard and a backend counting service. The web dashboard and +the counting service are managed by Nomad. Nomad additionally configures Envoy +proxies to run along side these applications. The dashboard is configured to +connect to the counting service via localhost on port 9001. The proxy is managed +by Nomad, and handles mTLS communication to the counting service. ## Prerequisites @@ -80,7 +80,7 @@ $ sudo tar -C /opt/cni/bin -xzf cni-plugins.tgz ## Run the Connect-enabled Services -Once Nomad and Consul are running submit the following Connect-enabled services +Once Nomad and Consul are running, submit the following Connect-enabled services to Nomad by copying the HCL into a file named `connect.nomad` and running: `nomad run connect.nomad` From e866e92ff4f4328da013aae7a31868a9cad4efca Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Wed, 4 Sep 2019 20:56:38 -0400 Subject: [PATCH 07/11] capitalize Consul --- website/source/guides/integrations/consul-connect/index.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index e357fed52..29cfdeaf6 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -48,7 +48,7 @@ Connect integration with Nomad requires [Consul 1.6 or later.](https://releases.hashicorp.com/consul/1.6.0/) The Consul agent can be run in dev mode with the following command: -**Note**: for this demo to work, consul must be in your $PATH +**Note**: for this demo to work, Consul must be in your $PATH ```sh $ consul agent -dev From 58f13da372ab2fa02cd6b6779a5b13cf79c3e577 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 5 Sep 2019 08:56:39 -0700 Subject: [PATCH 08/11] minor corrections * hcl formatting * demo is on localhost not host ip * clarify consul on PATH --- .../integrations/consul-connect/index.html.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 29cfdeaf6..2c3ee22e8 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -48,7 +48,7 @@ Connect integration with Nomad requires [Consul 1.6 or later.](https://releases.hashicorp.com/consul/1.6.0/) The Consul agent can be run in dev mode with the following command: -**Note**: for this demo to work, Consul must be in your $PATH +**Note**: Nomad's Connect integration requires Consul in your `$PATH` ```sh $ consul agent -dev @@ -111,7 +111,7 @@ to Nomad by copying the HCL into a file named `connect.nomad` and running: group "dashboard" { network { - mode ="bridge" + mode = "bridge" port "http" { static = 9002 to = 9002 @@ -211,7 +211,7 @@ a host network interface. The `to = 9002` parameter forwards that host port to port 9002 inside the network namespace. This allows you to connect to the web frontend in a browser by visiting -`http://:9002` as show below: +http://127.0.0.1:9002 as show below: [![Count Dashboard][count-dashboard]][count-dashboard] @@ -254,12 +254,14 @@ dashes (`-`) are converted to underscores (`_`) in environment variables so ## Limitations - - Consul Connect Native is not yet supported - - Consul Connect HTTP and gRPC checks are not yet supported - - Consul ACLs are not yet supported + - The `consul` binary must be present in Nomad's `$PATH` to run the Envoy + proxy sidecar on client nodes. + - Consul Connect Native is not yet supported. + - Consul Connect HTTP and gRPC checks are not yet supported. + - Consul ACLs are not yet supported. - Only the Docker, exec, and raw exec drivers support network namespaces and Connect. [count-dashboard]: /assets/images/count-dashboard.png [download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ -[hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 \ No newline at end of file +[hashiconfeu]: https://hashiconfeu.hashicorp.com/schedule/service-mesh-with-consul-connect-and-nomad-0.10 From a59e8ca4a62765bcc50cd1c50a43516a4063a5e0 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Thu, 5 Sep 2019 08:58:24 -0700 Subject: [PATCH 09/11] mention variable interpolation limitation --- website/source/guides/integrations/consul-connect/index.html.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 2c3ee22e8..ba8db981a 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -261,6 +261,8 @@ dashes (`-`) are converted to underscores (`_`) in environment variables so - Consul ACLs are not yet supported. - Only the Docker, exec, and raw exec drivers support network namespaces and Connect. + - Variable interpolation for group services and checks are not yet supported. + [count-dashboard]: /assets/images/count-dashboard.png [download]: https://releases.hashicorp.com/nomad/0.10.0-connect1/ From 6f50f0eb6fa44fa8b823190323614b274f998cee Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Thu, 5 Sep 2019 12:08:55 -0400 Subject: [PATCH 10/11] change localhost to host ip --- website/source/guides/integrations/consul-connect/index.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index ba8db981a..585e0b1ad 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -211,7 +211,7 @@ a host network interface. The `to = 9002` parameter forwards that host port to port 9002 inside the network namespace. This allows you to connect to the web frontend in a browser by visiting -http://127.0.0.1:9002 as show below: +http://:9002 as show below: [![Count Dashboard][count-dashboard]][count-dashboard] From 77464b700b1ac3445c4cbefd8c1999d35a03b9b8 Mon Sep 17 00:00:00 2001 From: Omar Khawaja Date: Thu, 5 Sep 2019 12:20:34 -0400 Subject: [PATCH 11/11] fix typo --- website/source/guides/integrations/consul-connect/index.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/guides/integrations/consul-connect/index.html.md b/website/source/guides/integrations/consul-connect/index.html.md index 585e0b1ad..00a4374c3 100644 --- a/website/source/guides/integrations/consul-connect/index.html.md +++ b/website/source/guides/integrations/consul-connect/index.html.md @@ -211,7 +211,7 @@ a host network interface. The `to = 9002` parameter forwards that host port to port 9002 inside the network namespace. This allows you to connect to the web frontend in a browser by visiting -http://:9002 as show below: +`http://:9002` as show below: [![Count Dashboard][count-dashboard]][count-dashboard]