Getting Started (v4)
In this tutorial, we will take a working Nginx charm and add the TLS Certificates integration using the TLS certificates library v4.
Pre-requisites
Knowledge
- You have some experience writing charms and are comfortable with the charm development tooling
Software
- Ubuntu 22.04
- A Juju controller running on a MicroK8s
- Charmcraft
1. Pack and deploy the nginx demo charm
In this section, we will deploy a demo Nginx charm and access its HTTP address via our browser.
Clone the TLS Certificates Interface Demo project:
git clone git@github.com:canonical/tls-certificates-interface-demo.git
Move to the repo directory:
cd tls-certificates-interface-demo
Pack the charm
charmcraft pack
Create a Juju model:
juju add-model demo
Deploy the charm
juju deploy ./tls-certificates-interface-demo_ubuntu-22.04-amd64.charm nginx-http --resource nginx-image=nginx:1.27.1
Wait for the charm to go to the Active/Idle status:
guillaume@thinkpad:~/code/tls-certificates-interface-demo$ juju status
Model Controller Cloud/Region Version SLA Timestamp
demo microk8s-localhost microk8s/localhost 3.5.3 unsupported 15:12:25-04:00
App Version Status Scale Charm Channel Rev Address Exposed Message
nginx-http active 1 tls-certificates-interface-demo 0 10.152.183.199 no
Unit Workload Agent Address Ports Message
nginx-http/0* active idle 10.1.19.158
Using your browser, navigate to the application address on port 8080 using the HTTP scheme. Here this would be http://10.152.183.199:8080.
You should see the following page:
We now know that have a working Nginx charm.
2. Import and use the TLS Certificates Library
This section outlines the changes that have to be made to the Nginx charm to support the TLS certificates integration. You can use this pull request as reference as well.
Fetch the TLS Certificates charm library
charmcraft fetch-lib charms.tls_certificates_interface.v4.tls_certificates
Add the following packages to the charm’s requirements.txt file:
cryptography==43.0.1
pydantic==2.9.1
Add the following section to the charm’s charmcraft.yaml file:
requires:
certificates:
interface: tls-certificates
parts:
charm:
build-packages:
- cargo
- libffi-dev
- libssl-dev
- pkg-config
- rustc
All of the following changes here are made in src/charm.py.
Import the following classes from TLS Certificates Interface Library in your charm code:
from lib.charms.tls_certificates_interface.v4.tls_certificates import (
Certificate,
CertificateRequestAttributes,
Mode,
PrivateKey,
TLSCertificatesRequiresV4,
)
Add the following global variables:
CERTS_DIR_PATH = "/etc/nginx"
PRIVATE_KEY_NAME = "nginx.key"
CERTIFICATE_NAME = "nginx.pem"
In the charm’s class constructor, instantiate a TLSCertificatesRequiresV4 object and have the Certificate Available Event handled by our central configure event handler:
class TlsCertificatesInterfaceDemoCharm(ops.CharmBase):
"""Charm the service."""
def __init__(self, framework: ops.Framework):
super().__init__(framework)
...
self.certificates = TLSCertificatesRequiresV4(
charm=self,
relationship_name="certificates",
certificate_requests=[self._get_certificate_request_attributes()],
mode=Mode.UNIT,
)
...
framework.observe(
self.certificates.on.certificate_available, self._configure
)
...
Add a _get_certificate_request_attributes method that returns the list of certificate requested by the charm:
class TlsCertificatesInterfaceDemoCharm(ops.CharmBase):
def _get_certificate_request_attributes(self) -> CertificateRequestAttributes:
return CertificateRequestAttributes(common_name="example.com")
In the collect unit status event handler, have the charm go to Blocked status until it is integrated with a TLS Certificates Provider:
class TlsCertificatesInterfaceDemoCharm(ops.CharmBase):
def __init__(self, framework: ops.Framework):
...
framework.observe(self.on.collect_unit_status, self._on_collect_status)
def _on_collect_status(self, event: ops.CollectStatusEvent):
...
if not self._relation_created("certificates"):
event.add_status(
ops.BlockedStatus("certificates integration not created")
)
return
...
Update the _configure event handler to manage TLS Certificates and restart the Pebble container when certificates have changed:
class TlsCertificatesInterfaceDemoCharm(ops.CharmBase):
"""Charm the service."""
def __init__(self, framework: ops.Framework):
super().__init__(framework)
...
framework.observe(self.on["nginx"].pebble_ready, self._configure)
framework.observe(self.on.config_changed, self._configure)
framework.observe(self.certificates.on.certificate_available, self._configure)
def _configure(self, _: ops.EventBase):
if not self.container.can_connect():
return
if not self._relation_created("certificates"):
return
if not self._certificate_is_available():
return
certificate_update_required = self._check_and_update_certificate()
desired_config_file = self._generate_config_file()
if config_update_required := self._is_config_update_required(desired_config_file):
self._push_config_file(content=desired_config_file)
should_restart = config_update_required or certificate_update_required
self._configure_pebble(restart=should_restart)
We will need the following methods to handle pulling, pushing and comparing certificates:
class TlsCertificatesInterfaceDemoCharm(ops.CharmBase):
def _relation_created(self, relation_name: str) -> bool:
return bool(self.model.relations.get(relation_name))
def _certificate_is_available(self) -> bool:
cert, key = self.certificates.get_assigned_certificate(
certificate_request=self._get_certificate_request_attributes()
)
return bool(cert and key)
def _check_and_update_certificate(self) -> bool:
"""Check if the certificate or private key needs an update and perform the update.
This method retrieves the currently assigned certificate and private key associated with
the charm's TLS relation. It checks whether the certificate or private key has changed
or needs to be updated. If an update is necessary, the new certificate or private key is
stored.
Returns:
bool: True if either the certificate or the private key was updated, False otherwise.
"""
provider_certificate, private_key = self.certificates.get_assigned_certificate(
certificate_request=self._get_certificate_request_attributes()
)
if not provider_certificate or not private_key:
logger.debug("Certificate or private key is not available")
return False
if certificate_update_required := self._is_certificate_update_required(
provider_certificate.certificate
):
self._store_certificate(certificate=provider_certificate.certificate)
if private_key_update_required := self._is_private_key_update_required(private_key):
self._store_private_key(private_key=private_key)
return certificate_update_required or private_key_update_required
def _is_certificate_update_required(self, certificate: Certificate) -> bool:
return self._get_existing_certificate() != certificate
def _is_private_key_update_required(self, private_key: PrivateKey) -> bool:
return self._get_existing_private_key() != private_key
def _get_existing_certificate(self) -> Optional[Certificate]:
return self._get_stored_certificate() if self._certificate_is_stored() else None
def _get_existing_private_key(self) -> Optional[PrivateKey]:
return self._get_stored_private_key() if self._private_key_is_stored() else None
def _certificate_is_stored(self) -> bool:
return self.container.exists(path=f"{CERTS_DIR_PATH}/{CERTIFICATE_NAME}")
def _private_key_is_stored(self) -> bool:
return self.container.exists(path=f"{CERTS_DIR_PATH}/{PRIVATE_KEY_NAME}")
def _get_stored_certificate(self) -> Certificate:
cert_string = str(self.container.pull(path=f"{CERTS_DIR_PATH}/{CERTIFICATE_NAME}").read())
return Certificate.from_string(cert_string)
def _get_stored_private_key(self) -> PrivateKey:
key_string = str(self.container.pull(path=f"{CERTS_DIR_PATH}/{PRIVATE_KEY_NAME}").read())
return PrivateKey.from_string(key_string)
def _store_certificate(self, certificate: Certificate) -> None:
"""Store certificate in workload."""
self.container.push(path=f"{CERTS_DIR_PATH}/{CERTIFICATE_NAME}", source=str(certificate))
logger.info("Pushed certificate pushed to workload")
def _store_private_key(self, private_key: PrivateKey) -> None:
"""Store private key in workload."""
self.container.push(
path=f"{CERTS_DIR_PATH}/{PRIVATE_KEY_NAME}",
source=str(private_key),
)
logger.info("Pushed private key to workload")
3. Deploy the nginx charm and integrate it with a TLS provider
Deploy the new nginx charm:
juju deploy ./tls-certificates-interface-demo_ubuntu-22.04-amd64.charm nginx-https --resource nginx-image=nginx:1.27.1
Wait for the charm to go to the Blocked/idle status:
guillaume@thinkpad:~/code/tls-certificates-interface-demo$ juju status
Model Controller Cloud/Region Version SLA Timestamp
demo microk8s-localhost microk8s/localhost 3.5.3 unsupported 15:15:22-04:00
App Version Status Scale Charm Channel Rev Address Exposed Message
nginx-http active 1 tls-certificates-interface-demo 0 10.152.183.199 no
nginx-https blocked 1 tls-certificates-interface-demo 1 10.152.183.188 no certificates integration not created
Unit Workload Agent Address Ports Message
nginx-http/0* active idle 10.1.19.158
nginx-https/0* blocked idle 10.1.19.145 certificates integration not created
Deploy Self Signed Certificates (a TLS Certificates provider), and integrate it with the nginx charm
juju deploy self-signed-certificates
juju integrate self-signed-certificates:certificates nginx-https:certificates
Wait for the nginx-https charm to go to the Active/Idle status:
guillaume@thinkpad:~/code/tls-certificates-interface-demo$ juju status
Model Controller Cloud/Region Version SLA Timestamp
demo microk8s-localhost microk8s/localhost 3.5.3 unsupported 15:17:13-04:00
App Version Status Scale Charm Channel Rev Address Exposed Message
nginx-http active 1 tls-certificates-interface-demo 0 10.152.183.199 no
nginx-https waiting 1 tls-certificates-interface-demo 1 10.152.183.188 no installing agent
self-signed-certificates active 1 self-signed-certificates latest/stable 155 10.152.183.242 no
Unit Workload Agent Address Ports Message
nginx-http/0* active idle 10.1.19.158
nginx-https/0* active idle 10.1.19.145
self-signed-certificates/0* active idle 10.1.19.146
Using your browser, navigate to the application address on port 8080 using the HTTPS scheme. Here this would be https://10.152.183.188:8080.
You should see the following page telling you that the HTTPs certificate is not valid:
Don’t worry, this message is expected since the certificate we received is self-signed.
Click on Advanced → Proceed and you should now see the same Nginx page as in step 1.
You can inspect the certificate and notice that you received a certificate for example.com.
Congratulations, you added the TLS integration to your charm.