How to Configure Certificates on an Axual Component

This guide shows you how to point an Axual component at the Kubernetes Secrets holding its certificates, how to give inbound and outbound connections separate truststores, and how to confirm which certificate a Secret carries.

Type

How-to guide

Goal

Configure a component so it can both serve and initiate mutual TLS (mTLS) connections.

Audience

Platform Operator who can read Secrets in the target namespace and edit the component’s values.yaml.

When to use

Use this guide when adding TLS to a component for the first time, or when moving one to different certificates.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Permission to read Secrets in the namespace the component runs in.

  • Permission to edit and apply the component’s values.yaml, whether through Helm directly or through your GitOps repository.

Tools and versions required

You need the following tools:

  • kubectl >= 1.28, with access to the target namespace.

  • openssl, for the verification step only.

  • helm >= 3.12, if you apply values with Helm rather than through a deployment pipeline.

Resources that must exist before starting

The following must already exist:

  • A keypair Secret for the component, and a truststore Secret holding the certificate authorities it must trust. TLS Secret Formats Reference gives the exact shape each one must have.

  • cert-manager, if you want those Secrets issued and renewed for you rather than created by hand.

Pair cert-manager with Reloader. cert-manager renews the certificate in the Secret, and Reloader restarts the pod so the component picks it up.

Confirm the Secrets exist

List the Secrets in the namespace and confirm the ones you intend to reference are present.

Replace every <VALUE> placeholder with your own value before running a command. 
kubectl get secret --namespace <NAMESPACE>

The component fails at startup if tls.enabled is true and a referenced Secret is absent, so confirm the names now rather than after the deploy.

Point the component at its Secrets

Add the tls block to the component’s section of values.yaml, naming the Secrets rather than embedding certificate data.

<component>:
  tls:
    enabled: true                                      (1)
    serverKeypairSecretName: <SERVER_KEYPAIR_SECRET>   (2)
    clientKeypairSecretName: <CLIENT_KEYPAIR_SECRET>   (3)
    truststoreCaSecretName: <TRUSTSTORE_SECRET>        (4)
1 Required. Nothing below it is read while this is false.
2 The keypair the component presents on its own endpoint. For an HTTPS endpoint, its CN must match the fully qualified domain name callers use.
3 The keypair the component presents when connecting out. May be the same Secret as the server keypair.
4 The certificate authorities the component trusts, in both directions.

Apply the values the way this component is normally deployed, with helm upgrade --install or by committing to the repository your deployment tool watches.

For the full set of keys, including the ones individual charts add, see The tls values block.

Separate the client and server truststores

Skip this section when the component trusts the same authorities in both directions, which is the usual case for internal components.

Set the two keys below when inbound and outbound connections are anchored to different certificate authorities. Each takes precedence over truststoreCaSecretName for its own direction.

<component>:
  tls:
    clientTruststoreCaSecretName: <OUTBOUND_TRUSTSTORE_SECRET>   (1)
    serverTruststoreCaSecretName: <INBOUND_TRUSTSTORE_SECRET>    (2)
1 Used when the component validates the remote end of a connection it opens.
2 Used when the component validates a client certificate presented to it.

For what each store is responsible for, see The four stores.

Verify the certificate a Secret carries

Kubernetes does not decode certificate data, so read the entry out of the Secret and inspect it with openssl. This confirms you referenced the certificate you meant, and shows when it expires.

kubectl get secret <TLS_SECRET_NAME> --namespace <NAMESPACE> \
  -o 'jsonpath={.data.ca\.crt}' | base64 -d \
  | openssl x509 -subject -issuer -startdate -enddate -noout

Expected output is four lines giving the subject, the issuer, and the validity window:

subject=CN = internal-server-only
issuer=CN = PKIESP
notBefore=...
notAfter=...

Change ca\.crt to tls\.crt to inspect the component’s own certificate instead of the authority that signed it.

Once the component restarts, confirm it came up and that its logs show no TLS handshake failures. If it does not start, Troubleshooting covers reading pod events and logs.