TLS Secret Formats Reference

This reference describes the three Kubernetes Secret shapes the Axual charts read, the key length, cipher and private key formats the platform accepts, and the tls values block that points a component at its Secrets. For the procedure that sets those values, see How to Configure Certificates on an Axual Component.

Type

Reference

Goal

Look up the exact shape a TLS Secret must have, or the exact name of a tls value.

Audience

Anyone who can create Secrets in the namespace the platform runs in, or edit a component’s values.yaml.

When to use

When writing a Secret manifest, configuring cert-manager to produce one, or setting the tls block on a component.

Contents

The sections below cover each area in this reference:

Secret formats

The Axual charts do not read certificate files directly. They read Kubernetes Secrets, and the Axual Keystore Provider init container builds the keystore and truststore files from them at pod startup. The three shapes below are the formats it accepts.

Secrets of type kubernetes.io/tls

Kubernetes stores TLS data in a standard Secret format under the type kubernetes.io/tls. cert-manager produces Secrets in this shape.

apiVersion: v1
kind: Secret
metadata:
  name: example-secret
type: kubernetes.io/tls
data:
  ca.crt:  ... (1)
  tls.crt: ... (2)
  tls.key: ... (3)
1 Base64 encoded root CA certificate string
2 Base64 encoded certificate string
3 Base64 encoded private key string

Certificate Secrets with two entries

Axual Platform components rarely use the ca.crt entry, so a client or server certificate Secret can carry two data entries instead of three.

apiVersion: v1
kind: Secret
metadata:
  name: example-secret
type: Opaque
data:
  tls.crt: ... (1)
  tls.key: ... (2)
1 Base64 encoded certificate string
2 Base64 encoded private key string

Truststore (CA) Secrets

A truststore Secret carries any number of key and value pairs. Each value is appended to the truststore that gets mounted onto the service using it, so one Secret can hold a whole chain.

Every CA certificate entry must use a .crt extension. An entry with any other extension is not added to the truststore. 
apiVersion: v1
kind: Secret
metadata:
  name: example-ca-certificates
type: Opaque
data:
  axual_root_ca.crt: ...
  axual_intermediate_1_ca.crt: ...
  axual_intermediate_2_ca.crt: ...

All abbreviated values above are Base64 encoded strings.

Certificate and key requirements

These constraints apply to every certificate the platform uses, whichever Secret shape carries it.

Item Requirement

Server certificate key length

4096 bits.

Other certificate key lengths

At least 2048 bits.

Certificate format

X.509 in PEM format. The file extension is not constrained, so .crt, .pem and others are all accepted, except in a truststore Secret where .crt is required.

Private key format

Axual Governance accepts PKCS8 in PEM format only, whose first line is -----BEGIN PRIVATE KEY-----. A key beginning -----BEGIN RSA PRIVATE KEY----- or -----BEGIN ENCRYPTED PRIVATE KEY----- is not accepted.

The cipher suites below are the ones Axual considers secure. Axual components negotiate TLSv1.2.

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

The tls values block

Every component chart that terminates or initiates TLS exposes the same tls block. The keys below are the block’s full set.

Key Type Default Description

tls.enabled

boolean

false

Required. Whether the chart configures TLS for the component at all. The remaining keys are read only when this is true.

tls.serverKeypairSecretName

string

""

Required when enabled is true. Name of an existing Secret of type kubernetes.io/tls holding the keypair the component presents on its own endpoint.

tls.clientKeypairSecretName

string

""

Optional. Name of an existing Secret of type kubernetes.io/tls holding the keypair the component presents when connecting to other components. May be the same Secret as serverKeypairSecretName.

tls.truststoreCaSecretName

string

""

Optional. Name of an existing Opaque Secret holding the CA certificates the component trusts, in the shape described in Truststore (CA) Secrets. Used for both directions unless one of the two keys below overrides it.

tls.clientTruststoreCaSecretName

string

""

Optional. Truststore Secret used only for outbound connections. Takes precedence over truststoreCaSecretName.

tls.serverTruststoreCaSecretName

string

""

Optional. Truststore Secret used only for validating inbound client certificates. Takes precedence over truststoreCaSecretName.
Individual component charts may expose additional TLS keys, and some generate a Secret from inline PEM data rather than referencing an existing one. Those keys are listed in that component’s own chart values reference under Component Details.