diff --git a/README.md b/README.md index 2ff4947ed..7a910885e 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,9 @@ [![Twitter](https://img.shields.io/twitter/follow/traefikproxy.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefikproxy) -Træfik (pronounced like _traffic_) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. -It supports several backends ([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 a lot more) to manage its configuration automatically and dynamically. +Træfik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. +Træfik 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. +Telling Træfik where your orchestrator is could be the _only_ configuration step you need to do. --- @@ -36,60 +37,101 @@ It supports several backends ([Docker](https://www.docker.com/), [Swarm mode](ht ## Overview -Imagine that you have deployed a bunch of microservices on your infrastructure. You probably used a service registry (like etcd or consul) and/or an orchestrator (swarm, Mesos/Marathon) to manage all these services. -If you want your users to access some of your microservices from the Internet, you will have to use a reverse proxy and configure it using virtual hosts or prefix paths: +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. -- domain `api.domain.com` will point the microservice `api` in your private network -- path `domain.com/web` will point the microservice `web` in your private network -- domain `backoffice.domain.com` will point the microservices `backoffice` in your private network, load-balancing between your multiple instances +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. -Microservices are often deployed in dynamic environments where services are added, removed, killed, upgraded or scaled many times a day. +**This is when Træfik can help you!** -Traditional reverse-proxies are not natively dynamic. You can't change their configuration and hot-reload easily. +Træfik 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. -Here enters Træfik. +**Run Træfik and let it do the work for you!** +_(But if you'd rather configure some of your routes manually, Træfik supports that too!)_ ![Architecture](docs/img/architecture.png) -Træfik can listen to your service registry/orchestrator API, and knows each time a microservice is added, removed, killed or upgraded, and can generate its configuration automatically. -Routes to your services will be created instantly. - -Run it and forget it! - - ## Features -- [It's fast](https://docs.traefik.io/benchmarks) -- No dependency hell, single binary made with go -- [Tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -- Rest API -- Hot-reloading of configuration. No need to restart the process +- Continuously updates its configuration (No restarts!) +- Supports multiple load balancing algorithms +- Provides HTTPS to your microservices by leveraging [Let's Encrypt](https://letsencrypt.org) - Circuit breakers, retry -- Round Robin, rebalancer load-balancers -- Metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) -- Clean AngularJS Web UI -- Websocket, HTTP/2, GRPC ready -- Access Logs (JSON, CLF) -- [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS with renewal) -- [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) support - 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](https://docs.traefik.io/benchmarks) ... which is nice +- Exposes a Rest API +- Packaged as a single binary file (made with :heart: with go) and available as a [tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -## Supported backends -- [Docker](https://www.docker.com/) / [Swarm mode](https://docs.docker.com/engine/swarm/) -- [Kubernetes](https://kubernetes.io) -- [Mesos](https://github.com/apache/mesos) / [Marathon](https://mesosphere.github.io/marathon/) -- [Rancher](https://rancher.com) (API, Metadata) -- [Consul](https://www.consul.io/) / [Etcd](https://coreos.com/etcd/) / [Zookeeper](https://zookeeper.apache.org) / [BoltDB](https://github.com/boltdb/bolt) -- [Eureka](https://github.com/Netflix/eureka) -- [Amazon ECS](https://aws.amazon.com/ecs) -- [Amazon DynamoDB](https://aws.amazon.com/dynamodb) -- File -- Rest API +## Supported Backends + +- [Docker](docs/configuration/backends/docker/) / [Swarm mode](docs/configuration/backends/docker/#docker-swarm-mode) +- [Kubernetes](docs/configuration/backends/kubernetes/) +- [Mesos](docs/configuration/backends/mesos/) / [Marathon](docs/configuration/backends/marathon/) +- [Rancher](docs/configuration/backends/rancher/) (API, Metadata) +- [Service Fabric](docs/configuration/backends/servicefabric/) +- [Consul Catalog](docs/configuration/backends/consulcatalog/) +- [Consul](docs/configuration/backends/consul/) / [Etcd](docs/configuration/backends/etcd/) / [Zookeeper](docs/configuration/backends/zookeeper/) / [BoltDB](docs/configuration/backends/boltdb/) +- [Eureka](docs/configuration/backends/eureka/) +- [Amazon ECS](docs/configuration/backends/ecs/) +- [Amazon DynamoDB](docs/configuration/backends/dynamodb/) +- [File](docs/configuration/backends/file/) +- [Rest](docs/configuration/backends/rest/) ## Quickstart -You can have a quick look at Træfik in this [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. If you are looking for a more comprehensive and real use-case example, you can also check [Play-With-Docker](http://training.play-with-docker.com/traefik-load-balancing/) to see how to load balance between multiple nodes. +To get your hands on Træfik, you can use the [5-Minute Quickstart](http://docs.traefik.io/#the-trfik-quickstart-using-docker) in our documentation (you will need Docker). + +Alternatively, if you don't want to install anything on your computer, you can try Træfik online in this great [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. + +If you are looking for a more comprehensive and real use-case example, you can also check [Play-With-Docker](http://training.play-with-docker.com/traefik-load-balancing/) to see how to load balance between multiple nodes. + +## Web UI + +You can access the simple HTML frontend of Træfik. + +![Web UI Providers](docs/img/web.frontend.png) +![Web UI Health](docs/img/traefik-health.png) + +## Documentation + +You can find the complete documentation at [https://docs.traefik.io](https://docs.traefik.io). +A collection of contributions around Træfik can be found at [https://awesome.traefik.io](https://awesome.traefik.io). + +## Support + +To get community support, you can: +- join the Træfik community Slack channel: [![Join the chat at https://traefik.herokuapp.com](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://traefik.herokuapp.com) +- use [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag) + +If you need commercial support, please contact [Containo.us](https://containo.us) by mail: . + +## Download + +- Grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page and run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): + +```shell +./traefik --configFile=traefik.toml +``` + +- Or use the official tiny Docker image and run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): + +```shell +docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik +``` + +- Or get the sources: + +```shell +git clone https://github.com/containous/traefik +``` + +## Introductory Videos Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at [GopherCon 2017](https://gophercon.com/). You will learn Træfik basics in less than 10 minutes. @@ -101,81 +143,26 @@ You will learn fundamental Træfik features and see some demos with Kubernetes. [![Traefik ContainerCamp UK](https://img.youtube.com/vi/aFtpIShV60I/0.jpg)](https://www.youtube.com/watch?v=aFtpIShV60I) - -## Web UI - -You can access the simple HTML frontend of Træfik. - -![Web UI Providers](docs/img/web.frontend.png) -![Web UI Health](docs/img/traefik-health.png) - - -## Test it - -- The simple way: 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 --configFile=traefik.toml -``` - -- Use the tiny Docker image and just run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): - -```shell -docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik -``` - -- From sources: - -```shell -git clone https://github.com/containous/traefik -``` - - -## Documentation - -You can find the complete documentation at [https://docs.traefik.io](https://docs.traefik.io). -A collection of contributions around Træfik can be found at [https://awesome.traefik.io](https://awesome.traefik.io). - - -## Support - -To get basic support, you can: -- join the Træfik community Slack channel: [![Join the chat at https://traefik.herokuapp.com](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://traefik.herokuapp.com) -- use [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag) - -If you prefer commercial support, please contact [containo.us](https://containo.us) by mail: . - - -## Release cycle - -- Release: We try to release a new version every 2 months - - i.e.: 1.3.0, 1.4.0, 1.5.0 -- Release candidate: we do RC (1.**x**.0-rc**y**) before the final release (1.**x**.0) - - i.e.: 1.1.0-rc1 -> 1.1.0-rc2 -> 1.1.0-rc3 -> 1.1.0-rc4 -> 1.1.0 -- Bug-fixes: For each version we release bug fixes - - i.e.: 1.1.1, 1.1.2, 1.1.3 - - those versions contain only bug-fixes - - no additional features are delivered in those versions -- Each version is supported until the next one is released - - i.e.: 1.1.x will be supported until 1.2.0 is out -- We use [Semantic Versioning](http://semver.org/) - - -## Contributing - -Please refer to [contributing documentation](CONTRIBUTING.md). - - -### Code of Conduct - -Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). -By participating in this project you agree to abide by its terms. - - ## Maintainers [Information about process and maintainers](MAINTAINER.md) +## Contributing + +If you'd like to contribute to the project, refer to the [contributing documentation](CONTRIBUTING.md). + +Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). +By participating in this project, you agree to abide by its terms. + +## Release Cycle + +- We release a new version (e.g. 1.1.0, 1.2.0, 1.3.0) every other month. +- Release Candidates are available before the release (e.g. 1.1.0-rc1, 1.1.0-rc2, 1.1.0-rc3, 1.1.0-rc4, before 1.1.0) +- Bug-fixes (e.g. 1.1.1, 1.1.2, 1.2.1, 1.2.3) are released as needed (no additional features are delivered in those versions, bug-fixes only) + +Each version is supported until the next one is released (e.g. 1.1.x will be supported until 1.2.0 is out) + +We use [Semantic Versioning](http://semver.org/) ## Plumbing @@ -184,11 +171,11 @@ By participating in this project you agree to abide by its terms. - [Negroni](https://github.com/urfave/negroni): web middlewares made simple - [Lego](https://github.com/xenolf/lego): the best [Let's Encrypt](https://letsencrypt.org) library in go - ## Credits Kudos to [Peka](http://peka.byethost11.com/photoblog/) for his awesome work on the logo ![logo](docs/img/traefik.icon.png). -Traefik's logo licensed under the Creative Commons 3.0 Attributions license. + +Traefik's logo is licensed under the Creative Commons 3.0 Attributions license. Traefik's logo was inspired by the gopher stickers made by Takuya Ueda (https://twitter.com/tenntenn). -The original Go gopher was designed by Renee French (http://reneefrench.blogspot.com/). +The original Go gopher was designed by Renee French (http://reneefrench.blogspot.com/). \ No newline at end of file diff --git a/docs/configuration/backends/docker.md b/docs/configuration/backends/docker.md index f587078e8..a56de8341 100644 --- a/docs/configuration/backends/docker.md +++ b/docs/configuration/backends/docker.md @@ -145,10 +145,10 @@ To enable constraints see [backend-specific constraints section](/configuration/ ## Labels: overriding default behaviour -!!! note - If you use a compose file, labels should be defined in the `deploy` part of your service. +#### Using Docker with Swarm Mode - This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/#labels-1)). +If you use a compose file with the Swarm mode, labels should be defined in the `deploy` part of your service. +This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/#labels-1)). ```yaml version: "3" @@ -159,52 +159,69 @@ services: traefik.docker.network: traefik ``` +#### Using Docker Compose + +If you are intending to use only Docker Compose commands (e.g. `docker-compose up --scale whoami=2 -d`), labels should be under your service, otherwise they will be ignored. + +```yaml +version: "3" +services: + whoami: + labels: + traefik.docker.network: traefik +``` + ### On Containers -Labels can be used on containers to override default behaviour. +Labels can be used on containers to override default behavior. -| Label | Description | -|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `traefik.docker.network` | Set the docker network to use for connections to this container.
If a container is linked to several networks, be sure to set the proper network name (you can check with `docker inspect `) otherwise it will randomly pick one (depending on how docker is returning them).
For instance when deploying docker `stack` from compose files, the compose defined networks will be prefixed with the `stack` name. | -| `traefik.enable=false` | Disable this container in Træfik | -| `traefik.port=80` | Register this port. Useful when the container exposes multiples ports. | -| `traefik.protocol=https` | Override the default `http` protocol | -| `traefik.weight=10` | Assign this weight to the container | -| `traefik.backend=foo` | Give the name `foo` to the generated backend for this container. | -| `traefik.backend.buffering.maxRequestBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | -| `traefik.backend.buffering.maxResponseBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | -| `traefik.backend.buffering.memRequestBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | -| `traefik.backend.buffering.memResponseBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | -| `traefik.backend.buffering.retryExpression=EXPR` | See [buffering](/configuration/commons/#buffering) section. | -| `traefik.backend.circuitbreaker.expression=EXPR` | Create a [circuit breaker](/basics/#backends) to be used against the backend | -| `traefik.backend.healthcheck.path=/health` | Enable health check for the backend, hitting the container at `path`. | -| `traefik.backend.healthcheck.port=8080` | Allow to use a different port for the health check. | -| `traefik.backend.healthcheck.interval=1s` | Define the health check interval. | -| `traefik.backend.loadbalancer.method=drr` | Override the default `wrr` load balancer algorithm | -| `traefik.backend.loadbalancer.stickiness=true` | Enable backend sticky sessions | -| `traefik.backend.loadbalancer.stickiness.cookieName=NAME` | Manually set the cookie name for sticky sessions | -| `traefik.backend.loadbalancer.sticky=true` | Enable backend sticky sessions (DEPRECATED) | -| `traefik.backend.loadbalancer.swarm=true` | Use Swarm's inbuilt load balancer (only relevant under Swarm Mode). | -| `traefik.backend.maxconn.amount=10` | Set a maximum number of connections to the backend.
Must be used in conjunction with the below label to take effect. | -| `traefik.backend.maxconn.extractorfunc=client.ip` | Set the function to be used against the request to determine what to limit maximum connections to the backend by.
Must be used in conjunction with the above label to take effect. | -| `traefik.frontend.auth.basic=EXPR` | Sets basic authentication for that frontend in CSV format: `User:Hash,User:Hash` | -| `traefik.frontend.entryPoints=http,https` | Assign this frontend to entry points `http` and `https`.
Overrides `defaultEntryPoints` | -| `traefik.frontend.errors..backend=NAME` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | -| `traefik.frontend.errors..query=PATH` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | -| `traefik.frontend.errors..status=RANGE` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | -| `traefik.frontend.passHostHeader=true` | Forward client `Host` header to the backend. | -| `traefik.frontend.passTLSCert=true` | Forward TLS Client certificates to the backend. | -| `traefik.frontend.priority=10` | Override default frontend priority | -| `traefik.frontend.rateLimit.extractorFunc=EXP` | See [rate limiting](/configuration/commons/#rate-limiting) section. | -| `traefik.frontend.rateLimit.rateSet..period=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | -| `traefik.frontend.rateLimit.rateSet..average=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | -| `traefik.frontend.rateLimit.rateSet..burst=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | -| `traefik.frontend.redirect.entryPoint=https` | Enables Redirect to another entryPoint for that frontend (e.g. HTTPS) | -| `traefik.frontend.redirect.regex=^http://localhost/(.*)` | Redirect to another URL for that frontend.
Must be set with `traefik.frontend.redirect.replacement`. | -| `traefik.frontend.redirect.replacement=http://mydomain/$1` | Redirect to another URL for that frontend.
Must be set with `traefik.frontend.redirect.regex`. | -| `traefik.frontend.redirect.permanent=true` | Return 301 instead of 302. | -| `traefik.frontend.rule=EXPR` | Override the default frontend rule. Default: `Host:{containerName}.{domain}` or `Host:{service}.{project_name}.{domain}` if you are using `docker-compose`. | -| `traefik.frontend.whitelistSourceRange=RANGE` | List of IP-Ranges which are allowed to access.
An unset or empty list allows all Source-IPs to access. If one of the Net-Specifications are invalid, the whole list is invalid and allows all Source-IPs to access. | +| Label | Description | +|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `traefik.docker.network` | Set the docker network to use for connections to this container. [1] | +| `traefik.enable=false` | Disable this container in Træfik | +| `traefik.port=80` | Register this port. Useful when the container exposes multiples ports. | +| `traefik.protocol=https` | Override the default `http` protocol | +| `traefik.weight=10` | Assign this weight to the container | +| `traefik.backend=foo` | Give the name `foo` to the generated backend for this container. | +| `traefik.backend.buffering.maxRequestBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | +| `traefik.backend.buffering.maxResponseBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | +| `traefik.backend.buffering.memRequestBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | +| `traefik.backend.buffering.memResponseBodyBytes=0` | See [buffering](/configuration/commons/#buffering) section. | +| `traefik.backend.buffering.retryExpression=EXPR` | See [buffering](/configuration/commons/#buffering) section. | +| `traefik.backend.circuitbreaker.expression=EXPR` | Create a [circuit breaker](/basics/#backends) to be used against the backend | +| `traefik.backend.healthcheck.path=/health` | Enable health check for the backend, hitting the container at `path`. | +| `traefik.backend.healthcheck.port=8080` | Allow to use a different port for the health check. | +| `traefik.backend.healthcheck.interval=1s` | Define the health check interval. | +| `traefik.backend.loadbalancer.method=drr` | Override the default `wrr` load balancer algorithm | +| `traefik.backend.loadbalancer.stickiness=true` | Enable backend sticky sessions | +| `traefik.backend.loadbalancer.stickiness.cookieName=NAME` | Manually set the cookie name for sticky sessions | +| `traefik.backend.loadbalancer.sticky=true` | Enable backend sticky sessions (DEPRECATED) | +| `traefik.backend.loadbalancer.swarm=true` | Use Swarm's inbuilt load balancer (only relevant under Swarm Mode). | +| `traefik.backend.maxconn.amount=10` | Set a maximum number of connections to the backend.
Must be used in conjunction with the below label to take effect. | +| `traefik.backend.maxconn.extractorfunc=client.ip` | Set the function to be used against the request to determine what to limit maximum connections to the backend by.
Must be used in conjunction with the above label to take effect. | +| `traefik.frontend.auth.basic=EXPR` | Sets basic authentication for that frontend in CSV format: `User:Hash,User:Hash` | +| `traefik.frontend.entryPoints=http,https` | Assign this frontend to entry points `http` and `https`.
Overrides `defaultEntryPoints` | +| `traefik.frontend.errors..backend=NAME` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | +| `traefik.frontend.errors..query=PATH` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | +| `traefik.frontend.errors..status=RANGE` | See [custom error pages](/configuration/commons/#custom-error-pages) section. | +| `traefik.frontend.passHostHeader=true` | Forward client `Host` header to the backend. | +| `traefik.frontend.passTLSCert=true` | Forward TLS Client certificates to the backend. | +| `traefik.frontend.priority=10` | Override default frontend priority | +| `traefik.frontend.rateLimit.extractorFunc=EXP` | See [rate limiting](/configuration/commons/#rate-limiting) section. | +| `traefik.frontend.rateLimit.rateSet..period=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | +| `traefik.frontend.rateLimit.rateSet..average=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | +| `traefik.frontend.rateLimit.rateSet..burst=6` | See [rate limiting](/configuration/commons/#rate-limiting) section. | +| `traefik.frontend.redirect.entryPoint=https` | Enables Redirect to another entryPoint for that frontend (e.g. HTTPS) | +| `traefik.frontend.redirect.regex=^http://localhost/(.*)` | Redirect to another URL for that frontend.
Must be set with `traefik.frontend.redirect.replacement`. | +| `traefik.frontend.redirect.replacement=http://mydomain/$1` | Redirect to another URL for that frontend.
Must be set with `traefik.frontend.redirect.regex`. | +| `traefik.frontend.redirect.permanent=true` | Return 301 instead of 302. | +| `traefik.frontend.rule=EXPR` | Override the default frontend rule. Default: `Host:{containerName}.{domain}` or `Host:{service}.{project_name}.{domain}` if you are using `docker-compose`. | +| `traefik.frontend.whitelistSourceRange=RANGE` | List of IP-Ranges which are allowed to access.
An unset or empty list allows all Source-IPs to access. If one of the Net-Specifications are invalid, the whole list is invalid and allows all Source-IPs to access. | + +[1] `traefik.docker.network`: +If a container is linked to several networks, be sure to set the proper network name (you can check with `docker inspect `) otherwise it will randomly pick one (depending on how docker is returning them). +For instance when deploying docker `stack` from compose files, the compose defined networks will be prefixed with the `stack` name. +Or if your service references external network use it's name instead. #### Custom Headers diff --git a/docs/index.md b/docs/index.md index a00414e99..00d2c30d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,66 +10,165 @@ [![Twitter](https://img.shields.io/twitter/follow/traefikproxy.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefikproxy) -Træfik (pronounced like _traffic_) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. -It supports several backends ([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 a lot more) to manage its configuration automatically and dynamically. +Træfik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. +Træfik 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. +Telling Træfik where your orchestrator is could be the _only_ configuration step you need to do. ## Overview -Imagine that you have deployed a bunch of microservices on your infrastructure. You probably used a service registry (like etcd or consul) and/or an orchestrator (swarm, Mesos/Marathon) to manage all these services. -If you want your users to access some of your microservices from the Internet, you will have to use a reverse proxy and configure it using virtual hosts or prefix paths: +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. -- domain `api.domain.com` will point the microservice `api` in your private network -- path `domain.com/web` will point the microservice `web` in your private network -- domain `backoffice.domain.com` will point the microservices `backoffice` in your private network, load-balancing between your multiple instances +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. -Microservices are often deployed in dynamic environments where services are added, removed, killed, upgraded or scaled many times a day. +**This is when Træfik can help you!** -Traditional reverse-proxies are not natively dynamic. You can't change their configuration and hot-reload easily. +Træfik 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. -Here enters Træfik. +**Run Træfik and let it do the work for you!** +_(But if you'd rather configure some of your routes manually, Træfik supports that too!)_ ![Architecture](img/architecture.png) -Træfik can listen to your service registry/orchestrator API, and knows each time a microservice is added, removed, killed or upgraded, and can generate its configuration automatically. -Routes to your services will be created instantly. - -Run it and forget it! - ## Features -- [It's fast](/benchmarks) -- No dependency hell, single binary made with go -- [Tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -- Rest API -- Hot-reloading of configuration. No need to restart the process +- Continuously updates its configuration (No restarts!) +- Supports multiple load balancing algorithms +- Provides HTTPS to your microservices by leveraging [Let's Encrypt](https://letsencrypt.org) - Circuit breakers, retry -- Round Robin, rebalancer load-balancers -- Metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) -- Clean AngularJS Web UI +- High Availability with cluster mode (beta) +- See the magic through its clean web UI - Websocket, HTTP/2, GRPC ready -- Access Logs (JSON, CLF) -- [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS with renewal) -- High Availability with cluster mode +- Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) +- Keeps access logs (JSON, CLF) +- [Fast](/benchmarks) ... which is nice +- Exposes a Rest API +- Packaged as a single binary file (made with :heart: with go) and available as a [tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image ## Supported backends -- [Docker](https://www.docker.com/) / [Swarm mode](https://docs.docker.com/engine/swarm/) -- [Kubernetes](https://kubernetes.io) -- [Service Fabric](https://docs.microsoft.com/en-gb/azure/service-fabric/) -- [Mesos](https://github.com/apache/mesos) / [Marathon](https://mesosphere.github.io/marathon/) -- [Rancher](https://rancher.com) (API, Metadata) -- [Consul](https://www.consul.io/) / [Etcd](https://coreos.com/etcd/) / [Zookeeper](https://zookeeper.apache.org) / [BoltDB](https://github.com/boltdb/bolt) -- [Eureka](https://github.com/Netflix/eureka) -- [Amazon ECS](https://aws.amazon.com/ecs) -- [Amazon DynamoDB](https://aws.amazon.com/dynamodb) -- File -- Rest API +- [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) +- [Service Fabric](/configuration/backends/servicefabric/) +- [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/) +## The Træfik Quickstart (Using Docker) -## Quickstart +In this quickstart, we'll use [Docker compose](https://docs.docker.com/compose) to create our demo infrastructure. -You can have a quick look at Træfik in this [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. +To save some time, you can clone [Træfik'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. + +### 1 — Launch Træfik — Tell It to Listen to Docker + +Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Træfik image: + +```yaml +version: '3' + +services: + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik 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 +``` + +**That's it. Now you can launch Træfik!** + +Start your `reverse-proxy` with the following command: + +```shell +docker-compose up -d reverse-proxy +``` + +You can open a browser and go to [http://localhost:8080](http://localhost:8080) to see Træfik's dashboard (we'll go back there once we have launched a service in step 2). + +### 2 — Launch a Service — Træfik Detects It and Creates a Route for You + +Now that we have a Træfik 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. + +```yaml +# ... + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's 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: + +```shell +docker-compose up -d whoami +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik 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) + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +_Shows the following output:_ +```yaml +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: + +```shell +docker-compose up -d --scale whoami=2 +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new instance of the container. + +Finally, see that Træfik load-balances between the two instances of your services by running twice the following command: + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +The output will show alternatively one of the followings: + +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +```yaml +Hostname: 8458f154e1f1 +IP: 172.27.0.4 +# ... +``` + +### 4 — Enjoy Træfik's Magic + +Now that you have a basic understanding of how Træfik can automatically create the routes to your services and load balance them, it might be time to dive into [the documentation](https://docs.traefik.io/) and let Træfik work for you! Whatever your infrastructure is, there is probably [an available Træfik backend](https://docs.traefik.io/configuration/backends/available) that will do the job. + +Our recommendation would be to see for yourself how simple it is to enable HTTPS with [Træfik's let's encrypt integration](https://docs.traefik.io/user-guide/examples/#lets-encrypt-support) using the dedicated [user guide](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/). + +## Resources Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at [GopherCon 2017](https://gophercon.com). You will learn Træfik basics in less than 10 minutes. @@ -81,9 +180,9 @@ You will learn fundamental Træfik features and see some demos with Kubernetes. [![Traefik ContainerCamp UK](https://img.youtube.com/vi/aFtpIShV60I/0.jpg)](https://www.youtube.com/watch?v=aFtpIShV60I) -## Get it +## Downloads -### Binary +### 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): @@ -91,113 +190,10 @@ You can grab the latest binary from the [releases](https://github.com/containous ./traefik -c traefik.toml ``` -### Docker +### 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 -``` - -## Test it - -You can test Træfik easily using [Docker compose](https://docs.docker.com/compose), with this `docker-compose.yml` file in a folder named `traefik`: - -```yaml -version: '3' - -services: - proxy: - image: traefik - command: --api --docker --docker.domain=docker.localhost --logLevel=DEBUG - networks: - - webgateway - ports: - - "80:80" - - "8080:8080" - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - /dev/null:/traefik.toml - -networks: - webgateway: - driver: bridge -``` - -Start it from within the `traefik` folder: - -```shell -docker-compose up -d -``` - -In a browser, you may open [http://localhost:8080](http://localhost:8080) to access Træfik's dashboard and observe the following magic. - -Now, create a folder named `test` and create a `docker-compose.yml` in it with this content: - -```yaml -version: '3' - -services: - whoami: - image: emilevauge/whoami - networks: - - web - labels: - - "traefik.backend=whoami" - - "traefik.frontend.rule=Host:whoami.docker.localhost" - -networks: - web: - external: - name: traefik_webgateway -``` - -Then, start and scale it in the `test` folder: - -```shell -docker-compose up --scale whoami=2 -d -``` - -Finally, test load-balancing between the two services `test_whoami_1` and `test_whoami_2`: - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -```yaml -Hostname: ef194d07634a -IP: 127.0.0.1 -IP: ::1 -IP: 172.17.0.4 -IP: fe80::42:acff:fe11:4 -GET / HTTP/1.1 -Host: 172.17.0.4:80 -User-Agent: curl/7.35.0 -Accept: */* -Accept-Encoding: gzip -X-Forwarded-For: 172.17.0.1 -X-Forwarded-Host: 172.17.0.4:80 -X-Forwarded-Proto: http -X-Forwarded-Server: dbb60406010d -``` - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -```yaml -Hostname: 6c3c5df0c79a -IP: 127.0.0.1 -IP: ::1 -IP: 172.17.0.3 -IP: fe80::42:acff:fe11:3 -GET / HTTP/1.1 -Host: 172.17.0.3:80 -User-Agent: curl/7.35.0 -Accept: */* -Accept-Encoding: gzip -X-Forwarded-For: 172.17.0.1 -X-Forwarded-Host: 172.17.0.3:80 -X-Forwarded-Proto: http -X-Forwarded-Server: dbb60406010d -``` +``` \ No newline at end of file diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md new file mode 100644 index 000000000..7deb4faf6 --- /dev/null +++ b/examples/quickstart/README.md @@ -0,0 +1,106 @@ +## The Træfik Quickstart (Using Docker) + +In this quickstart, we'll use [Docker compose](https://docs.docker.com/compose) to create our demo infrastructure. + +To save some time, you can clone [Træfik'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. + +### 1 — Launch Træfik — Tell It to Listen to Docker + +Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Træfik image: + +```yaml +version: '3' + +services: + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik 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 +``` + +**That's it. Now you can launch Træfik!** + +Start your `reverse-proxy` with the following command: + +```shell +docker-compose up -d reverse-proxy +``` + +You can open a browser and go to [http://localhost:8080](http://localhost:8080) to see Træfik's dashboard (we'll go back there once we have launched a service in step 2). + +### 2 — Launch a Service — Træfik Detects It and Creates a Route for You + +Now that we have a Træfik 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. + +```yaml +# ... + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's 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: + +```shell +docker-compose up -d whoami +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik 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) + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +_Shows the following output:_ +```yaml +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: + +```shell +docker-compose up -d --scale whoami=2 +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new instance of the container. + +Finally, see that Træfik load-balances between the two instances of your services by running twice the following command: + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +The output will show alternatively one of the followings: + +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +```yaml +Hostname: 8458f154e1f1 +IP: 172.27.0.4 +# ... +``` + +### 4 — Enjoy Træfik's Magic + +Now that you have a basic understanding of how Træfik can automatically create the routes to your services and load balance them, it might be time to dive into [the documentation](https://docs.traefik.io/) and let Træfik work for you! Whatever your infrastructure is, there is probably [an available Træfik backend](https://docs.traefik.io/configuration/backends/available) that will do the job. + +Our recommendation would be to see for yourself how simple it is to enable HTTPS with [Træfik's let's encrypt integration](https://docs.traefik.io/user-guide/examples/#lets-encrypt-support) using the dedicated [user guide](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/). \ No newline at end of file diff --git a/examples/quickstart/docker-compose.yml b/examples/quickstart/docker-compose.yml new file mode 100644 index 000000000..f31f5d408 --- /dev/null +++ b/examples/quickstart/docker-compose.yml @@ -0,0 +1,18 @@ +version: '3' + +services: + #The reverse proxy service (Træfik) + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik 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 + + #A container that exposes a simple API + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's IP address + labels: + - "traefik.frontend.rule=Host:whoami.docker.localhost" \ No newline at end of file