traefik-k8s

Traefik Ingress Operator for Kubernetes

  • Canonical Observability
Channel Revision Published Runs on
latest/stable 234 Yesterday
Ubuntu 20.04
latest/candidate 236 Yesterday
Ubuntu 20.04
latest/beta 236 18 Mar 2025
Ubuntu 20.04
latest/edge 236 14 Mar 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.v2.ingress

Interface Library for ingress.

This library wraps relation endpoints using the ingress interface and provides a Python API for both requesting and providing per-application ingress, with load-balancing occurring across all units.

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.v2.ingress

In the metadata.yaml of the charm, add the following:

requires:
    ingress:
        interface: ingress
        limit: 1

Then, to initialise the library:

from charms.traefik_k8s.v2.ingress import (IngressPerAppRequirer,
  IngressPerAppReadyEvent, IngressPerAppRevokedEvent)

class SomeCharm(CharmBase):
  def __init__(self, *args):
    # ...
    self.ingress = IngressPerAppRequirer(self, port=80)
    # The following event is triggered when the ingress URL to be used
    # by this deployment of the `SomeCharm` is ready (or changes).
    self.framework.observe(
        self.ingress.on.ready, self._on_ingress_ready
    )
    self.framework.observe(
        self.ingress.on.revoked, self._on_ingress_revoked
    )

    def _on_ingress_ready(self, event: IngressPerAppReadyEvent):
        logger.info("This app's ingress URL: %s", event.url)

    def _on_ingress_revoked(self, event: IngressPerAppRevokedEvent):
        logger.info("This app no longer has ingress")

Index

class IngressUrl

Description

Ingress url schema. None

class IngressProviderAppData

Description

Ingress application databag schema. None

class ProviderSchema

Description

Provider schema for Ingress. None

class IngressHealthCheck

Description

HealthCheck schema for Ingress. None

class IngressRequirerAppData

Description

Ingress requirer application databag model. None

Methods

IngressRequirerAppData. validate_scheme( cls , scheme )

Description

Validate scheme arg. None

IngressRequirerAppData. validate_port( cls , port )

Description

Validate port. None

class IngressRequirerUnitData

Description

Ingress requirer unit databag model. None

Methods

IngressRequirerUnitData. validate_host( cls , host )

Description

Validate host. None

IngressRequirerUnitData. validate_ip( cls , ip )

Description

Validate ip. None

class RequirerSchema

Description

Requirer schema for Ingress. None

class IngressError

Description

Base class for custom errors raised by this library. None

class NotReadyError

Description

Raised when a relation is not ready. None

class DataValidationError

Description

Raised when data validation fails on IPU relation data. None

class IngressPerAppDataProvidedEvent

Description

Event representing that ingress data has been provided for an app. None

class IngressPerAppDataRemovedEvent

Description

Event representing that ingress data has been removed for an app. None

class IngressPerAppProviderEvents

Description

Container for IPA Provider events. None

class IngressRequirerData

Description

Data exposed by the ingress requirer to the provider. None

class IngressPerAppProvider

Description

Implementation of the provider of ingress. None

Methods

IngressPerAppProvider. __init__( self , charm: CharmBase , relation_name: str )

Constructor for IngressPerAppProvider.

Arguments

charm

The charm that is instantiating the instance.

relation_name

The name of the relation endpoint to bind to (defaults to "ingress").

IngressPerAppProvider. wipe_ingress_data( self , relation: Relation )

Description

Clear ingress data from relation. None

IngressPerAppProvider. get_data( self , relation: Relation )

Description

Fetch the remote (requirer) app and units' databags. None

IngressPerAppProvider. is_ready( self , relation )

Description

The Provider is ready if the requirer has sent valid data. None

IngressPerAppProvider. publish_url( self , relation: Relation , url: str )

Description

Publish to the app databag the ingress url. None

IngressPerAppProvider. proxied_endpoints( self )

Returns the ingress settings provided to applications by this IngressPerAppProvider.

Description

For example, when this IngressPerAppProvider has provided the http://foo.bar/my-model.my-app URL to the my-app application, the returned dictionary will be:

{
    "my-app": {
        "url": "http://foo.bar/my-model.my-app"
    }
}

class IngressPerAppReadyEvent

Description

Event representing that ingress for an app is ready. None

class IngressPerAppRevokedEvent

Description

Event representing that ingress for an app has been revoked. None

class IngressPerAppRequirerEvents

Description

Container for IPA Requirer events. None

class IngressPerAppRequirer

Description

Implementation of the requirer of the ingress relation. None

Methods

IngressPerAppRequirer. __init__( self , charm: CharmBase , relation_name: str )

Constructor for IngressRequirer.

Arguments

charm

The charm that is instantiating the library.

relation_name

The name of the relation endpoint to bind to (defaults to "ingress"); the relation must be of interface type "ingress" and have a limit of 1.

host

Hostname to be used by the ingress provider to address the requiring application; if unspecified, the default Kubernetes service name will be used.

ip

Alternative addressing method other than host to be used by the ingress provider; if unspecified, the binding address from the Juju network API will be used.

healthcheck_params

Optional dictionary containing health check configuration parameters conforming to the IngressHealthCheck schema. The dictionary must include: - "path" (str): The health check endpoint path (required). It may also include: - "scheme" (Optional[str]): Replaces the server URL scheme for the health check endpoint. - "hostname" (Optional[str]): Hostname to be set in the health check request. - "port" (Optional[int]): Replaces the server URL port for the health check endpoint. - "interval" (str): Frequency of the health check calls (defaults to "30s" if omitted). - "timeout" (str): Maximum duration for a health check request (defaults to "5s" if omitted). If provided, "path" is required while "interval" and "timeout" will use Traefik's defaults when not specified.

strip_prefix

Configure Traefik to strip the path prefix.

redirect_https

Redirect incoming requests to HTTPS.

scheme

Either a callable that returns the scheme to use when constructing the ingress URL, or a string if the scheme is known and stable at charm initialization.

Description

The request args can be used to specify the ingress properties when the instance is created. If any are set, at least port is required, and they will be sent to the ingress provider as soon as it is available. All request args must be given as keyword args.

IngressPerAppRequirer. is_ready( self )

Description

The Requirer is ready if the Provider has sent valid data. None

IngressPerAppRequirer. provide_ingress_requirements( self )

Publishes the data that Traefik needs to provide ingress.

Arguments

scheme

Scheme to be used; if unspecified, use the one used by init.

host

Hostname to be used by the ingress provider to address the requirer unit; if unspecified, FQDN will be used instead

ip

Alternative addressing method other than host to be used by the ingress provider. if unspecified, binding address from juju network API will be used.

port

the port of the service (required)

IngressPerAppRequirer. relation( self )

Description

The established Relation instance, or None. None

IngressPerAppRequirer. url( self )

The full ingress URL to reach the current unit.

Description

Returns None if the URL isn't available yet.