Upcoming Deprecation of the Ingress Relation in the Nginx Ingress Integrator Charm

The Nginx ingress integrator charm was created before the ingress relation interface existed. The similarity in the names between the ingress relation of the Nginx ingress integrator charm and the ingress relation interface, as used by the traefik charm, is purely coincidental. Previous attempts to make the Nginx ingress integrator charm’s ingress relation compliant with the ingress relation interface failed due to fundamental differences, particularly in the interpretation of the host field in relation data.

To alleviate this confusion and improve interoperability, we have decided to rename the ingress relation in the Nginx ingress integrator charm to nginx-route. This change will also give us the opportunity to revisit the ingress charm library and replace it with the nginx-route charm library, which will have a more intuitive and less error-prone Python interface.

In the coming weeks, we will release a new revision of the Nginx ingress integrator charm that will support the nginx-route relation in addition to the existing ingress relation. This update will also include the nginx-route charm library for managing the nginx-route relation. Additionally, a detailed upgrade guide will be provided for the upgrade process.

We understand that these changes may cause inconvenience and apologize for any disruption they may cause. We are grateful for the support of our community during this transition and welcome any feedback on issues encountered during the upgrade process.

If you receive the following warning message in the status of the Nginx ingress integrator charm after upgrading it:

app [{connected_app_names}] connected via deprecated ingress relation, please update to nginx-route relation

it is recommended that you upgrade your charm to use the nginx-route relation. If you are the charm author, you can follow the guide below to upgrade your charm:

Step 1: Download the nginx_route charm library into your charm and remove the ingress charm library by running the following command:

charmcraft fetch-lib charms.nginx-ingress-integrator.v0.nginx_route
rm lib/charms/nginx_ingress_integrator/v0/ingress.py

Step 2: Update the metadata.yaml file in your charm to reflect the new relation interface:

Original metadata.yaml:

requires:
  ingress:
    interface: ingress

Updated metadata.yaml file:

requires:
  nginx-route:
    interface: nginx-route

Step 3: Update your charm source code to use the nginx-route relation and charm library:

Here’s an example of a charm using the ingress relation:

...
from charms.nginx_ingress_integrator.v0.ingress import IngressRequires

class ExampleCharm(CharmBase):
    def __init__(self, *args, **kwargs):
        ...
        self._ingress = IngressRequires(self, {
            "service-hostname": self.config["external_hostname"],
            "service-name": self.app.name,
            "service-port": 80,
        })
        self.framework.observe(self.on.config_changed, self._update_ingress_config)
    
    def _update_ingress(self, event):
        if self.config["additional_hostnames"]:
            self._ingress.update_config({"additional-hostnames": self.config["additional_hostnames"]})

And here’s the same charm upgraded to use the nginx-route relation and charm library:

...
from charms.nginx_ingress_integrator.v0.nginx_route import require_nginx_route

class ExampleCharm(CharmBase):
    def __init__(self, *args, **kwargs):
        ...
        self._require_nginx_route()

    def _require_nginx_route(self):
        require_nginx_route(
            charm=self,
            service_hostname=self.config["external_hostname"],
            service_name=self.app.name,
            service_port=80,
            additional_hostnames=self.config["additional_hostnames"] if self.config["additional_hostnames"] else None
        )

After upgrading your charm source code, it’s best to test the upgraded charm locally before publishing it to Charmhub.

Step 4: Upgrade your charm deployment

Since the relation has changed, you need to remove the ingress relation before refreshing your charm:

juju remove-relation example-app nginx-ingress-integrator
juju refresh example-app
juju relate example-app:nginx-route nginx-ingress-integrator

That’s it! Your charm is now upgraded to use the nginx-route relation and charm library.

2 Likes

Great, would love to see the new interface in the charm-relation-interfaces repo so we can all collaborate on defining it - hopefully with a bit more longevity! :slight_smile:

1 Like

Thank you for your support! However, I am unsure about including the nginx-route relation in the charm-relation-interfaces repository. As the name suggests, this relation is specifically designed to be used with the Nginx ingress integrator charm, and therefore may not be relevant to other charms. Do you recommend adding the nginx-route relation to the charm-relation-interfaces repository in this situation?

Hey :slight_smile:

Yes I still think it’s a good idea. If nothing else, the format of the interfaces there encourage some good thinking around structure and consistency, and will also serve as formal documentation for the interface. It also means that other folk from the charm universe can pitch in suggestions/reviews as well :slight_smile:

Jon

Thank you for your advice! Once I’ve added ‘nginx-route’ to the Nginx ingress integrator, I will create a pull request in the ‘charm-relation-interfaces’ repository to include the ‘nginx-route’ relation.

A small heads up that this link leads an invalid URL (404).

That should be lib/charms/nginx_ingress_integrator/v0/ingress.py as the path I believe.

Yes, this is indeed strange.

Just for your information, this pages exists in the staging Charmhub instance: Charmhub | Interface catalogue

Updated, thanks!

We have added a new feature to the nginx-ingress-integrator in revision 80 for zero-downtime migration from the nginx-route relation to the ingress relation. The zero-downtime migration is designed for mission-critical applications and is not intended for ordinary users.

Actually, it’s already there: https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/nginx_route/v0

:slight_smile: