diff --git a/website/source/assets/images/traefik_ui.png b/website/source/assets/images/traefik_ui.png new file mode 100644 index 000000000..0c3a6cb8d Binary files /dev/null and b/website/source/assets/images/traefik_ui.png differ diff --git a/website/source/guides/load-balancing/load-balancing.html.md b/website/source/guides/load-balancing/load-balancing.html.md index c7a7466fd..f09334a90 100644 --- a/website/source/guides/load-balancing/load-balancing.html.md +++ b/website/source/guides/load-balancing/load-balancing.html.md @@ -18,6 +18,7 @@ Consul](https://www.hashicorp.com/blog/load-balancing-strategies-for-consul)). - [Fabio](/guides/load-balancing/fabio.html) - [NGINX](/guides/load-balancing/nginx.html) - [HAProxy](/guides/load-balancing/haproxy.html) +- [Traefik](/guides/load-balancing/traefik.html) Please refer to the specific documentation above or in the sidebar for more detailed information about each strategy. diff --git a/website/source/guides/load-balancing/traefik.html.md b/website/source/guides/load-balancing/traefik.html.md new file mode 100644 index 000000000..b170ac988 --- /dev/null +++ b/website/source/guides/load-balancing/traefik.html.md @@ -0,0 +1,272 @@ +--- +layout: "guides" +page_title: "Load Balancing with Traefik" +sidebar_current: "guides-load-balancing-traefik" +description: |- + There are multiple approaches to load balancing within a Nomad cluster. + One approach involves using [Traefik][traefik] which natively integrates + with service discovery data from Consul. +--- + +# Load Balancing with Traefik + +The main use case for Traefik in this scenario is to distribute incoming HTTP(S) +and TCP requests from the internet to frontend services that can handle these +requests. This guide will show you one such example using a demo web +application. + +Traefik can natively integrate with Consul using the [Consul Catalog +Provider][traefik-consul-provider] and can use [tags][traefik-tags] to route +traffic. + +## Reference Material + +- [Traefik][traefik] +- [Traefik Consul Catalog Provider Documentation][traefik-consul-provider] + +## Estimated Time to Complete + +20 minutes + +## Prerequisites + +To perform the tasks described in this guide, you need to have a Nomad +environment with Consul installed. You can use this [repo][terraform-repo] to +easily provision a sandbox environment. This guide will assume a cluster with +one server node and three client nodes. + +-> **Note:** This guide is for demo purposes and only assumes a single server +node. Please consult the [reference architecture][reference-arch] for production +configuration. + +## Steps + +### Step 1: Create a Job for Demo Web App + +Create a job for a demo web application and name the file `webapp.nomad`: + +```hcl +job "demo-webapp" { + datacenters = ["dc1"] + + group "demo" { + count = 3 + + task "server" { + env { + PORT = "${NOMAD_PORT_http}" + NODE_IP = "${NOMAD_IP_http}" + } + + driver = "docker" + + config { + image = "hashicorp/demo-webapp-lb-guide" + } + + resources { + network { + mbits = 10 + port "http" {} + } + } + + service { + name = "demo-webapp" + port = "http" + tags = [ + "traefik.tags=service", + "traefik.frontend.rule=PathPrefixStrip:/myapp", + ] + + check { + type = "http" + path = "/" + interval = "2s" + timeout = "2s" + } + } + } + } +} +``` + +- Note that this job deploys 3 instances of our demo web application which we + will load balance with Traefik in the next few steps. +- We are using tags to configure routing to our web app. Even though our + application listens on `/`, it is possible to define `/myapp` as the route + because of the [`PathPrefixStrip`][matchers] option. + +### Step 2: Deploy the Demo Web App + +We can now deploy our demo web application: + +```shell +$ nomad run webapp.nomad +==> Monitoring evaluation "a2061ab7" + Evaluation triggered by job "demo-webapp" + Evaluation within deployment: "8ca6d358" + Allocation "1d14babe" created: node "2d6eea6e", group "demo" + Allocation "3abb950d" created: node "a62fa99d", group "demo" + Allocation "c65e14bf" created: node "a209a662", group "demo" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "a2061ab7" finished with status "complete" +``` + +### Step 3: Create a Job for Traefik + +Create a job for Traefik and name it `traefik.nomad`. This will be our load +balancer that will balance requests to the deployed instances of our web +application. + +```hcl +job "traefik" { + region = "global" + datacenters = ["dc1"] + type = "service" + + group "traefik" { + count = 1 + + task "traefik" { + driver = "docker" + + config { + image = "traefik:1.7" + network_mode = "host" + + port_map { + http = 8080 + api = 8081 + } + + volumes = [ + "local/traefik.toml:/etc/traefik/traefik.toml", + ] + } + + template { + data = < Monitoring evaluation "e22ce276" + Evaluation triggered by job "traefik" + Evaluation within deployment: "c6466497" + Allocation "695c5632" created: node "a62fa99d", group "traefik" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "e22ce276" finished with status "complete" +``` + +### Step 5: Check the Traefik Dashboard + +You can visit the dashboard for Traefik at +`http://:8081`. You can use this page to verify your +settings and for basic monitoring. + +[![Home Page][traefik_ui]][traefik_ui] + +### Step 6: Make a Request to the Load Balancer + +If you query the Traefik load balancer, you should be able to see a response +similar to the one shown below (this command should be run from a +node inside your cluster): + +```shell +$ curl http://traefik.service.consul:8080/myapp +Welcome! You are on node 172.31.28.103:28893 +``` + +Note that your request has been forwarded to one of the several deployed +instances of the demo web application (which is spread across 3 Nomad clients). +The output shows the IP address of the host it is deployed on. If you repeat +your requests, you will see that the IP address changes. + +* Note: if you would like to access Traefik from outside your cluster, you + can set up a load balancer in your environment that maps to an active port + `8080` on your clients (or whichever port you have configured for Traefik to + listen on). You can then send your requests directly to your external load + balancer. + +[inline]: /docs/job-specification/template.html#inline-template +[matchers]: https://docs.traefik.io/v1.4/basics/#matchers +[reference-arch]: /guides/install/production/reference-architecture.html#high-availability +[remote-template]: /docs/job-specification/template.html#remote-template +[template-stanza]: /docs/job-specification/template.html +[terraform-repo]: https://github.com/hashicorp/nomad/tree/master/terraform#provision-a-nomad-cluster-in-the-cloud +[traefik]: https://traefik.io/ +[traefik_ui]: /assets/images/traefik_ui.png +[traefik-consul-provider]: https://docs.traefik.io/v1.7/configuration/backends/consulcatalog/ +[traefik-tags]: https://docs.traefik.io/v1.5/configuration/backends/consulcatalog/#tags diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 59976c34e..ed5985a4d 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -269,6 +269,11 @@ HAProxy + >