Traefik Ingress Operator for Kubernetes

  • By Canonical Observability
Channel Revision Published Runs on
latest/stable 194 28 Jun 2024
Ubuntu 20.04
latest/candidate 199 28 Jun 2024
Ubuntu 20.04
latest/beta 199 21 Jun 2024
Ubuntu 20.04
latest/edge 203 Yesterday
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

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")

class IngressUrl

Description

Ingress url schema. None

class IngressProviderAppData

Description

Ingress application databag schema. None

class ProviderSchema

Description

Provider 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); relation must be of interface type ingress and have "limit: 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, binding address from juju network API will be used.

strip_prefix

configure Traefik to strip the path prefix.

redirect_https

redirect incoming requests to HTTPS.

scheme

callable returning the scheme to use when constructing the ingress url. Or a string, if the scheme is known and stable at charm-init-time.

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.