Net-proxy/traefik

From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

Traefik provides a proxy that is container aware. This is a level 7 proxy, that is it operates in the application layer in the OSI model, that can only do connection termination. One needs a level 4 proxy, that is it operate in the transport layer in the OSI model, to do connection routing as required by SSL-SNI for example.

Traefik will configure a virtual host for each container in ones container cluster (Mesos/docker/kubernetes and other supported), allowing it to serve from each container. It will even go one further and issue SSL certificates for each service.

It may be run from within a container or upon the host. This article is concerned with the latter.

Installation

E-Builds for traefik are presently supplied by the frabjous overlay.

USE flags

Traefik is a go based project and does not seem to need any specific use flags.

Cannot load package information. Is the atom net-proxy/traefik correct?

Emerge

Traefik is readily emerged via the usual means once the overlay has been configured.

root #emerge --ask net-proxy/frabjous

Additional software

Traefik is run as a compliment to ones container manager (Docker/Mesos). One may configure it to be run as the web facing proxy if there are no host services or behind another proxy (Haproxy/NginX/Apache) should one be serving content from another web server(Nginx/Apache). Additionally Traefik supports analytics/monitoring which can be connected to packages like Prometheus.

Configuration

As traefik is quite modular it is easiest to copy the relevant pre-configured sections out of their documentation, stitching the parts together as necessary for ones own system.

Environment variables

Traefik does not have any environment variables that it looks out for, there is supposedly certain configurations that may make it use environment variables (Although the author can not recall the packages name at this time).

Files

Traefik has one main configuration file which controls it's operation.

  • /etc/traefik/traefik.toml - Global configuration file for traefik.

One may configure Traefik to use a further folder/file for different frontend/backend configurations.

  • /etc/traefik/conf.d/ - Path for additional routing configurations.

The following paths should be used for logging purposes.

  • var/log/traefik - Folder for traefik to provide logging information.
  • var/log/traefik/traefik.log - Traefik log for recording program, container and certification events .
  • var/log/traefik/access.log - Access log for recording web traffic through Traefik.

Service

(Provide instructions on starting/stopping and enabling/disabling the software's service. This is only really necessary if it if the software includes a daemon for certain tasks.)

Typically the service needs access to the docker socket, {Path|/var/run/docker.sock}, to generate configurations for the containers it proxies. Traefik should be really be started as root so that it can connect to the socket and then restrict it's own permissions to that of the Traefik user. The present init script starts the service as the {user|traefik} user which prevents it from seeing the socket. One may add Traefik to the docker group to enable this permission again.

user $gpasswd -a traefik docker

OpenRC

One one has configured Traefik to their satisfaction they may add the service to the default service

user $rc-update add traefik default

Subsequently start the service or restart the machine.

user $rc-service traefik start

Use the following command to remove it from active duty.

user $rc-update del traefik

runit

Note
If you have information about invoking Traefik under runit please edit this section accordingly

systemd

Note
If you have information about invoking Traefik under runit please edit this section accordingly

Usage

While one is configuring Traefik it is convenient to run it directly.

Invocation

Traefik may be run in debug mode directly, allowing one to watch it's responses to various requests. The following command will invoke Traefik directly and view it's debug information as it pours onto ones console.

user $traefik -d

One may use Template:Keys to terminate this process.

Troubleshooting

(Troubleshoot issues in this section. Separate issues by best describing the error with a new section name. Remove if no issues are known.)

Ignoring Frontend/backend configuration

Traefik is not told to explicitly watch it's own configuration file for frontend/backedn configuration(s). This is resolved by simply adding the file heading into the configuration.

404

If traefik is hosted behind a proxy and the proxy is not forwarding the Host header then traefik cannot know which container to serve and returns a 404. To fix this ensure that one has correctly configured the proxy protocol in both the frontend proxy and the Traefik service itself.

Removal

Removal of Traefik is as simple as unmerging the package, one may also wish to remove the overlay thereafter.

Unmerge

root #emerge --ask --depclean net-proxy/traefik

See also

  • Article_name - (Link to related Gentoo Wiki articles using bullet points for each link in this section; each link should be local to the Wiki. Use a dash to separate the link from a reason why the link was decided upon.)

External resources

  • (Link to external resources (outside the Wiki) using bullet points in this section. It is common for the information in this section to full sentences that are links.)

References

(Optional section. Remove this section if references are not used. This section is used to cite factual information. This information is found outside the Gentoo Wiki and used to back up truth claims. The actual references themselves still be littered throughout the main article.)