Elasticsearch mTLS Client Authentication

TSB supports mutual TLS (mTLS) client certificate authentication when connecting to Elasticsearch or OpenSearch. When enabled, TSB presents a PEM-encoded client certificate to the Elasticsearch server during the TLS handshake, in addition to verifying the server's certificate.

The credentials are stored in the es-certs Kubernetes secret and mounted automatically into the components that connect to Elasticsearch:

• Management plane: OAP receives the certificate as a PKCS12 keystore, built from the PEM material by an init container at startup.
• Control plane: the Envoy front-proxy uses the PEM certificate and key directly as upstream tls_certificates.

Prerequisites

Before you begin, obtain from your Elasticsearch or OpenSearch administrator:

• A PEM-encoded client certificate
• The corresponding PEM-encoded private key
• The CA certificate used to sign the server's TLS certificate, if not already configured via secrets.elasticsearch.cacert

Configure using Helm

Management Plane

Add the client certificate and key to the secrets section of your Management Plane values.yaml file:

secrets:
  elasticsearch:
    cacert: |
      -----BEGIN CERTIFICATE-----
      <CA certificate content>
      -----END CERTIFICATE-----
    clientcert: |
      -----BEGIN CERTIFICATE-----
      <Client certificate content>
      -----END CERTIFICATE-----
    clientkey: |
      -----BEGIN RSA PRIVATE KEY-----
      <Private key content>
      -----END RSA PRIVATE KEY-----

Then apply the updated values with Helm:

helm upgrade mp tetrate-tsb-helm/managementplane \
  --version <tsb-version> \
  --namespace tsb \
  --values values.yaml \
  --set image.registry=<registry-location>

Control Plane

Add the same credentials to the secrets section of your Control Plane values.yaml file in each application cluster:

secrets:
  elasticsearch:
    cacert: |
      -----BEGIN CERTIFICATE-----
      <CA certificate content>
      -----END CERTIFICATE-----
    clientcert: |
      -----BEGIN CERTIFICATE-----
      <Client certificate content>
      -----END CERTIFICATE-----
    clientkey: |
      -----BEGIN RSA PRIVATE KEY-----
      <Private key content>
      -----END RSA PRIVATE KEY-----

Then apply the updated values with Helm:

helm upgrade cp tetrate-tsb-helm/controlplane \
  --version <tsb-version> \
  --namespace istio-system \
  --values values.yaml \
  --set image.registry=<registry-location>

Repeating credentials across clusters

Each control plane cluster requires its own Helm upgrade. If all clusters connect to the same Elasticsearch instance, the same certificate and key can be used in each cluster's values.yaml.

Configure using tctl

If you manage TSB manifests with tctl install manifest, the es-certs secret rendered for both the management plane and control plane can include the client certificate and key. Provide the PEM material in the relevant secret struct when generating your manifests, and tctl will include client.crt and client.key in the rendered es-certs secret.

Verify the configuration

After upgrading, confirm that the es-certs secret has been created and that the OAP pods have restarted successfully:

# Management plane
kubectl -n tsb get secret es-certs
kubectl -n tsb rollout status deployment oap

# Control plane
kubectl -n istio-system get secret es-certs
kubectl -n istio-system rollout status deployment oap-deployment

If the management plane OAP pod fails to start, check the init container logs for errors converting the PEM material to a keystore:

kubectl -n tsb logs deployment/oap -c pem-to-keystore

If the control plane Envoy fails to connect, check its logs for TLS handshake errors:

kubectl -n istio-system logs deployment/oap-deployment -c envoy --tail=50

Keep credentials in sync

Ensure the client certificate is signed by a CA that Elasticsearch is configured to trust. A mismatch will cause connection failures in OAP (management and control plane) and in the control plane Envoy front-proxy.