Observability Libs

  • By Jon Seager
Channel Revision Published Runs on
latest/edge 48 04 Sep 2024
Ubuntu 20.04
juju deploy observability-libs --channel edge
Show information

Platform:

charms.observability_libs.v1.cert_handler

Overview.

This document explains how to use the CertHandler class to create and manage TLS certificates through the tls_certificates interface.

The goal of the CertHandler is to provide a wrapper to the tls_certificates library functions to make the charm integration smoother.

Library Usage

This library should be used to create a CertHandler object, as per the following example:

self.cert_handler = CertHandler(
    charm=self,
    key="my-app-cert-manager",
    cert_subject="unit_name",  # Optional
)

You can then observe the library's custom event and make use of the key and cert:

self.framework.observe(self.cert_handler.on.cert_changed, self._on_server_cert_changed)

container.push(keypath, self.cert_handler.private_key)
container.push(certpath, self.cert_handler.server_cert)

Since this library uses Juju Secrets it requires Juju >= 3.0.3.


def is_ip_address(value: str)

Description

Return True if the input value is a valid IPv4 address; False otherwise. None

class CertChanged

Description

Event raised when a cert is changed (becomes available or revoked). None

class CertHandlerEvents

Description

Events for CertHandler. None

class Vault

Description

Simple application secret wrapper for local usage. None

Methods

Vault. __init__( self , backend: _VaultBackend )

Vault. store( self , contents , clear: bool )

Description

Store these contents in the vault overriding whatever is there. None

Vault. get_value( self , key: str )

Description

Like retrieve, but single-value. None

Vault. retrieve( self )

Description

Return the full vault content. None

Vault. clear( self )

Description

Clear the vault. None

class CertHandler

Description

A wrapper for the requirer side of the TLS Certificates charm library. None

Methods

CertHandler. __init__( self , charm: CharmBase )

CertHandler is used to wrap TLS Certificates management operations for charms.

Arguments

charm

The owning charm.

key

A manually-crafted, static, unique identifier used by ops to identify events. It shouldn't change between one event to another.

certificates_relation_name

Name of the certificates relation over which we obtain TLS certificates. Must match metadata.yaml.

peer_relation_name

Name of a peer relation used to store our secrets. Only used on older Juju versions where secrets are not supported. Must match metadata.yaml.

cert_subject

Custom subject. Name collisions are under the caller's responsibility.

sans

DNS names. If none are given, use FQDN.

refresh_events

an optional list of bound events which will be observed to replace the current CSR with a new one if there are changes in the CSR's DNS SANs or IP SANs. Then, subsequently, replace its corresponding certificate with a new one.

Description

CerHandler manages one single cert.

CertHandler. enabled( self )

Boolean indicating whether the charm has a tls_certificates relation.

Description

See also the available property.

CertHandler. available( self )

Description

Return True if all certs are available in relation data; False otherwise. None

CertHandler. relation( self )

Description

The "certificates" relation. None

CertHandler. private_key( self )

Private key.

Description

BEWARE: if the vault misbehaves, the backing secret is removed, the peer relation dies or whatever, we might be calling generate_private_key() again and cause a desync with the CSR because it's going to be signed with an outdated key we have no way of retrieving. The caller needs to ensure that if the vault backend gets reset, then so does the csr.

TODO: we could consider adding a way to verify if the csr was signed by our privkey, and do that on collect_unit_status as a consistency check

CertHandler. get_cert( self )

Description

Get the certificate from relation data. None

CertHandler. ca_cert( self )

Description

CA Certificate. None

CertHandler. server_cert( self )

Description

Server Certificate. None

CertHandler. chain( self )

Description

Return the ca chain bundled as a single PEM string. None