traefik-k8s

Traefik Ingress Operator for Kubernetes

  • Canonical Observability
Channel Revision Published Runs on
latest/stable 228 04 Mar 2025
Ubuntu 20.04
latest/candidate 232 04 Mar 2025
Ubuntu 20.04
latest/beta 234 04 Mar 2025
Ubuntu 20.04
latest/edge 234 25 Feb 2025
Ubuntu 20.04
1.0/stable 164 16 Feb 2024
Ubuntu 20.04
1.0/candidate 164 22 Nov 2023
Ubuntu 20.04
1.0/beta 164 22 Nov 2023
Ubuntu 20.04
1.0/edge 164 22 Nov 2023
Ubuntu 20.04
juju deploy traefik-k8s
Show information

Learn to deploy on juju >

Platform:

charms.traefik_k8s.v0.traefik_route

Interface Library for traefik_route.

This library wraps relation endpoints for traefik_route. The requirer of this relation is the traefik-route-k8s charm, or any charm capable of providing Traefik configuration files. The provider is the traefik-k8s charm, or another charm willing to consume Traefik configuration files.

Getting Started

To get started using the library, you just need to fetch the library using charmcraft.

cd some-charm
charmcraft fetch-lib charms.traefik_k8s.v0.traefik_route

To use the library from the provider side (Traefik):

provides:
    traefik_route:
        interface: traefik_route
        limit: 1

from charms.traefik_k8s.v0.traefik_route import TraefikRouteProvider

class TraefikCharm(CharmBase):
  def __init__(self, *args):
    # ...
    self.traefik_route = TraefikRouteProvider(self)

    self.framework.observe(
        self.traefik_route.on.ready, self._handle_traefik_route_ready
    )

    def _handle_traefik_route_ready(self, event):
        config: str = self.traefik_route.get_config(event.relation)  # yaml
        # use config to configure Traefik

To use the library from the requirer side (TraefikRoute):

requires:
    traefik-route:
        interface: traefik_route
        limit: 1
        optional: false

Example usage without raw flag (default behavior):

# ...
from charms.traefik_k8s.v0.traefik_route import TraefikRouteRequirer

class TraefikRouteCharm(CharmBase):
  def __init__(self, *args):
    # ...
    traefik_route = TraefikRouteRequirer(
        self, self.model.relations.get("traefik-route"),
        "traefik-route",
        raw=False  # Default: Traefik will append TLS configs
    )
    if traefik_route.is_ready():
        traefik_route.submit_to_traefik(
            config={'my': {'traefik': 'configuration'}}
        )

Example usage with raw flag enabled (full control over TLS configuration):

# ...
from charms.traefik_k8s.v0.traefik_route import TraefikRouteRequirer

class TraefikRouteCharm(CharmBase):
  def __init__(self, *args):
    # ...
    traefik_route = TraefikRouteRequirer(
        self, self.model.relations.get("traefik-route"),
        "traefik-route",
        raw=True  # Traefik will not modify TLS settings on non HTTP routes
    )
    if self.traefik_route.is_ready():
        self.traefik_route.submit_to_traefik(
            config={
                'tcp': {
                    'routers': {
                        'secure-route': {
                            'rule': 'Host(`secure.example.com`)',
                            'service': 'my-service',
                            'tls': {'certResolver': 'myresolver'}
                        }
                    }
                }
            }
        )

Index

class TraefikRouteException

Description

Base class for exceptions raised by TraefikRoute. None

class UnauthorizedError

Description

Raised when the unit needs leadership to perform some action. None

class TraefikRouteProviderReadyEvent

Description

Event emitted when Traefik is ready to provide ingress for a routed unit. None

class TraefikRouteProviderDataRemovedEvent

Description

Event emitted when a routed ingress relation is removed. None

class TraefikRouteRequirerReadyEvent

Description

Event emitted when a unit requesting ingress has provided all data Traefik needs. None

class TraefikRouteRequirerEvents

Description

Container for TraefikRouteRequirer events. None

class TraefikRouteProviderEvents

Description

Container for TraefikRouteProvider events. None

class TraefikRouteProvider

Implementation of the provider of traefik_route.

Description

This will presumably be owned by a Traefik charm. The main idea is that Traefik will observe the ready event and, upon receiving it, will fetch the config from the TraefikRoute's application databag, apply it, and update its own app databag to let Route know that the ingress is there. The TraefikRouteProvider provides api to do this easily.

Methods

TraefikRouteProvider. __init__( self , charm: CharmBase , relation_name: str , external_host: str )

Constructor for TraefikRouteProvider.

Arguments

charm

The charm that is instantiating the instance.

relation_name

The name of the relation relation_name to bind to (defaults to "traefik-route").

external_host

The external host.

scheme

The scheme.

TraefikRouteProvider. external_host( self )

Description

Return the external host set by Traefik, if any. None

TraefikRouteProvider. scheme( self )

Description

Return the scheme set by Traefik, if any. None

TraefikRouteProvider. relations( self )

Description

The list of Relation instances associated with this endpoint. None

TraefikRouteProvider. update_traefik_address( self )

Description

Ensure that requirers know the external host for Traefik. None

TraefikRouteProvider. is_ready( self , relation: Relation )

Whether TraefikRoute is ready on this relation.

Description

Returns True when the remote app shared the config; False otherwise.

TraefikRouteProvider. get_config( self , relation: Relation )

Description

Renamed to get_dynamic_config. None

TraefikRouteProvider. get_dynamic_config( self , relation: Relation )

Description

Retrieve the dynamic config published by the remote application. None

TraefikRouteProvider. is_raw_enabled( self , relation: Relation )

Description

Check if the raw config mode is enabled by the remote application. None

TraefikRouteProvider. get_static_config( self , relation: Relation )

Description

Retrieve the static config published by the remote application. None

class TraefikRouteRequirer

Handles the requirer side of the traefik-route interface.

Description

This class provides an API for publishing dynamic and static configurations to the Traefik charm through the traefik-route relation. It does not perform validation on the provided configurations, assuming that Traefik will handle valid YAML-encoded data.

The application databag follows the structure:

{
    "config": "<Traefik dynamic config YAML>",
    "static": "<Traefik static config YAML>",  # Optional, requires Traefik restart
    "raw": "<bool>"  # Determines if Traefik should append TLS config for non HTTP routes
}

Methods

TraefikRouteRequirer. __init__( self , charm: CharmBase , relation: Relation , relation_name: str , raw )

TraefikRouteRequirer. external_host( self )

Description

Return the external host set by Traefik, if any. None

TraefikRouteRequirer. scheme( self )

Description

Return the scheme set by Traefik, if any. None

TraefikRouteRequirer. is_ready( self )

Description

Is the TraefikRouteRequirer ready to submit data to Traefik? None

TraefikRouteRequirer. submit_to_traefik( self , config: dict , static )

Submit an ingress configuration to Traefik.

Description

This method publishes dynamic and static configuration data to the traefik-route relation, allowing Traefik to pick up and apply the settings.

  • Dynamic config (config): Defines routing rules for Traefik.
  • Static config (static): Requires a Traefik restart to take effect.