How to set up production integrations

See first: Charm maturity

A production-ready charm should fit into the Juju ecosystem, integrating with other applications. Therefore, it needs to be compatible with other charms. This guide summarises the integrations that production charms often need to support.

These integrations are not mandatory for your charm to work. You need to decide which ones to use based on your charm’s workload.

Tip

If your charm uses a Charmcraft 12-factor app extension, many integrations are set up for you. See Charmcraft | Manage relations for a 12-factor app charm. To add custom integrations to a 12-factor app charm, follow Add a custom integration to a 12-factor app charm instead of this page.

Best practices

Juju can integrate two charms when their endpoints use the same interface name. You should use existing interface names for any integration that your charm supports. To browse the available interfaces and their supporting libraries, see Charmlibs | Interface libraries.

Writing integration tests is the best way to validate that your charm can integrate well with others. See How to write integration tests for a charm, then How to manage relations | Integration tests.

Ingress

Integrate your charm with an ingress provider when your workload serves HTTP or HTTPS, and users or applications outside the model need to reach it at a stable URL. Your charm declares a requires endpoint that uses the ingress interface, and consumes the ingress data from the provider.

Some providers:

• Gateway API Integrator, NGINX Ingress Integrator, and Istio Ingress on Kubernetes.

• Ingress Configurator on machines. It translates ingress to the haproxy-route interface of the HAProxy charm.

In most cases, your charm can use the traefik_k8s.ingress library. See also the ingress v2 interface specification.

Example charm: Jenkins

Observability

Integrate your charm with the Canonical Observability Stack (COS) to provide metrics, logs, alerts, and dashboards for your workload. Most charms with a workload need it. A charm that doesn’t run a workload, such as an integrator charm, might not.

To integrate your charm with COS:

• On Kubernetes, your charm integrates with each COS component over its own interface. Declare a provides endpoint for each of prometheus_scrape (Prometheus) and grafana_dashboard (Grafana), and a requires endpoint for loki_push_api (Loki). See Observe your charm with COS Lite in our Kubernetes charm tutorial. To trace your charm code and send the trace data to COS, see How to trace your charm.

• On machines, your charm declares a single provides endpoint that uses the cos_agent interface. Use the grafana_agent.cos_agent library to implement it. The OpenTelemetry Collector subordinate charm forwards everything to COS. See more: COS | Instrument machine charms.

Example charms: Hydra, Valkey

Databases

Charms often need to connect to a database. Your charm declares a requires endpoint that uses the interface for your database. Each database technology has its own interface:

Database	Interface	Provider charms
PostgreSQL	postgresql_client	postgresql, postgresql-k8s
MySQL	mysql_client	mysql, mysql-k8s
MongoDB	mongodb_client	mongodb, mongodb-k8s

The dpcharmlibs-interfaces library covers all of these interfaces. New charms should use this library. Some existing charms still use the older data_platform_libs.v0.data_interfaces charm library.

Example charms: MediaWiki uses dpcharmlibs-interfaces for its Valkey relation (interface valkey_client). Discourse requires postgresql_client and MediaWiki requires mysql_client, but both still use the older data_platform_libs.v0.data_interfaces library for these.

TLS certificates

Integrate your charm with a certificate provider when your workload needs TLS certificates, for example to serve or query from HTTPS endpoints. Your charm declares a requires endpoint that uses the tls-certificates interface and receives certificates from the provider.

Some providers:

• Self Signed Certificates

• Lego

• Manual TLS Certificates

• Vault

New charms should use the charmlibs.interfaces.tls_certificates library. Some existing charms still use the older tls_certificates_interface.tls_certificates charm library.

Example charms: NGINX Ingress Integrator, Landscape

Object storage

Integrate your charm with an object storage provider when your workload needs S3-compatible storage. Your charm declares a requires endpoint that uses the s3 interface, and receives the endpoint, bucket, and credentials from the provider.

The main provider is S3 Integrator, which you configure with the details of an S3-compatible service. Use the object-storage-charmlib library to implement the integration.

Example charms: MLflow, Valkey

Identity

Use the Canonical Identity Stack for identity and access management of your charm. To compare the available solutions, see Choosing an identity solution. Your charm declares a requires endpoint that uses the interface for the protocol that your workload supports:

Protocol	Interface	Provider charms	Library
OAuth 2.0 and OpenID Connect (OIDC)	oauth	hydra, authentik-server	charmlibs.interfaces.oauth
LDAP	ldap	glauth-k8s, authentik-ldap-outpost	charmlibs.interfaces.ldap
SAML	saml	saml-integrator provides SAML configuration details to charms that authenticate with a SAML server. It doesn’t provide SAML functionality.	saml_integrator.saml

Example charms: SSSD uses the LDAP library. Discourse uses the SAML library.