Traefik Ingress Operator for Kubernetes
- By Canonical Observability
| Channel | Revision | Published | Runs on |
|---|---|---|---|
| latest/stable | 194 | 01 Aug 2024 | |
| latest/candidate | 199 | 28 Jun 2024 | |
| latest/beta | 203 | 01 Aug 2024 | |
| latest/edge | 207 | 04 Sep 2024 | |
| 1.0/stable | 164 | 16 Feb 2024 | |
| 1.0/candidate | 164 | 22 Nov 2023 | |
| 1.0/beta | 164 | 22 Nov 2023 | |
| 1.0/edge | 164 | 22 Nov 2023 |
juju deploy traefik-k8s
Deploy Kubernetes operators easily with Juju, the Universal Operator Lifecycle Manager. Need a Kubernetes cluster? Install MicroK8s to create a full CNCF-certified Kubernetes system in under 60 seconds.
Platform:
charms.traefik_k8s.v1.ingress_per_unit
-
- Last updated 04 Mar 2024
- Revision Library version 1.19
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
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
the charm that is instantiating the library.
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").
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 to be used by the ingress provider to address the requirer unit.
mode to be used between "tcp" and "http".
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!).
remove prefixes from the URL path.
redirect incoming requests to HTTPS
callable returning the scheme to use when constructing the ingress url.
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
Scheme to be used; if unspecified, use the one used by init.
Hostname to be used by the ingress provider to address the requirer unit; if unspecified, FQDN will be used instead
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.