istio-ingress-k8s

Istio Ingress

Channel Revision Published Runs on
1/stable 33 26 Jun 2025
Ubuntu 24.04
1/candidate 33 10 Jun 2025
Ubuntu 24.04
1/beta 33 10 Jun 2025
Ubuntu 24.04
1/edge 33 14 May 2025
Ubuntu 24.04
2/candidate 50 08 Oct 2025
Ubuntu 24.04
2/edge 52 03 Nov 2025
Ubuntu 24.04
juju deploy istio-ingress-k8s --channel 1/stable
Show information

Learn to deploy on juju >

Platform:

charms.istio_ingress_k8s.v0.istio_ingress_route

Interface Library for istio_ingress_route.

This library wraps relation endpoints for istio_ingress_route. The requirer of this relation is any charm needing advanced ingress routing (multi-port, multi-protocol). The provider is the istio-ingress-k8s charm.

Getting Started

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

cd some-charm
charmcraft fetch-lib charms.istio_ingress_k8s.v0.istio_ingress_route

To use the library from the requirer side:

requires:
    ingress:
        interface: istio_ingress_route

from charms.istio_ingress_k8s.v0.istio_ingress_route import (
    IstioIngressRouteRequirer,
    IstioIngressRouteConfig,
    Listener,
    HTTPRoute,
    GRPCRoute,
    BackendRef,
    ProtocolType,
    HTTPMethod,
    HTTPRouteMatch,
    HTTPPathMatch,
    PathMatchType,
    GRPCMethodMatch,
    GRPCRouteMatch,
    to_gateway_protocol,  # Helper for charm-side use
)

class MyCharm(CharmBase):
  def __init__(self, *args):
    # ...
    self.ingress = IstioIngressRouteRequirer(
        self,
        relation_name="ingress",
    )

    self.framework.observe(
        self.ingress.on.ready, self._on_ingress_ready
    )

  def _configure_ingress(self):
      # Define listeners - names are auto-generated by the charm
      http_listener = Listener(port=3200, protocol=ProtocolType.HTTP)
      grpc_listener = Listener(port=9096, protocol=ProtocolType.GRPC)

      config = IstioIngressRouteConfig(
          model=self.model.name,  # Requirer's namespace where services live
          listeners=[http_listener, grpc_listener],
          http_routes=[
              HTTPRoute(
                  name="http-route",
                  listener=http_listener,
                  matches=[
                      HTTPRouteMatch(
                          path=HTTPPathMatch(type=HTTPPathMatchType.PathPrefix, value="/api"),
                          method=HTTPMethod.GET
                      )
                  ],
                  backends=[BackendRef(service=self.app.name, port=3200)],
              ),
          ],
          grpc_routes=[
              GRPCRoute(
                  name="grpc-route",
                  listener=grpc_listener,
                  matches=[
                      GRPCRouteMatch(
                          method=GRPCMethodMatch(service="myapp.MyService", method="GetData")
                      )
                  ],
                  backends=[BackendRef(service=self.app.name, port=9096)],
              ),
          ],
      )
      self.ingress.submit_config(config)

  def _on_ingress_ready(self, event):
      # Get the final external URL
      scheme = "https" if self.ingress.tls_enabled else "http"
      url = f"{scheme}://{self.ingress.external_host}"
      # Use this URL for your application configuration

To use the library from the provider side (istio-ingress):

provides:
    istio-ingress-route:
        interface: istio_ingress_route

from charms.istio_ingress_k8s.v0.istio_ingress_route import IstioIngressRouteProvider

class IstioIngressCharm(CharmBase):
  def __init__(self, *args):
    # ...
    self.istio_ingress_route = IstioIngressRouteProvider(
        self,
        external_host=self._external_host,
        tls_enabled=self._is_tls_enabled(),
    )

    self.framework.observe(
        self.istio_ingress_route.on.ready, self._handle_istio_ingress_route_ready
    )

    def _handle_istio_ingress_route_ready(self, event):
        config = self.istio_ingress_route.get_config(event.relation)
        if not config:
            return

        # Transform listeners based on TLS availability
        is_tls_enabled = self._is_tls_enabled()
        for listener in config.listeners:
            gateway_protocol = to_gateway_protocol(listener.protocol, is_tls_enabled)
            # Use gateway_protocol to create Gateway listeners
            # Create HTTPRoutes and GRPCRoutes from config

Index

class IstioIngressRouteException

Description

Base class for exceptions raised by IstioIngressRoute. None

class UnauthorizedError

Description

Raised when the unit needs the leader to perform some action. None

class ProtocolType

Application-level protocol types.

Description

Consumers specify the application protocol (HTTP or GRPC). The istio-ingress charm automatically applies TLS encryption based on certificate availability, upgrading HTTP→HTTPS and GRPC→GRPCS transparently.

Note: The Gateway API doesn't have GRPC as a distinct protocol type. GRPC uses HTTP/2, so it maps to "HTTP" or "HTTPS" in Gateway listeners. The difference between HTTP and gRPC traffic is expressed through the route type (HTTPRoute vs GRPCRoute).

def to_gateway_protocol(
    protocol: ProtocolType,
    tls_enabled: bool
)

Map application protocol to Gateway API protocol.

Arguments

protocol

Application-level protocol (HTTP or GRPC)

tls_enabled

Whether TLS termination should be applied

Returns

