https://github.com/canonical/traefik-k8s-operator
This charmed operator automates the operational procedures of running Traefik, an open-source application proxy.
https://github.com/canonical/traefik-k8s-operator
charm platform-engineering product-kubernetes-ingress squad-emea
Last synced: 24 days ago
JSON representation
This charmed operator automates the operational procedures of running Traefik, an open-source application proxy.
- Host: GitHub
- URL: https://github.com/canonical/traefik-k8s-operator
- Owner: canonical
- License: apache-2.0
- Created: 2022-01-18T15:24:13.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-05T11:00:03.000Z (about 1 month ago)
- Last Synced: 2026-03-05T15:17:52.851Z (about 1 month ago)
- Topics: charm, platform-engineering, product-kubernetes-ingress, squad-emea
- Language: Python
- Homepage: https://charmhub.io/traefik-k8s
- Size: 26.1 MB
- Stars: 15
- Watchers: 4
- Forks: 43
- Open Issues: 71
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# Traefik Kubernetes Charmed Operator
[](https://charmhub.io/traefik-k8s)
[](https://github.com/canonical/traefik-k8s-operator/actions/workflows/release.yaml)
[](https://discourse.charmhub.io)
This [Juju](https://juju.is) charmed operator written with the [Operator Lifecycle Manager Framework](https://juju.is/docs/olm), powering _ingress controller-like_ capabilities on Kubernetes.
By _ingress controller-like_ capabilities, we mean that the Traefik Kubernetes charmed operator exposes Juju applications to the outside of a Kubernetes cluster, **without** relying on the [`ingress` resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) of Kubernetes.
Rather, Traefik is instructed to expose Juju applications by means of relations with them.
## Setup
These instructions assume you will run the charm on [`microk8s`](https://microk8s.io), and rely on a few plugins, specifically:
```sh
sudo snap install microk8s
microk8s enable storage dns
# The following line is required unless you plan to use the `external_hostname` configuration option
microk8s enable metallb 192.168.0.10-192.168.0.100 # You likely want change these IP ranges
```
## Usage
```sh
juju deploy ./traefik-k8s_ubuntu-20.04-amd64.charm traefik-ingress --trust --resource traefik-image=ghcr.io/canonical/traefik:2.10.4
```
## Configurations
* `external_hostname` allows you to specify a host for the URL that Traefik will assume is its externally-visible URL, and that will be used to generate the URLs passed to the proxied applications. Note that this has to be a 'bare' hostname, i.e. no `http` prefix and no `:port` suffix. Neither are configurable at the moment.
If `external_hostname` is unspecified, Traefik will use the ingress ip of its Kubernetes service, and the charm will go into `WaitingStatus` if it does not discover an ingress IP on its Kubernetes service.
The [Setup](#setup) section shows how to optionally set up `metallb` with MicroK8s, so that Traefik's Kubernetes service will receive an ingress IP.
* `routing_mode`: structured as an enumeration, that allows you to select how Traefik will generate routes:
* `path`: Traefik will use its externally-visible url and create a route for the requester that will be structure like:
```
http://:/--
```
For example, an ingress-per-unit provider with `http://foo` external URL, will provide to the unit `my-unit/2` in the `my-model` model the following URL:
```
http://foo/my-model-my-unit-2
```
* `subdomain`: Traefik will use its externally-visible url, based on `external_hostname` or, missing that, the ingress IP, and create a route for the requester that will be structure like:
```
http://--.:/
```
For example, an ingress-per-unit provider with `http://foo:8080` external URL, will provide to the unit `my-unit/2` in the `my-model` model the following URL:
```
http://my-model-my-unit-2.foo:8080
```
**IMPORTANT:** With the `subdomain` routing mode, incoming HTTP requests have the `Host` header set to match one of the routes.
Considering the example above, incoming requests are expected to have the following HTTP header:
```
Host: my-model-my-unit-2.foo
```
## Relations
### Providing ingress proxying
This charmed operator supports two types of proxying:
* `per-app`: This is the "classic" proxying logic of an ingress-controller, load-balancing incoming connections to the various units of the Juju application related via the `ingress` relation by routing over the latter's Kubernetes service.
* `per-unit`: Traefik will have routes to the single pods of the proxied Juju application related to it via the `ingress-per-unit` relation.
This type of routing, while somewhat unconventional in Kubernetes, is necessary for applications like Prometheus (where each remote-write endpoint needs to be routed to separately) and beneficial to databases, the clients of which can perform client-side load balancing
### Monitoring Traefik itself
The metrics endpoint exposed by Traefik can be scraped by Prometheus over the [`prometheus_scrape` relation interface](https://charmhub.io/prometheus-k8s/libraries/prometheus_scrape) with:
```sh
juju add-relation traefik-ingress:metrics-endpoint prometheus
```
## Documentation
Our documentation is stored in the `docs` directory.
It is based on the Canonical starter pack
and hosted on [Read the Docs](https://about.readthedocs.com/). In structuring,
the documentation employs the [Diátaxis](https://diataxis.fr/) approach.
You may open a pull request with your documentation changes, or you can
[file a bug](https://github.com/canonical/traefik-k8s-operator/issues) to provide constructive feedback or suggestions.
To run the documentation locally before submitting your changes:
```bash
cd docs
make run
```
GitHub runs automatic checks on the documentation
to verify spelling, validate links and style guide compliance.
You can (and should) run the same checks locally:
```bash
make spelling
make linkcheck
make vale
make lint-md
```
## Contributing
Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this charm following best practice guidelines, and [CONTRIBUTING.md](https://github.com/canonical/traefik-k8s-operator/blob/main/CONTRIBUTING.md) for developer guidance.