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.
