How to Prepare Certificates and DNS Before Installing

This guide shows you how to turn the DNS and Certificate Inventory Reference into registered DNS names and Kubernetes Secrets, so every certificate the first Axual chart needs already exists before you install it.

Type

How-to guide

Goal

Have every DNS name registered and every certificate Secret created, ready for How to Configure Certificates on an Axual Component to point components at.

Audience

Infrastructure engineers who can register DNS names and request certificates, and Platform Operators who can create Secrets in the target namespace.

When to use

Stage 1 of The installation order, after Infrastructure Requirements is agreed and before Preparations.

This guide stops once the Secrets exist. It does not point any component at them, that is How to Configure Certificates on an Axual Component, the next step in the installation order.

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 register records with the organisation’s DNS provider, or a named contact who can do it for you.

  • Permission to request certificates from the organisation’s certificate authority (Enterprise PKI), or a named contact who can do it for you.

  • Permission to create Secrets in the namespace each component will run in.

Tools and versions required

You need the following tools:

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

  • base64, for the manual issuance path only. The command below uses the GNU -w 0 flag to keep the output on one line, which a Secret value requires; on macOS use -b 0 instead.

  • cert-manager, for the automated issuance path only.

Resources that must exist before starting

The following must already exist:

  • The load balancer or ingress addresses each exposed component resolves to, from Install an Ingress Controller and the cluster’s own load balancer setup.

  • The target namespace, or namespaces, the Secrets below will be created in.

Register the DNS names

Work through the DNS names table row by row. Each row names a component, the address it resolves to, either a custom load balancer IP or the ingress load balancer IP, and how it is exposed. Point every name at the matching address with your DNS provider.

A certificate is issued for the hostname a client resolves. Register the name before requesting its certificate, or the Subject Alternative Name (SAN) on the certificate has nothing to match once the name exists.

Decide cert-manager or manual issuance

Certificates expire on a recurring schedule, so issuing and renewing them by hand does not scale past a handful of components. Why certificate issuance is automated covers the trade-off; cert-manager covers what the platform expects of it.

The platform reads Kubernetes Secrets either way, so this decision changes how the Secrets in the next two steps get created, not their shape.

Request the certificate authorities and component certificates

Request the two authorities and the certificates listed in Certificate authorities and Certificates to request:

  • The Enterprise PKI root certificate, and a server certificate from it for every externally reachable component, with the DNS names registered above as its Subject Alternative Names.

  • The internal PKIESP root certificate, and a server certificate from it for every internal component. cert-manager can issue and manage this authority itself, which is the usual setup.

Under cert-manager, this step is creating the Issuer or ClusterIssuer and the per-component Certificate resources, rather than requesting files by hand.

Create the Secrets

Land each certificate as a Kubernetes Secret in the shape TLS Secret Formats Reference defines. cert-manager writes these shapes on its own once its Certificate resources are created; the commands below are for the manual path.

Replace every <VALUE> placeholder with your own value before running a command.

A server or client keypair, as a Secret of type kubernetes.io/tls:

kubectl create secret tls <KEYPAIR_SECRET_NAME> \
  --cert=<CERTIFICATE_FILE>.pem \
  --key=<PRIVATE_KEY_FILE>.pem \
  --namespace <NAMESPACE>

A truststore, as an Opaque Secret with one .crt entry per authority in the chain:

kubectl create secret generic <TRUSTSTORE_SECRET_NAME> \
  --from-file=enterprise_root_ca.crt=<ENTERPRISE_CA_FILE>.pem \
  --from-file=pkiesp_root_ca.crt=<PKIESP_CA_FILE>.pem \
  --namespace <NAMESPACE>

Repeat both for every component in the inventory. Name the Secrets so their purpose and component are clear, the names are your own choice, configure-component-certificates.adoc references them by name rather than expecting a fixed one.

Verify every Secret is ready

List the Secrets in the namespace and confirm one exists for every component in the inventory.

kubectl get secrets --namespace <NAMESPACE>

Read back a certificate to confirm it is the one you meant, and that its Subject Alternative Names match the DNS names registered above.

kubectl get secret <KEYPAIR_SECRET_NAME> --namespace <NAMESPACE> \
  -o 'jsonpath={.data.tls\.crt}' | base64 -d \
  | openssl x509 -subject -issuer -dates -noout

How to Inspect a Certificate covers the other ways to read a certificate back. Once every Secret checks out, continue with How to Configure Certificates on an Axual Component to point each component at its Secrets.