Internal Certificates Requirements

Before you continue, make sure you:
✓ Understand the 4 types of certificates in TSB particularly internal certificates and the two methods of XCP authentication: mTLS and JWT with TLS.

note

Please note that the certificates described here are solely used for the communication between TSB components, and thus are not part of your workloads' certificates that are typically managed by Istio or application TLS certificates.

warning

In case you have installed cert-manager in the management plane cluster, you can use tctl to automatically install required issuer and certificate in the management plane and create control plane certificate. Please see the documentations for Management Plane Installation and Onboarding Clusters for more details.

mTLS Authentication

All certificates involved in mTLS communication between management plane and control plane should be created from the same chain of trust, i.e. have the same CA. For the CA, we recommend plugging into your existing PKI infrastructure.

Management Plane

XCP central

XCP central in the management plane uses the certificate stored in a secret named xcp-central-cert in the management plane namespace (which defaults to tsb). The secret must contain data for the standard tls.crt, tls.key, and ca.crt fields.

The certificate must have the following URI SAN spiffe://xcp.tetrate.io/central

Below is an example of XCP central certificate as cert-manager resource. Note that following assumes the existence of cert-manager identity issuer named xcp-identity-issuer.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: xcp-central-cert
  namespace: tsb
spec:
  secretName: xcp-central-cert
  issuerRef:
    name: xcp-identity-issuer
    kind: Issuer
  duration: 30000h
  uris:
  - spiffe://xcp.tetrate.io/central

MPC

If you are upgrading to TSB 1.2.4 or 1.4.0, the MPC component needs a certificate to authenticate with XCP Central using mTLS.

MPC component in the management plane uses the certificate stored in a secret named mpc-certs in the management plane namespace (which defaults to tsb). The secret must contain data for the standard tls.crt, tls.key, and ca.crt fields.

The certificate must have following URI SAN spiffe://xcp.tetrate.io/mpc

Below is an example of MPC certificate as cert-manager resource.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: mpc-certs
  namespace: tsb
spec:
  secretName: mpc-certs
  issuerRef:
    name: xcp-identity-issuer
    kind: Issuer
  duration: 30000h
  uris:
  - spiffe://xcp.tetrate.io/mpc

Control Plane

XCP edge in the control plane uses the certificate stored in a secret named xcp-edge-cert in the control plane namespace (default to istio-system). The secret must contain data for the standard tls.crt, tls.key, and ca.crt fields.

The certificate must have following URI SAN spiffe://xcp.tetrate.io/<cluster-name-in-tsb>

Below is an example of XCP edge certificate as cert-manager resource.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: xcp-edge-cert
  namespace: istio-system
spec:
  secretName: xcp-edge-cert
  issuerRef:
    name: xcp-identity-issuer
    kind: Issuer
  duration: 30000h
  uris:
  - spiffe://xcp.tetrate.io/<cluster-name-in-tsb>

JWT authentication

When using JWT authentication with regular (non-mutual) TLS, the XCP central certificate must include its address in its subject alternate names (SANs). This will either be a DNS name or an IP address.

Similar with mTLS above, XCP central in the management plane uses the certificate stored in a secret named xcp-central-cert in the management plane namespace (which defaults to tsb). The secret must contain data for the standard tls.crt, tls.key, and ca.crt fields.

Below is an example of XCP central certificate as cert-manager resource if you are using IP address.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: xcp-central-cert
  namespace: tsb
spec:
  secretName: xcp-central-cert
  ipAddresses:
  - a.b.c.d  ## <--- IP Address here
  issuerRef:
    name: xcp-identity-issuer
    kind: Issuer
  duration: 30000h

Or, if you are using domain names, edit the field spec.dnsNames

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: xcp-central-cert
  namespace: tsb
spec:
  secretName: xcp-central-cert
  dnsNames:
  - example-tsb.tetrate.io ## <-- DNS name here
  issuerRef:
    name: xcp-identity-issuer
    kind: Issuer
  duration: 30000h

DNS name when creating certificate with tctl

If you use tctl to automatically install required issuer and certificate, XCP central cert will have central.xcp.tetrate.io as the DNS name.

Migrating from mTLS to JWT

If you are already using mTLS and want to migrate to JWT, follow steps described in here