Relay certificate overview

A Gloo Mesh setup consists of one management cluster that the Gloo management components are installed in, and one or more workload clusters that run service meshes which are registered with and managed by the management cluster. The management cluster serves as the management plane, and the workload clusters serve as the data plane. For more information, see the Relay architecture concept.

To secure the communication between the management server and agents, server and client TLS certificates are used. By default, Gloo Mesh Enterprise autogenerates and signs its own root and intermediate CA certificate and key, and stores these credentials in the management cluster. The intermediate CA private key is then used to issue and sign client TLS certificates for Gloo agents in each workload cluster.

For an overview of certificate management architectures, see Setup options.

Gloo Mesh-managed client TLS certificate lifecycle

You can choose to use Gloo Mesh self-signed certificates for the root CA and use these credentials to derive the intermediate CA certificate and key. The intermediate CA credentials are then used to automatically sign and issue client TLS certificates for the Gloo agent in each workload cluster that registers with the management server.

With this approach, Gloo Mesh monitors the expiration of the client TLS certificates and automatically renews them when they expire. Other certificates, such as the server TLS certificate that the management server uses, or the root and intermediate CA certificates are not automatically rotated with this setup. For more information, see the Certificate rotation overview.

To use Gloo Mesh to manage the client TLS certificate for you, you can choose between the following setup options:

For instructions on how to set up these certificate management architectures, see Gloo Mesh-managed client TLS certificates.

Manage the client TLS certificate yourself

Instead of managing the client TLS certificate lifecycle with Gloo Mesh, you can choose to bring your own certificate management tools and PKI provider to have full control over the certificate lifecycle. For example, you can use your preferred PKI provider to generate and store the root and intermediate CA credentials outside your cluster. Then, you use a tool like cert-manager to manage the lifecycle of the client TLS and other certificates for you. Cert-manager monitors the expiration of your certificate and renews them by connecting to your PKI provider. To learn more about this setup, see Option 4: Manually provide the client TLS certificates.

Refer to the following guides to learn how to use cert-manager with an external PKI provider:

Initial proof of trust

When a workload cluster is registered with the management server for the first time, the agent must establish an initial trust with the Gloo management server to allow the connection. Depending on the setup that you choose, a client TLS certificate might not be present on the workload cluster by the time the agent tries to connect to the management server for the first time. To prove the agent's identity to the management server, Gloo Mesh supports identity tokens and direct provisioning of client TLS certificates.

Identity tokens

You can use Gloo Mesh identity tokens to establish inital trust between the agents and the management server. Identity tokens are automatically generated when you install the Gloo management plane and decide to use Gloo Mesh self-signed certificates for the root CA. However, you can also use this option when you use custom CAs with automatic client TLS certificate rotation.

If you decide to bring your own client and server TLS certificates and to manage the certificate rotation yourself, you cannot use identity tokens to establish initial trust. Instead, you must directly provide the client TLS certificates so that the initial connection between the management server and agent already uses the TLS certificates.

The following diagram and steps illustrate how identity tokens are used to establish initial trust.

Identity tokens to establish initial trust between the Gloo agent and management server
  1. You install the Gloo management plane in the management cluster. If you decide to use Gloo Mesh self-signed certificates for the root CA, an identity token is created for you and stored in the relay-identity-token-secret Kubernetes secret. If you decide to bring your own CA certificates, you can generate an identity token yourself and store it in the relay-identity-token-secret Kubernetes secret. The identity token can be any string value.
  2. Before you register a workload cluster with the management server, the relay-identity-token-secret Kubernetes secret must exist on the workload cluster. This secret must contain the exact same value that was used in the relay-identity-token-secret Kubernetes secret on the management cluster.
  3. During the workload registration, the agent looks up the identity token from the secret and sends this token to the management server to prove its identity.
  4. The management server verifies that the token that was sent by the agent matches the identity token that was stored in the relay-identity-token-secret on the management cluster.
  5. If the token matches, the management server uses the credentials in the relay-tls-signing-secret to sign and issue a client TLS certificate.
  6. The client TLS certificate is returned to the Gloo agent.
  7. The agent stores the certificate in the relay-client-tls-secret Kubernetes secret on the workload cluster.
  8. In subsequent communication with the management server, the agent uses the client TLS certificate to prove its identity to the management server and to establish a secure mutual TLS connection.

Directly provide the client TLS certificates

If you do not or cannot use identity tokens to establish initial trust between the Gloo agent and the management server, the client TLS certificate must be present on the workload cluster before the agent tries to connect to the management server for the first time. You must use this option if you choose to bring your own client and server TLS certificates and to manage the certificate rotation yourself.

Review the following image to understand how to directly provide the client TLS certificate to the workload cluster.

Directly provide the client TLS certificate to the workload cluster to establish initial trust between the Gloo agent and management server
  1. You use your PKI provider or certificate management tools to generate the client TLS certificate. The certificate must be derived from the same root CA that was used to issue the server TLS certificate that the Gloo management server uses. The certificate is stored in the relay-client-tls-secret Kubernetes secret on the workload cluster. Note that the secret must exist on the workload cluster before it is registered with the management server.
  2. During the workload registration, the agent uses the client TLS certificate from the relay-client-tls-secret Kubernetes secret to authenticate with the management server and prove its identity.