traefik/docs/index.md

222 lines
9.6 KiB
Markdown
Raw Normal View History

<p align="center">
2018-10-17 14:24:04 +00:00
<img src="img/traefik.logo.png" alt="Traefik" title="Traefik" />
</p>
2015-09-22 08:33:37 +00:00
[![Build Status SemaphoreCI](https://semaphoreci.com/api/v1/containous/traefik/branches/master/shields_badge.svg)](https://semaphoreci.com/containous/traefik)
[![Docs](https://img.shields.io/badge/docs-current-brightgreen.svg)](/)
2017-09-11 17:10:04 +00:00
[![Go Report Card](https://goreportcard.com/badge/github.com/containous/traefik)](https://goreportcard.com/report/github.com/containous/traefik)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/containous/traefik/blob/master/LICENSE.md)
2018-06-12 15:04:04 +00:00
[![Join the chat at https://slack.traefik.io](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://slack.traefik.io)
[![Twitter](https://img.shields.io/twitter/follow/traefik.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefik)
2015-09-22 08:33:37 +00:00
2018-10-17 14:24:04 +00:00
Traefik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy.
Traefik integrates with your existing infrastructure components ([Docker](https://www.docker.com/), [Swarm mode](https://docs.docker.com/engine/swarm/), [Kubernetes](https://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Consul](https://www.consul.io/), [Etcd](https://coreos.com/etcd/), [Rancher](https://rancher.com), [Amazon ECS](https://aws.amazon.com/ecs), ...) and configures itself automatically and dynamically.
Pointing Traefik at your orchestrator should be the _only_ configuration step you need.
## Overview
2018-03-22 11:34:03 +00:00
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.
2018-04-23 13:56:03 +00:00
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.
2018-10-17 14:24:04 +00:00
**This is when Traefik can help you!**
2018-10-17 14:24:04 +00:00
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.
2018-10-17 14:24:04 +00:00
**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!)_
2015-09-22 08:33:37 +00:00
![Architecture](img/architecture.png)
2015-09-22 08:33:37 +00:00
2017-08-25 18:40:03 +00:00
## Features
2018-03-22 11:34:03 +00:00
- Continuously updates its configuration (No restarts!)
- Supports multiple load balancing algorithms
2018-03-26 12:12:03 +00:00
- Provides HTTPS to your microservices by leveraging [Let's Encrypt](https://letsencrypt.org) (wildcard certificates support)
2017-08-25 18:40:03 +00:00
- Circuit breakers, retry
2018-03-22 11:34:03 +00:00
- High Availability with cluster mode (beta)
- See the magic through its clean web UI
2017-08-25 18:40:03 +00:00
- Websocket, HTTP/2, GRPC ready
2018-03-22 11:34:03 +00:00
- Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB)
- Keeps access logs (JSON, CLF)
- Fast
2018-03-22 11:34:03 +00:00
- Exposes a Rest API
2018-07-31 08:58:03 +00:00
- Packaged as a single binary file (made with ❤️ with go) and available as a [tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image
2017-08-25 18:40:03 +00:00
## Supported Providers
2017-08-25 18:40:03 +00:00
2018-03-22 11:34:03 +00:00
- [Docker](/configuration/backends/docker/) / [Swarm mode](/configuration/backends/docker/#docker-swarm-mode)
- [Kubernetes](/configuration/backends/kubernetes/)
- [Mesos](/configuration/backends/mesos/) / [Marathon](/configuration/backends/marathon/)
- [Rancher](/configuration/backends/rancher/) (API, Metadata)
2018-04-10 15:26:04 +00:00
- [Azure Service Fabric](/configuration/backends/servicefabric/)
2018-03-22 11:34:03 +00:00
- [Consul Catalog](/configuration/backends/consulcatalog/)
- [Consul](/configuration/backends/consul/) / [Etcd](/configuration/backends/etcd/) / [Zookeeper](/configuration/backends/zookeeper/) / [BoltDB](/configuration/backends/boltdb/)
- [Eureka](/configuration/backends/eureka/)
- [Amazon ECS](/configuration/backends/ecs/)
- [Amazon DynamoDB](/configuration/backends/dynamodb/)
- [File](/configuration/backends/file/)
- [Rest](/configuration/backends/rest/)
2015-09-22 08:33:37 +00:00
2018-10-17 14:24:04 +00:00
## The Traefik Quickstart (Using Docker)
2015-09-22 08:33:37 +00:00
2018-03-22 11:34:03 +00:00
In this quickstart, we'll use [Docker compose](https://docs.docker.com/compose) to create our demo infrastructure.
2016-11-16 10:48:08 +00:00
2018-10-17 14:24:04 +00:00
To save some time, you can clone [Traefik's repository](https://github.com/containous/traefik) and use the quickstart files located in the [examples/quickstart](https://github.com/containous/traefik/tree/master/examples/quickstart/) directory.
2016-11-16 10:48:08 +00:00
2018-10-17 14:24:04 +00:00
### 1 — Launch Traefik — Tell It to Listen to Docker
2015-09-22 08:33:37 +00:00
2018-10-17 14:24:04 +00:00
Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Traefik image:
2015-09-22 08:33:37 +00:00
```yaml
version: '3'
services:
2018-03-22 11:34:03 +00:00
reverse-proxy:
image: traefik # The official Traefik docker image
2018-10-17 14:24:04 +00:00
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
2015-09-22 08:33:37 +00:00
```
!!! warning
2018-10-09 16:36:03 +00:00
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](/configuration/api#security).
2018-10-17 14:24:04 +00:00
**That's it. Now you can launch Traefik!**
2018-03-22 11:34:03 +00:00
Start your `reverse-proxy` with the following command:
2017-09-05 13:58:03 +00:00
```shell
2018-04-23 13:56:03 +00:00
docker-compose up -d reverse-proxy
2017-09-05 13:58:03 +00:00
```
2018-10-17 14:24:04 +00:00
You can open a browser and go to [http://localhost:8080](http://localhost:8080) to see Traefik's dashboard (we'll go back there once we have launched a service in step 2).
2018-10-17 14:24:04 +00:00
### 2 — Launch a Service — Traefik Detects It and Creates a Route for You
2018-10-17 14:24:04 +00:00
Now that we have a Traefik instance up and running, we will deploy new services.
2018-04-23 13:56:03 +00:00
Edit your `docker-compose.yml` file and add the following at the end of your file.
2018-03-22 11:34:03 +00:00
```yaml
2018-04-23 13:56:03 +00:00
# ...
whoami:
image: containous/whoami # A container that exposes an API to show its IP address
labels:
- "traefik.frontend.rule=Host:whoami.docker.localhost"
```
2018-03-22 11:34:03 +00:00
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).
2018-03-22 11:34:03 +00:00
Start the `whoami` service with the following command:
2018-04-23 13:56:03 +00:00
2017-04-30 18:17:57 +00:00
```shell
2018-03-22 11:34:03 +00:00
docker-compose up -d whoami
2015-09-22 08:33:37 +00:00
```
2018-10-17 14:24:04 +00:00
Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Traefik has automatically detected the new container and updated its own configuration.
2018-03-22 11:34:03 +00:00
When Traefik detects new services, it creates the corresponding routes so you can call them ... _let's see!_ (Here, we're using curl)
2015-09-22 08:33:37 +00:00
2017-04-30 18:17:57 +00:00
```shell
2017-09-05 13:58:03 +00:00
curl -H Host:whoami.docker.localhost http://127.0.0.1
```
2018-03-22 11:34:03 +00:00
_Shows the following output:_
2017-09-05 13:58:03 +00:00
```yaml
2018-03-22 11:34:03 +00:00
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:
2018-04-23 13:56:03 +00:00
2018-03-22 11:34:03 +00:00
```shell
2018-08-06 12:08:03 +00:00
docker-compose scale whoami=2
2017-09-05 13:58:03 +00:00
```
2018-10-17 14:24:04 +00:00
Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Traefik has automatically detected the new instance of the container.
2018-03-22 11:34:03 +00:00
2018-10-17 14:24:04 +00:00
Finally, see that Traefik load-balances between the two instances of your services by running twice the following command:
2018-03-22 11:34:03 +00:00
2017-09-05 13:58:03 +00:00
```shell
curl -H Host:whoami.docker.localhost http://127.0.0.1
```
2018-03-22 11:34:03 +00:00
The output will show alternatively one of the followings:
2017-09-05 13:58:03 +00:00
```yaml
2018-03-22 11:34:03 +00:00
Hostname: 8656c8ddca6c
IP: 172.27.0.3
#...
2016-03-08 15:27:12 +00:00
```
2018-03-22 11:34:03 +00:00
```yaml
Hostname: 8458f154e1f1
IP: 172.27.0.4
# ...
```
2018-10-17 14:24:04 +00:00
### 4 — Enjoy Traefik's Magic
2018-03-22 11:34:03 +00:00
2018-10-17 14:24:04 +00:00
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](/#supported-providers) that will do the job.
2018-03-22 11:34:03 +00:00
2018-10-17 14:24:04 +00:00
Our recommendation would be to see for yourself how simple it is to enable HTTPS with [Traefik's let's encrypt integration](/user-guide/examples/#lets-encrypt-support) using the dedicated [user guide](/user-guide/docker-and-lets-encrypt/).
2018-03-22 11:34:03 +00:00
## Resources
2018-11-19 15:40:03 +00:00
Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at GopherCon 2017.
2018-10-17 14:24:04 +00:00
You will learn Traefik basics in less than 10 minutes.
2018-03-22 11:34:03 +00:00
[![Traefik GopherCon 2017](https://img.youtube.com/vi/RgudiksfL-k/0.jpg)](https://www.youtube.com/watch?v=RgudiksfL-k)
Here is a talk given by [Ed Robinson](https://github.com/errm) at [ContainerCamp UK](https://container.camp) conference.
2018-10-17 14:24:04 +00:00
You will learn fundamental Traefik features and see some demos with Kubernetes.
2018-03-22 11:34:03 +00:00
[![Traefik ContainerCamp UK](https://img.youtube.com/vi/aFtpIShV60I/0.jpg)](https://www.youtube.com/watch?v=aFtpIShV60I)
## Downloads
### The Official Binary File
You can grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page and just run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml):
```shell
./traefik -c traefik.toml
```
### The Official Docker Image
Using the tiny Docker image:
```shell
docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik
2018-04-23 13:56:03 +00:00
```
2018-08-20 15:08:03 +00:00
## Security
2018-08-22 08:18:03 +00:00
### 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 security+subscribe@traefik.io or on [the online viewer](https://groups.google.com/a/traefik.io/forum/#!forum/security).
### CVE
Reported vulnerabilities can be found on
[cve.mitre.org](https://cve.mitre.org/cgi-bin/cvekey.cgi?keyword=traefik).
### Report a Vulnerability
2018-10-17 14:24:04 +00:00
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](https://security.traefik.io).