How to manage TLS encryption

This guide shows how to enable TLS encryption, update private keys, and rotate TLS/CA certificates for a Charmed OpenSearch deployment.

For a step-by-step introduction, see the Tutorial.

Note

TLS is mandatory for Charmed OpenSearch and cannot be disabled.

Enable TLS encryption

The example below uses the self-signed-certificates operator.

Caution

Self-signed certificates are not recommended for production.

See the X.509 certificates topic for an overview of available certificate charms.

Deploy the TLS charm:

juju deploy self-signed-certificates --config ca-common-name="My CA"

Integrate it with OpenSearch:

juju integrate self-signed-certificates opensearch

Verify the relation with juju status --relations. The OpenSearch application turns active — it is no longer blocked with a “Missing TLS relation” message.

Check certificates in use

To inspect the issuer of the certificate currently served by OpenSearch:

openssl s_client -showcerts -connect <unit-ip>:<port> < /dev/null | grep issuer

Update private keys

Private keys can be updated via the set-tls-private-key action. Charmed OpenSearch uses three certificate categories:

  • app-admin — administrative actions (leader unit only)

  • unit-transport — internal node-to-node communication

  • unit-http — external client-to-node communication

Note

Each unit has its own node certificate, so unit-transport and unit-http keys must be set on every target unit individually (e.g. juju run opensearch/<unit-id> ...).

For an explanation of why these three categories exist and how rotation works, see TLS certificates.

Auto-generate new keys

Generate the app-admin key on the leader:

juju run opensearch/leader set-tls-private-key category=app-admin

Then generate the unit-transport and unit-http keys on each unit, replacing <unit-id> (for example, opensearch/0, opensearch/1):

juju run opensearch/<unit-id> set-tls-private-key category=unit-transport
juju run opensearch/<unit-id> set-tls-private-key category=unit-http

Use custom keys

Generate keys with OpenSSL:

openssl genrsa -out unit-http.pem 3072
openssl genrsa -out unit-transport.pem 3072
openssl genrsa -out app-admin.pem 3072

Apply the app-admin key on the leader:

juju run opensearch/leader set-tls-private-key category=app-admin key="$(base64 -w0 app-admin.pem)"

Then apply the unit-transport and unit-http keys on each unit, replacing <unit-id> (for example, opensearch/0, opensearch/1):

juju run opensearch/<unit-id> set-tls-private-key category=unit-transport key="$(base64 -w0 unit-transport.pem)"
juju run opensearch/<unit-id> set-tls-private-key category=unit-http key="$(base64 -w0 unit-http.pem)"

Rotate TLS certificates

Certificate rotation is triggered automatically when a certificate expires. To rotate manually, regenerate the private key for the desired category:

juju run opensearch/<unit-id> set-tls-private-key category=<category>

Where <category> is app-admin, unit-transport, or unit-http. Use opensearch/leader for app-admin; use opensearch/<unit-id> for unit-transport and unit-http, repeating for each unit.

This generates a new private key and CSR, which is sent to the certificate provider for signing. Once signed, the new certificate is automatically applied to the cluster.

Rotate CA certificates

The CA certificate is provided by the TLS operator you are using. The rotation process differs depending on the operator.

With self-signed-certificates

Trigger CA rotation by changing the common name:

juju config self-signed-certificates ca-common-name=<new-ca-common-name>

This will:

  1. Generate a new CA certificate with the new common name.

  2. Revoke all previously issued TLS certificates.

  3. Cause OpenSearch to automatically request new certificates.

  4. Trigger a rolling restart to apply the new CA across all nodes.

Until the rolling restart completes, nodes continue using the old certificates.

Verify the new CA is in use:

openssl s_client -showcerts -connect <unit-ip>:<port> < /dev/null | grep issuer

With manual-tls-certificates

To rotate the CA with the manual-tls operator, sign CSRs with the new CA certificate and provide them to the cluster. If you no longer have the original CSR files, regenerate them first.

Provide the new certificate to each unit, starting with the leader:

juju run manual-tls-certificates/leader provide-certificate \
  relation-id=<relation-id> \
  certificate="$(base64 -w0 certificate.pem)" \
  ca-chain="$(base64 -w0 ca_chain.pem)" \
  ca-certificate="$(base64 -w0 ca_certificate.pem)" \
  certificate-signing-request="$(base64 -w0 csr.pem)" \
  unit-name="<unit-name>"

Caution

Always distribute certificates to the leader unit first, then to the remaining nodes.

After receiving the new CA, each node generates new CSRs that must be signed with the new CA and provided back. Repeat for every unit in the cluster.

Once all units have the new CA, OpenSearch reloads certificates (or triggers a rolling restart if the issuer, subject, or SANs have changed).

Verify the rotation:

openssl s_client -showcerts -connect <unit-ip>:<port> < /dev/null | grep issuer

Next steps