

Getting Started

Traefik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. Traefik integrates with your existing infrastructure components (Docker, Swarm mode, Kubernetes, Marathon, Consul, Etcd, Rancher, Amazon ECS, ...) and configures itself automatically and dynamically. Pointing Traefik at your orchestrator should be the only configuration step you need.

Overview¶

Imagine that you have deployed a bunch of microservices with the help of an orchestrator (like Swarm or Kubernetes) or a service registry (like etcd or consul). Now you want users to access these microservices, and you need a reverse proxy.

Traditional reverse-proxies require that you configure each route that will connect paths and subdomains to each microservice. In an environment where you add, remove, kill, upgrade, or scale your services many times a day, the task of keeping the routes up to date becomes tedious.

This is when Traefik can help you!

Traefik listens to your service registry/orchestrator API and instantly generates the routes so your microservices are connected to the outside world -- without further intervention from your part.

Run Traefik and let it do the work for you! (But if you'd rather configure some of your routes manually, Traefik supports that too!)

Architecture

Features¶

Continuously updates its configuration (No restarts!)
Supports multiple load balancing algorithms
Provides HTTPS to your microservices by leveraging Let's Encrypt (wildcard certificates support)
Circuit breakers, retry
High Availability with cluster mode (beta)
See the magic through its clean web UI
Websocket, HTTP/2, GRPC ready
Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB)
Keeps access logs (JSON, CLF)
Fast
Exposes a Rest API
Packaged as a single binary file (made with ❤️ with go) and available as a tiny official docker image

Supported Providers¶

The Traefik Quickstart (Using Docker)¶

In this quickstart, we'll use Docker compose to create our demo infrastructure.

To save some time, you can clone Traefik's repository and use the quickstart files located in the examples/quickstart directory.

1 — Launch Traefik — Tell It to Listen to Docker¶

Create a docker-compose.yml file where you will define a reverse-proxy service that uses the official Traefik image:

version: '3'

services:
  reverse-proxy:
    image: traefik:v1.7 # The official Traefik docker image
    command: --api --docker # Enables the web UI and tells Traefik to listen to docker
    ports:
      - "80:80"     # The HTTP port
      - "8080:8080" # The Web UI (enabled by --api)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # So that Traefik can listen to the Docker events

Warning

Enabling the Web UI with the --api flag might expose configuration elements. You can read more about this on the API/Dashboard's Security section.

That's it. Now you can launch Traefik!

Start your reverse-proxy with the following command:

docker-compose up -d reverse-proxy

You can open a browser and go to http://localhost:8080 to see Traefik's dashboard (we'll go back there once we have launched a service in step 2).

2 — Launch a Service — Traefik Detects It and Creates a Route for You¶

Now that we have a Traefik instance up and running, we will deploy new services.

Edit your docker-compose.yml file and add the following at the end of your file.

# ...
  whoami:
    image: traefik/whoami # A container that exposes an API to show its IP address
    labels:
      - "traefik.frontend.rule=Host:whoami.docker.localhost"

The above defines whoami: a simple web service that outputs information about the machine it is deployed on (its IP address, host, and so on).

Start the whoami service with the following command:

docker-compose up -d whoami

Go back to your browser (http://localhost:8080) and see that Traefik has automatically detected the new container and updated its own configuration.

When Traefik detects new services, it creates the corresponding routes so you can call them ... let's see! (Here, we're using curl)

curl -H Host:whoami.docker.localhost http://127.0.0.1

Shows the following output:

Hostname: 8656c8ddca6c
IP: 172.27.0.3
#...

3 — Launch More Instances — Traefik Load Balances Them¶

Run more instances of your whoami service with the following command:

docker-compose scale whoami=2

Go back to your browser (http://localhost:8080) and see that Traefik has automatically detected the new instance of the container.

Finally, see that Traefik load-balances between the two instances of your services by running twice the following command:

curl -H Host:whoami.docker.localhost http://127.0.0.1

The output will show alternatively one of the followings:

Hostname: 8656c8ddca6c
IP: 172.27.0.3
#...

Hostname: 8458f154e1f1
IP: 172.27.0.4
# ...

4 — Enjoy Traefik's Magic¶

Now that you have a basic understanding of how Traefik can automatically create the routes to your services and load balance them, it might be time to dive into the documentation and let Traefik work for you! Whatever your infrastructure is, there is probably an available Traefik provider that will do the job.

Our recommendation would be to see for yourself how simple it is to enable HTTPS with Traefik's let's encrypt integration using the dedicated user guide.

Resources¶

Here is a talk given by Emile Vauge at GopherCon 2017. You will learn Traefik basics in less than 10 minutes.

Here is a talk given by Ed Robinson at ContainerCamp UK conference. You will learn fundamental Traefik features and see some demos with Kubernetes.

Downloads¶

The Official Binary File¶

You can grab the latest binary from the releases page and just run it with the sample configuration file:

./traefik -c traefik.toml

The Official Docker Image¶

Using the tiny Docker image:

docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik

Security¶

Security Advisories¶

We strongly advise you to join our mailing list to be aware of the latest announcements from our security team. You can subscribe sending a mail to [email protected] or on the online viewer.

CVE¶

Reported vulnerabilities can be found on cve.mitre.org.

Report a Vulnerability¶

We want to keep Traefik safe for everyone. If you've discovered a security vulnerability in Traefik, we appreciate your help in disclosing it to us in a responsible manner, using this form.