This project automates the process of connecting the Traefik reverse proxy to Docker container networks dynamically. It listens for Docker events and manages Traefik's network connections to ensure it can reverse proxy for containers labeled for Traefik management.
This is useful if you have, for example, one traefik proxy which handle incoming requests for multiple docker compose services. It will only to the needed networks (ie the one whith traefik labels) without the need of a common traefik network for all services, which break the isolation principal.
- π Automatic Network Connection: Automatically connects Traefik to the networks of newly created containers that are labeled for Traefik. Ability to indicate which networks to connect to.
- π Intelligent Network Disconnection: Disconnects Traefik from networks of containers that are no longer running, ensuring a clean and efficient network setup.
- βοΈ Dynamic Configuration: Utilizes a YAML configuration file, CLI arguments and/or environment variables for easy setup and adjustments without needing to alter the source code.
- π TLS Support: Secure your Docker API communication by specifying TLS configuration details.
- π³ Run in cohtainer: Run this tool directly as a container to easy integration in your project.
- Docker
If you want to run it outside containers, make sure you have the following installed:
- Python 3.6+
- See
requirements.txtfor details.
Start the container :
docker run -d \
--name traefik_network_connector \
-v $PWD/config.yaml:/usr/src/app/config.yaml \
-v /var/run/docker.sock:/var/run/docker.sock \
obeoneorg/traefik_network_connector:latestAnd it's ok !
For more details about the configuration options, refer to the Configuration section.
Modify config.yaml to adjust the Traefik container name, the label to monitor, and other settings. Key configuration options include:
traefik.containerName: Name of the Traefik container in Docker.logLevel: Adjust the verbosity of the script's output.traefik.monitoredLabel: Docker label that triggers network connection actions. (DEPRECATED ! Directly usetraefik.docker.networkinstead in Traefik 2.0+)
β οΈ Take care ! @ If you usetraefik.monitoredLabel, you just have to give the network name in your compose file. But if you usetraefik.docker.network, you need to prefix the network name (for the example, let's saymynetwork) with your deployment name (for example, you rundocker compose upin a directory namedfoo, your network name will befoo_mynetwork). I don't understand why me, a single developer without special knowledge about docker, I was able to detect the compose name, but not Traefik... So you can't use a same compose for multiple deployment, it's kind of ridiculous, but I didn't find an elegant solution... (Il you have an idea, contact me !)
For a detailed explanation of all configuration options, refer to the comments within config.yaml.
To override the default configuration settings, use the command line arguments using the --key=value format. The key is a YAML config path and is used to override the corresponding value in the configuration. The keys must be all lowercase.
For example, to override the log level, use the --loglevel=INFO argument. For the docker host, use the --docker.host argument. For the Traefik container name use the --traefik.containername argument.
List of available command line arguments can be found using --help, and explaination in the config.yaml file.
To override the default configuration settings, you can also use the environment variables (as for command line arguments above, key is the YAML path but using _ instead of .). For example, to override the docker host, use the DOCKER_HOST environment variable.
To get started with the Traefik Network Connector, follow these steps:
-
Clone the repository:
git clone https://github.com/obeone/traefik_network_connector.git
-
Navigate to the cloned directory:
cd traefik_network_connector -
Install the required dependencies:
pip install -r requirements.txt
To use the Traefik Automatic Docker Network Connector, follow these steps:
-
Ensure Docker is running and you have the necessary permissions to interact with Docker's API.
-
Configure settings the way you like.
-
Run the script:
python main.py --config=<path_to_your_config.yaml>
If the
--configargument is omitted, the script defaults to usingconfig.yamlin the current directory.
To manage the Traefik Automatic Docker Network Connector as a service using systemd, follow these steps:
- Place the
traefik_network_connector.servicefile in/etc/systemd/system/. - Reload the systemd daemon:
sudo systemctl daemon-reload. - Start the service:
sudo systemctl start traefik_network_connector. - Enable the service at boot:
sudo systemctl enable traefik_network_connector. - Check the service status:
sudo systemctl status traefik_network_connector.
For increased security a Docker Socket proxy like linuxserver/socket-proxy can be used.
Essential configuration using Docker Compose:
services:
traefik-network-connector:
image: obeoneorg/traefik_network_connector:...
depends_on:
traefik-network-connector-docker-proxy:
condition: service_healthy
environment:
DOCKER_HOST: tcp://traefik-network-connector-docker-proxy:2375
networks:
- traefik-network-connector-docker-proxy
traefik-network-connector-docker-proxy:
environment:
CONTAINERS: 1
NETWORKS: 1
POST: 1
networks:
- traefik-network-connector-docker-proxy
networks:
traefik-network-connector-docker-proxy:
name: traefik-network-connector-docker-proxy
internal: trueThe Traefik Automatic Docker Network Connector needs read access to the containers (CONTAINERS: 1)
and networks (NETWORKS: 1) API as well as write permissions (POST: 1). In case the Docker socket
proxy exposes the Docker API via TCP, the Docker host must be configured accordingly.
- Monitoring Docker Events: Listens for creation and destruction events of containers and manages network connections accordingly.
- Connecting Traefik: When a container with the specified label is created, it connects Traefik to its network if not already connected. If a config specified label is present (default is
autoproxy.networks) only these networks will be connected to. - Disconnecting Traefik: If a container is destroyed, it checks if Traefik should be disconnected from its network, based on other containers' usage of the network.
To ensure secure communication with the Docker server, configure the following TLS settings in config.yaml:
docker:
host: "tcp://<your_docker_host>:2376" # Replace with your Docker host and port
tls:
verify: "/path/to/ca.pem" # Path to CA certificate for TLS verification
cert: "/path/to/cert.pem" # Path to client certificate for TLS
key: "/path/to/key.pem" # Path to client key for TLSThis section addresses common issues and questions:
-
Q: How do I resolve Docker API communication errors?
- A: If you are using TCP connections, ensure your Docker daemon is configured to allow secure connections and that your
config.yaml(or CLI/Environment variable) TLS settings are correct.
- A: If you are using TCP connections, ensure your Docker daemon is configured to allow secure connections and that your
-
Q: What if Traefik is not connecting to a container's network?
- A: Verify that the container has the correct label to be monitored as specified in your config.yaml and that Traefik is running an its name is properly set in your configuration. Also, check the logs.
-
Q: How can I debug connection issues between Traefik and Docker containers?
- A: Increase the
logLeveltoDEBUGto get more detailed output from the script. This can provide insights into the connection process and where it might be failing.
- A: Increase the
-
Q: How do I override configuration settings?
- A: You can override settings using command line arguments as detailed in the Usage section. Each configuration in
config.yamlcan be overridden by an equivalent command line argument or environment variable, see Configuration Settings.
- A: You can override settings using command line arguments as detailed in the Usage section. Each configuration in
-
Q: What is the priority for configuration settings?
- A: Command line arguments have the highest priority, followed by environment variables, and then the default settings in
config.yaml.
- A: Command line arguments have the highest priority, followed by environment variables, and then the default settings in
-
Q: How can I debug issues with incorrect configuration values?
- A: Ensure that your command line arguments and environment variables are correctly formatted and match the expected patterns. Use the
--helpoption with the script to see available command line arguments.
- A: Ensure that your command line arguments and environment variables are correctly formatted and match the expected patterns. Use the
-
Q: How can I specify the networks Traefik should connect to?
- A: It was easy, but... Look at Configuration.
Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests. Before contributing, please read through existing issues and pull requests to ensure that your contribution is unique and beneficial.
For support or queries, please open an issue on this repository. We aim to respond as quickly as possible to all inquiries.
πΎ obeone
Primarily powered by my new brain, GPT-4o, with some crucial tweaks and oversight from my secondary brain.
Check out more of my work on GitHub.