How to provide a certificate

The gateway-api-integrator charm enforces HTTPS by default. To deploy the charm successfully with the default enforce-https=true configuration, you must integrate it with a certificate provider through the certificates relation.

Without this integration, the charm enters a blocked state:

gateway-api-integrator/0  blocked  idle  Certificates relation is required when enforce-https is enabled.

If you intentionally need to serve unencrypted HTTP instead, you can disable HTTPS enforcement. See How to configure HTTPS enforcement for the security implications and configuration instructions.

Prerequisites

Before you begin:

Use the self-signed-certificates charm

For development, testing, and other non-production environments, use the self-signed-certificates charm. This is the recommended and simplest way to satisfy the certificate requirement. The charm creates its own certificate authority (CA), issues the requested certificates, and renews them automatically.

Deploy the certificate provider:

juju deploy self-signed-certificates

Integrate it with gateway-api-integrator:

juju integrate self-signed-certificates:certificates gateway-api-integrator:certificates

When the certificate is available, both applications report an active status:

user@host:~$
juju status
App                       Status  Scale  Charm
gateway-api-integrator    active      1  gateway-api-integrator
self-signed-certificates  active      1  self-signed-certificates

Unit                         Workload  Agent  Message
gateway-api-integrator/0*    active    idle   Gateway addresses: <gateway-address>
self-signed-certificates/0*  active    idle

Retrieve the certificate issued for the gateway hostname or IP address:

juju run gateway-api-integrator/leader get-certificate \
  hostname=<hostname-or-gateway-address> \
  --format=json \
  | jq -r 'to_entries[0].value.results.certificate' \
  > gateway.crt

Caution

Clients do not trust self-signed certificates by default. Install the CA certificate on clients that must validate the gateway certificate, or use a publicly trusted certificate provider for production.

Use a certificate signed by your own CA

Use the manual-tls-certificates charm when you already have a CA and need to control the certificate-signing process. This option requires you to retrieve and sign each certificate signing request (CSR), then return the signed certificate and CA chain manually.

Follow the Manual TLS Certificates getting-started guide for the certificate-signing workflow. For this deployment, deploy the compatible channel and integrate it with gateway-api-integrator:

juju deploy manual-tls-certificates --channel=1/stable
juju integrate manual-tls-certificates:certificates gateway-api-integrator:certificates

After the relation creates a certificate request, follow the linked guide to retrieve the CSR and sign the certificate. The manual-tls-certificates charm then provides the certificate to gateway-api-integrator through the certificates relation.

Use the LEGO charm for production deployments

For production deployments with publicly resolvable domain names, use the LEGO charm. The LEGO charm obtains publicly trusted certificates from an ACME-compatible server, such as Let’s Encrypt, by using the DNS-01 challenge. It also renews certificates automatically.

Follow the LEGO charm documentation to deploy the charm and configure your DNS provider. Then integrate it with gateway-api-integrator:

juju integrate lego:certificates gateway-api-integrator:certificates

After the provider issues all requested certificates, gateway-api-integrator becomes active and serves HTTPS traffic.