gateway_metadata

Gateway metadata interface library.

This library provides the provider and requirer sides of the gateway-metadata relation interface for sharing Kubernetes Gateway API metadata (name, namespace, deployment name, service account) between gateway providers and consuming charms.

What is this library for?

Charms that wrap a Kubernetes Gateway API resource (e.g. istio-ingress-k8s) automatically spin up a Gateway resource which creates proxy pods and routes for traffic routing. In certain cases, charms using the gateway need to know specific information about the gateway itself, including the gateway name, gateway class, and other details. This information can be used to create custom resources that attach to the gateway.

The gateway-metadata interface provides an umbrella relation containing gateway information that requiring charms can use to attach custom resources to the gateway managed by the provider charm. While currently used by the istio-ingress-k8s charm, it is designed for any charm that wraps a Kubernetes Gateway API resource.

Provider usage:

from charmlibs.interfaces.gateway_metadata import GatewayMetadata, GatewayMetadataProvider

class MyGatewayCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.gateway_metadata = GatewayMetadataProvider(self)

    def _publish(self):
        self.gateway_metadata.publish_metadata(
            GatewayMetadata(
                namespace="istio-system",
                gateway_name="my-gateway",
                deployment_name="my-gateway",
                service_account="my-gateway",
            )
        )

Requirer usage:

from charmlibs.interfaces.gateway_metadata import GatewayMetadataRequirer

class MyConsumerCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.gateway_metadata = GatewayMetadataRequirer(self)

    def _read(self):
        if self.gateway_metadata.is_ready:
            metadata = self.gateway_metadata.get_metadata()
class GatewayMetadata(
*,
namespace: str,
gateway_name: str,
deployment_name: str,
service_account: str,
)

Bases: BaseModel

Gateway workload metadata.

namespace: str
gateway_name: str
deployment_name: str
service_account: str
class GatewayMetadataProvider(
charm: CharmBase,
relation_name: str = 'gateway-metadata',
)

Bases: Object

Provider side of the gateway-metadata interface.

The provider publishes metadata about the Gateway workload to related applications.

publish_metadata(
metadata: GatewayMetadata,
) → None

Publish gateway metadata to all related applications.

Parameters:

metadata – The GatewayMetadata to publish.

class GatewayMetadataRequirer(
charm: CharmBase,
relation_name: str = 'gateway-metadata',
)

Bases: Object

Requirer side of the gateway-metadata interface.

The requirer receives metadata about the Gateway workload from the provider.

property is_ready: bool

Check if gateway metadata is available.

Returns:

True if the provider has published metadata, False otherwise.

get_metadata() → GatewayMetadata | None

Retrieve the gateway metadata published by the provider.

Returns:

GatewayMetadata if available, None otherwise.