---
title: Charmhub | ingress interface
description: Interfaces describe the relation between two charms. This interface shows
  opinionated, standardized interface specifications for charm relations.
url: https://charmhub.io/integrations/ingress
---

# ingress

Version 2, published

## Usage

This relation interface describes the expected behavior of any charm claiming to be able to provide or consume ingress data.

In most cases, this will be accomplished using the [ingress library](https://github.com/canonical/traefik-k8s-operator/blob/main/lib/charms/traefik_k8s/v1/ingress.py), although charm developers are free to provide alternative libraries as long as they fulfill the behavioral and schematic requirements described in this document.

## Direction

The `ingress` interface implements a provider/requirer pattern.
The requirer is a charm that wishes to receive ingress, and the provider is a charm able to provide it.

```
flowchart TD
    Requirer -- IngressData --> Provider
    Provider -- Ingress --> Requirer
```

## Behavior

The requirer and the provider need to adhere to a certain set of criteria to be considered compatible with the interface.

### Provider

* Is expected to provide ingress for the remote applications requesting it.
* Is expected to respect the ingress parameters sent by the requirer: hostname, port and model name (namespace).
* Is expected to publish the ingress url via relation data.
  The url is expected to have (by default) the following structure:

```
> `http://[ingress-hostname]:[port]/[model]-[unit]/`
```

where:

* `ingress-hostname` is the hostname that the ingress is configured with
* `model` is the name of the model the application requesting ingress is deployed into
* `unit` is the name of the unit this address leads to, with `/` replaced by `-` (E.g. `myapp/0` becomes `myapp-0`).
* `port` is the port to expose in the unit.

The structure of this URL is fixed in the generic ingress schema; specific ingress providers implementations may offer some way of customising it.

### Requirer

* Is expected to provide a port, application name, and a model name (namespace).
* Is expected to provide, for each unit requesting ingress, a hostname.

## Relation Data

Pydantic schemas for provider and requirer can be found [[here]](https://github.com/canonical/charmlibs/blob/main/interfaces/ingress/interface/vv2/schema.py)
All fields are json-serialized.

### Requirer

Exposes the unit name (`name`), model name (`model`), hostname (`host`) and port (`port`) at which ingress should be provided.
`name`, `port` and `model` should be placed in the **application** databag. `host`, as it may differ per ingressed unit (e.g. if it's a fqdn), will be placed in the **unit** databags of the respective ingress-requesting units.

#### Example

```
application-data: {
 name: '"app_name"',
 model: '"model_name"',
 port: '4242',
}
unit-data: {
 host: '"hostname"',
}
```

### Provider

Exposes a `url` field containing the url at which ingress is available. Should be placed in the **application** databag.

#### Example

```
application_data: {
  ingress: '{"url": "http://foo.bar:80/model_name-app_name/0"}'
}
```

## Charms implementing this interface

### Providers

* [traefik-k8s](https://charmhub.io/traefik-k8s)

### Requirers

## Other charms using this interface

### Providers

* [traefik-k8s](https://charmhub.io/traefik-k8s)
* [istio-pilot](https://charmhub.io/istio-pilot)
* [istio-ingress-k8s](https://charmhub.io/istio-ingress-k8s)
* [nginx-ingress-integrator](https://charmhub.io/nginx-ingress-integrator)
* [content-cache-k8s](https://charmhub.io/content-cache-k8s)

### Requirers

* [traefik-k8s](https://charmhub.io/traefik-k8s)
* [vault-k8s](https://charmhub.io/vault-k8s)
* [grafana-k8s](https://charmhub.io/grafana-k8s)
* [mattermost-k8s](https://charmhub.io/mattermost-k8s)
* [alertmanager-k8s](https://charmhub.io/alertmanager-k8s)
* [openfga-k8s](https://charmhub.io/openfga-k8s)
* [indico](https://charmhub.io/indico)
* [trino-k8s](https://charmhub.io/trino-k8s)
* [kfp-ui](https://charmhub.io/kfp-ui)
* [spark-history-server-k8s](https://charmhub.io/spark-history-server-k8s)
* [reductstore-k8s](https://charmhub.io/reductstore-k8s)
* [oidc-gatekeeper](https://charmhub.io/oidc-gatekeeper)
* [kubernetes-dashboard](https://charmhub.io/kubernetes-dashboard)
* [jupyter-ui](https://charmhub.io/jupyter-ui)
* [kubeflow-dashboard](https://charmhub.io/kubeflow-dashboard)
* [juju-dashboard-k8s](https://charmhub.io/juju-dashboard-k8s)
* [airbyte-k8s](https://charmhub.io/airbyte-k8s)
* [superset-k8s](https://charmhub.io/superset-k8s)
* [juju-jimm-k8s](https://charmhub.io/juju-jimm-k8s)
* [mimir-coordinator-k8s](https://charmhub.io/mimir-coordinator-k8s)
* [datahub-k8s](https://charmhub.io/datahub-k8s)
* [blackbox-exporter-k8s](https://charmhub.io/blackbox-exporter-k8s)
* [dex-auth](https://charmhub.io/dex-auth)
* [bingo](https://charmhub.io/bingo)
* [netbox-k8s](https://charmhub.io/netbox-k8s)
* [vault](https://charmhub.io/vault)
* [temporal-ui-k8s](https://charmhub.io/temporal-ui-k8s)
* [loki-coordinator-k8s](https://charmhub.io/loki-coordinator-k8s)
* [content-cache-k8s](https://charmhub.io/content-cache-k8s)
* [ranger-k8s](https://charmhub.io/ranger-k8s)
* [httprequest-lego-provider](https://charmhub.io/httprequest-lego-provider)
* [mlflow-server](https://charmhub.io/mlflow-server)
* [mm-pd-bot](https://charmhub.io/mm-pd-bot)
* [oauth2-proxy-k8s](https://charmhub.io/oauth2-proxy-k8s)
* [kubeflow-volumes](https://charmhub.io/kubeflow-volumes)
* [katib-ui](https://charmhub.io/katib-ui)
* [lego](https://charmhub.io/lego)
* [canonical-livepatch-server-k8s](https://charmhub.io/canonical-livepatch-server-k8s)
* [catalogue-k8s](https://charmhub.io/catalogue-k8s)