Nginx Ingress Integrator

  • By Canonical IS DevOps
Channel Revision Published Runs on
latest/stable 84 Yesterday
Ubuntu 20.04
latest/edge 83 09 Nov 2023
Ubuntu 20.04
v2/edge 84 09 Jan 2024
Ubuntu 20.04
juju deploy nginx-ingress-integrator
Show information

Platform:

Ubuntu
20.04

charms.nginx_ingress_integrator.v0.ingress

Library for the ingress relation.

This library contains the Requires and Provides classes for handling the ingress interface.

Import IngressRequires in your charm, with two required options:

  • "self" (the charm itself)
  • config_dict

config_dict accepts the following keys:

  • additional-hostnames
  • backend-protocol
  • limit-rps
  • limit-whitelist
  • max-body-size
  • owasp-modsecurity-crs
  • owasp-modsecurity-custom-rules
  • path-routes
  • retry-errors
  • rewrite-enabled
  • rewrite-target
  • service-hostname (required)
  • service-name (required)
  • service-namespace
  • service-port (required)
  • session-cookie-max-age
  • tls-secret-name

See the config section for descriptions of each, along with the required type.

As an example, add the following to src/charm.py:

from charms.nginx_ingress_integrator.v0.ingress import IngressRequires

# In your charm's `__init__` method (assuming your app is listening on port 8080).
self.ingress = IngressRequires(self, {
        "service-hostname": self.app.name,
        "service-name": self.app.name,
        "service-port": 8080,
    }
)

And then add the following to metadata.yaml:

requires:
  ingress:
    interface: ingress

You must register the IngressRequires class as part of the __init__ method rather than, for instance, a config-changed event handler, for the relation changed event to be properly handled.

In the example above we're setting service-hostname (which translates to the external hostname for the application when related to nginx-ingress-integrator) to self.app.name here. This ensures by default the charm will be available on the name of the deployed juju application, but can be overridden in a production deployment by setting service-hostname on the nginx-ingress-integrator charm. For example:

juju deploy nginx-ingress-integrator
juju deploy my-charm
juju relate nginx-ingress-integrator my-charm:ingress
# The service is now reachable on the ingress IP(s) of your k8s cluster at
# 'http://my-charm'.
juju config nginx-ingress-integrator service-hostname='my-charm.example.com'
# The service is now reachable on the ingress IP(s) of your k8s cluster at
# 'http://my-charm.example.com'.

class IngressAvailableEvent

IngressAvailableEvent custom event.

Description

This event indicates the Ingress provider is available.

class IngressProxyAvailableEvent

IngressProxyAvailableEvent custom event.

Description

This event indicates the IngressProxy provider is available.

class IngressBrokenEvent

IngressBrokenEvent custom event.

Description

This event indicates the Ingress provider is broken.

class IngressCharmEvents

Custom charm events.

Description

Attrs: ingress_available: Event to indicate that Ingress is available. ingress_proxy_available: Event to indicate that IngressProxy is available. ingress_broken: Event to indicate that Ingress is broken.

class IngressRequires

This class defines the functionality for the 'requires' side of the 'ingress' relation.

Description

Hook events observed: - relation-changed

Attrs: model: Juju model where the charm is deployed. config_dict: Contains all the configuration options for Ingress.

Methods

IngressRequires. __init__( self , charm: CharmBase , config_dict: Dict )

Init function for the IngressRequires class.

Arguments

charm

The charm that requires the ingress relation.

config_dict

Contains all the configuration options for Ingress.

IngressRequires. update_config( self , config_dict: Dict )

Allow for updates to relation.

Arguments

config_dict

Contains all the configuration options for Ingress.

class IngressBaseProvides

Parent class for IngressProvides and IngressProxyProvides.

Description

Attrs: model: Juju model where the charm is deployed.

Methods

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

Init function for the IngressProxyProvides class.

Arguments

charm

The charm that provides the ingress-proxy relation.

relation_name

The name of the relation.

class IngressProvides

Class containing the functionality for the 'provides' side of the 'ingress' relation.

Description

Hook events observed: - relation-changed

Methods

IngressProvides. __init__( self , charm: CharmBase )

Init function for the IngressProvides class.

Arguments

charm

The charm that provides the ingress relation.

class IngressProxyProvides

Class containing the functionality for the 'provides' side of the 'ingress-proxy' relation.

Description

Hook events observed: - relation-changed

Methods

IngressProxyProvides. __init__( self , charm: CharmBase )

Init function for the IngressProxyProvides class.

Arguments

charm

The charm that provides the ingress-proxy relation.