Gateway API protocol string ("HTTP" or "HTTPS")

Description

The Gateway API doesn't have separate HTTP/gRPC protocol types. Both use HTTP, with the difference being in the route type (HTTPRoute vs GRPCRoute).

class HTTPMethod

Description

HTTP methods for route matching. None

class HTTPPathMatchType

Description

Path match types for HTTP routes. None

class Listener

Gateway listener configuration.

Description

Specify the application-level protocol (HTTP or GRPC). The istio-ingress charm will automatically upgrade to TLS (HTTPS/GRPCS) when certificates are available.

The listener name is automatically derived from port and protocol by the charm.

Methods

Listener. name( self )

Get the listener name derived from protocol and port.

Returns

Listener name in format: {protocol}-{port} (e.g., "http-8080", "grpc-9090")

Listener. gateway_protocol( self )

Get the Gateway API protocol (cleartext).

Returns

Gateway API protocol string without TLS ("HTTP")

Description

This maps GRPC -> HTTP, since Gateway API doesn't have a GRPC protocol type. Both HTTP and gRPC use HTTP/2; the difference is in the route type.

class BackendRef

Description

Reference to a backend service. None

class HTTPPathMatch

Description

Path matching configuration for HTTP routes. None

class GRPCMethodMatch

gRPC method matching configuration.

Description

Matches gRPC methods in the format /service/method where:

  • service can be a simple name (e.g., "MyService") or package-qualified (e.g., "package.MyService")
  • method is the RPC method name (optional - if omitted, matches all methods on the service)

class HTTPRouteMatch

Description

Match conditions for HTTP routes. None

class GRPCRouteMatch

Description

Match conditions for gRPC routes. None

class HTTPRoute

Description

HTTP route configuration. None

Methods

HTTPRoute. protocol( self )

Description

Protocol type for HTTP routes. None

class GRPCRoute

Description

gRPC route configuration. None

Methods

GRPCRoute. protocol( self )

Description

Protocol type for gRPC routes. None

class IstioIngressRouteConfig

Description

Complete configuration for istio-ingress-route. None

class IstioIngressRouteProviderReadyEvent

Description

Event emitted when istio-ingress is ready to provide ingress for a routed unit. None

class IstioIngressRouteProviderDataRemovedEvent

Description

Event emitted when a routed ingress relation is removed. None

class IstioIngressRouteRequirerReadyEvent

Description

Event emitted when a unit requesting ingress has provided all data. None

class IstioIngressRouteRequirerEvents

Description

Container for IstioIngressRouteRequirer events. None

class IstioIngressRouteProviderEvents

Description

Container for IstioIngressRouteProvider events. None

class IstioIngressRouteProvider

Implementation of the provider of istio_ingress_route.

Description

This will be owned by the istio-ingress charm. The main idea is that istio-ingress will observe the ready event and, upon receiving it, will fetch the config from the requirer's application databag, apply it (create Gateway listeners and Routes), and update its own app databag to let the requirer know that the ingress is ready.

Methods

IstioIngressRouteProvider. __init__( self , charm: CharmBase , relation_name: str , external_host: str )

Constructor for IstioIngressRouteProvider.

Arguments

charm

The charm that is instantiating the instance.

relation_name

The name of the relation to bind to (defaults to "istio-ingress-route").

external_host

The external host.

tls_enabled

Whether TLS is enabled on the gateway.

IstioIngressRouteProvider. external_host( self )

Description

Return the external host set by istio-ingress, if any. None

IstioIngressRouteProvider. tls_enabled( self )

Description

Return whether TLS is enabled on the gateway. None

IstioIngressRouteProvider. relations( self )

Description

The list of Relation instances associated with this endpoint. None

IstioIngressRouteProvider. update_ingress_address( self )

Description

Ensure that requirers know the external host for istio-ingress. None

IstioIngressRouteProvider. wipe_ingress_data( self , relation: Relation )

Clear ingress data from relation.

Arguments

relation

The relation to clear data from

Description

This removes the external_host and tls_enabled fields from the provider's application databag for the given relation. This is typically used when route conflicts are detected or when the ingress should no longer be available.

IstioIngressRouteProvider. is_ready( self , relation: Relation )

Whether IstioIngressRoute is ready on this relation.

Description

Returns True when the remote app shared the config; False otherwise.

IstioIngressRouteProvider. get_config( self , relation: Relation )

Description

Retrieve the config published by the remote application. None

class IstioIngressRouteRequirer

Handles the requirer side of the istio-ingress-route interface.

Description

This class provides an API for publishing routing configurations to the istio-ingress charm through the istio-ingress-route relation.

Methods

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

Constructor for IstioIngressRouteRequirer.

Arguments

charm

The charm that is instantiating the instance.

relation_name

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

IstioIngressRouteRequirer. external_host( self )

Description

Return the external host set by istio-ingress, if any. None

IstioIngressRouteRequirer. tls_enabled( self )

Description

Return whether TLS is enabled on the gateway. None

IstioIngressRouteRequirer. is_ready( self )

Description

Is the IstioIngressRouteRequirer ready to submit data? None

IstioIngressRouteRequirer. submit_config( self , config: IstioIngressRouteConfig )

Submit an ingress configuration to istio-ingress.

Arguments

config

The IstioIngressRouteConfig to submit.

Description

This method publishes routing configuration data to the istio-ingress-route relation.