Traefik Ingress

  • By Canonical Observability
Channel Revision Published Runs on
latest/stable 110 31 Jan 2023
Ubuntu 20.04
latest/candidate 110 25 Jan 2023
Ubuntu 20.04
latest/beta 110 25 Jan 2023
Ubuntu 20.04
latest/edge 120 10 Mar 2023
Ubuntu 20.04
1.0/stable 110 31 Jan 2023
Ubuntu 20.04
1.0/candidate 110 25 Jan 2023
Ubuntu 20.04
1.0/beta 110 25 Jan 2023
Ubuntu 20.04
1.0/edge 110 25 Jan 2023
Ubuntu 20.04
juju deploy traefik-k8s
Show information

Platform:

charms.traefik_k8s.v1.ingress_per_unit

Interface Library for ingress_per_unit.

This library wraps relation endpoints using the ingress_per_unit interface and provides a Python API for both requesting and providing per-unit ingress.

Getting Started

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

charmcraft fetch-lib charms.traefik_k8s.v1.ingress_per_unit

Add the jsonschema dependency to the requirements.txt of your charm.

requires:
    ingress:
        interface: ingress_per_unit
        limit: 1

Then, to initialise the library:

from charms.traefik_k8s.v1.ingress_per_unit import (IngressPerUnitRequirer,
  IngressPerUnitReadyForUnitEvent, IngressPerUnitRevokedForUnitEvent)

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

    def _on_ingress_ready(self, event: IngressPerUnitReadyForUnitEvent):
        # event.url is the same as self.ingress_per_unit.url
        logger.info("This unit's ingress URL: %s", event.url)

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

If you wish to be notified also (or instead) when another unit's ingress changes (e.g. if you're the leader and you're doing things with your peers' ingress), you can pass listen_to = "all-units" | "both" to IngressPerUnitRequirer and observe self.ingress_per_unit.on.ready and self.ingress_per_unit.on.revoked.

Index

class DataValidationError

Description

Raised when data validation fails on IPU relation data. None

class RelationException

Base class for relation exceptions from this library.

Attributes

relation
The Relation which caused the exception.
entity
The Application or Unit which caused the exception.

Methods

RelationException. __init__( self , relation: Relation , entity )

class RelationDataMismatchError

Description

Data from different units do not match where they should. None

class RelationPermissionError

Description

Ingress is requested to do something for which it lacks permissions. None

Methods

RelationPermissionError. __init__( self , relation: Relation , entity , message: str )

class IngressDataReadyEvent

Event triggered when the requirer has provided valid ingress data.

Description

Also emitted when the data has changed. If you receive this, you should handle it as if the data being provided was new.

class IngressDataRemovedEvent

Event triggered when a requirer has wiped its ingress data.

Description

Also emitted when the requirer data has become incomplete or invalid. If you receive this, you should handle it as if the remote unit no longer wishes to receive ingress.

class IngressPerUnitProviderEvents

Description

Container for events for IngressPerUnit. None

class IngressPerUnitProvider

Description

Implementation of the provider of ingress_per_unit. None

Methods

IngressPerUnitProvider. is_ready( self , relation )

Checks whether the given relation is ready.

Description

Or any relation if not specified. A given relation is ready if SOME remote side has sent valid data.

IngressPerUnitProvider. validate( self , relation: Relation )

Checks whether the given relation is failed.

Description

Or any relation if not specified.

IngressPerUnitProvider. is_unit_ready( self , relation: Relation , unit: Unit )

Description

Report whether the given unit has shared data in its unit data bag. None

IngressPerUnitProvider. get_data( self , relation: Relation , unit: Unit )

Description

Fetch the data shared by the specified unit on the relation (Requirer side). None

IngressPerUnitProvider. publish_url( self , relation: Relation , unit_name: str , url: str )

Place the ingress url in the application data bag for the units on the requirer side.

Description

Assumes that this unit is leader.

IngressPerUnitProvider. wipe_ingress_data( self , relation )

Remove all published ingress data.

Description

Assumes that this unit is leader.

IngressPerUnitProvider. proxied_endpoints( self )

The ingress settings provided to units by this provider.

Description

For example, when this IngressPerUnitProvider has provided the `http://foo.bar/my-model.my-app-1` and `http://foo.bar/my-model.my-app-2` URLs to the two units of the my-app application, the returned dictionary will be: ``` { "my-app/1": { "url": "http://foo.bar/my-model.my-app-1" }, "my-app/2": { "url": "http://foo.bar/my-model.my-app-2" } } ```

class IngressPerUnitReadyEvent

Ingress is ready (or has changed) for some unit.

Description

Attrs: `unit_name`: name of the unit for which ingress has been provided/has changed. `url`: the (new) url for that unit.

class IngressPerUnitReadyForUnitEvent

Ingress is ready (or has changed) for this unit.

Description

Is only fired on the unit(s) for which ingress has been provided or has changed. Attrs: `url`: the (new) url for this unit.

class IngressPerUnitRevokedEvent

Ingress is revoked (or has changed) for some unit.

Description

Attrs: `unit_name`: the name of the unit whose ingress has been revoked. this could be "THIS" unit, or a peer.

class IngressPerUnitRevokedForUnitEvent

Ingress is revoked (or has changed) for this unit.

Description

Is only fired on the unit(s) for which ingress has changed.

class IngressPerUnitRequirerEvents

Description

Container for IUP events. None

class IngressPerUnitRequirer

Description

Implementation of the requirer of ingress_per_unit. None

Methods

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

Constructor for IngressPerUnitRequirer.

Arguments

`charm`
the charm that is instantiating the library.
`relation_name`
the name of the relation name to bind to (defaults to "ingress-per-unit"; relation must be of interface type "ingress_per_unit" and have "limit: 1")
`host`
Hostname to be used by the ingress provider to address the requirer unit; if unspecified, the FQDN of the unit will be used instead
`port`
port to be used by the ingress provider to address the requirer unit.
`listen_to`
Choose which events should be fired on this unit: "only-this-unit": this unit will only be notified when ingress is ready/revoked for this unit. "all-units": this unit will be notified when ingress is ready/revoked for any unit of this application, including itself. "all": this unit will receive both event types (which means it will be notified *twice* of changes to this unit's ingress!)

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.

IngressPerUnitRequirer. relation( self )

Description

The established Relation instance, or None if still unrelated. None

IngressPerUnitRequirer. is_ready( self )

Checks whether the given relation is ready.

Description

Or any relation if not specified. A given relation is ready if the remote side has sent valid data.

IngressPerUnitRequirer. provide_ingress_requirements( self )

Publishes the data that Traefik needs to provide ingress.

Arguments

host
Hostname to be used by the ingress provider to address the requirer unit; if unspecified, FQDN will be used instead
port
the port of the service (required)

IngressPerUnitRequirer. urls( self )

The full ingress URLs to reach every unit.

Description

May return an empty dict if the URLs aren't available yet.

IngressPerUnitRequirer. url( self )

The full ingress URL to reach the current unit.

Description

May return None if the URL isn't available yet.