--- title: Charmhub | Deploy Istio Ingress using Charmhub - The Open Operator Collection description: Deploy the latest version of Istio Ingress as a Kubernetes Operator on any cloud. url: https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route --- # Istio Ingress [Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability") * [Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability") Platform: 1/stable rev33-4-gd208806 ``` juju deploy istio-ingress-k8s --channel 1/stable ``` [Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications) [Toggle side navigation](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#drawer) ## charms.istio\_ingress\_k8s.v0.istio\_ingress\_route * [*Docstrings*Docstrings](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route) [*Code*Source code](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route/source-code) * + Download Fetch library ``` charmcraft fetch-lib charms.istio_ingress_k8s.v0.istio_ingress_route ``` [Download istio\_ingress\_route.py](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route/download) + *Last updated* 02 Oct 2026 + *Revision* Library version 0.4 #### 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 ``` Note: If you are using this library on standard ports (80/443), you will have to check if TLS is enabled. ``` if self.ingress.tls_enabled: port = 443 else: port = 80 http_listener = Listener(port=port, protocol=ProtocolType.HTTP) ``` 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](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteexception) * [class UnauthorizedError](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#unauthorizederror) * [class ProtocolType](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#protocoltype) * [def to\_gateway\_protocol( protocol, tls\_enabled )](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#to_gateway_protocol) * [class Listener](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#listener) * + [def name( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#listener-name) * + [def gateway\_protocol( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#listener-gateway_protocol) * [class BackendRef](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#backendref) * [class HTTPMethod](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httpmethod) * [class HTTPPathMatchType](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httppathmatchtype) * [class HTTPPathMatch](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httppathmatch) * [class GRPCMethodMatch](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#grpcmethodmatch) * [class HTTPRouteMatch](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httproutematch) * [class GRPCRouteMatch](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#grpcroutematch) * [class PathModifierType](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#pathmodifiertype) * [class PathModifier](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#pathmodifier) * + [def validate\_path\_modifier( cls, data)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#pathmodifier-validate_path_modifier) * + [def serialize\_model( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#pathmodifier-serialize_model) * [class FilterType](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#filtertype) * [class URLRewriteSpec](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#urlrewritespec) * [class URLRewriteFilter](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#urlrewritefilter) * + [def type( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#urlrewritefilter-type) * [class RequestRedirectSpec](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#requestredirectspec) * [class RequestRedirectFilter](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#requestredirectfilter) * + [def type( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#requestredirectfilter-type) * [class HTTPRoute](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httproute) * + [def protocol( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#httproute-protocol) * [class GRPCRoute](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#grpcroute) * + [def protocol( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#grpcroute-protocol) * [class IstioIngressRouteConfig](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteconfig) * [class IstioIngressRouteProviderReadyEvent](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteproviderreadyevent) * [class IstioIngressRouteProviderDataRemovedEvent](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteproviderdataremovedevent) * [class IstioIngressRouteRequirerReadyEvent](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirerreadyevent) * [class IstioIngressRouteRequirerEvents](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirerevents) * [class IstioIngressRouteProviderEvents](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteproviderevents) * [class IstioIngressRouteProvider](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider) * + [def \_\_init\_\_( self, charm, relation\_name, external\_host)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-__init__) * + [def external\_host( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-external_host) * + [def tls\_enabled( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-tls_enabled) * + [def relations( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-relations) * + [def update\_ingress\_address( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-update_ingress_address) * + [def wipe\_ingress\_data( self, relation)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-wipe_ingress_data) * + [def is\_ready( self, relation)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-is_ready) * + [def get\_config( self, relation)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouteprovider-get_config) * [class IstioIngressRouteRequirer](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer) * + [def \_\_init\_\_( self, charm, relation\_name)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer-__init__) * + [def external\_host( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer-external_host) * + [def tls\_enabled( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer-tls_enabled) * + [def is\_ready( self)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer-is_ready) * + [def submit\_config( self, config)](https://charmhub.io/istio-ingress-k8s/libraries/istio_ingress_route#istioingressrouterequirer-submit_config) #### 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 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 HTTPMethod Description HTTP methods for route matching. None #### class HTTPPathMatchType Description Path match types for HTTP routes. 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 PathModifierType Description Path modifier types. None #### class PathModifier Description Path modification configuration. None Methods PathModifier. validate\_path\_modifier( cls , data ) Description Handle deserialization from K8s Gateway API format. None PathModifier. serialize\_model( *self* ) Description Serialize with correct field name for K8s Gateway API. None #### class FilterType Description Filter type values. None #### class URLRewriteSpec Specification for URL rewrite configuration. Description At least one of hostname or path must be specified. #### class URLRewriteFilter Description URLRewrite filter for modifying request URL before proxying upstream. None Methods URLRewriteFilter. type( *self* ) Description Filter type. None #### class RequestRedirectSpec Description Specification for request redirect configuration. None #### class RequestRedirectFilter Description Request redirect filter for HTTP/gRPC redirects. None Methods RequestRedirectFilter. type( *self* ) Description Filter type. 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.