Certificate rotation overview

Learn how the client TLS certificate for the Gloo agent is rotated, and the options that are available to you to customize this process.

Client TLS certificate lifecycle management with Gloo Gateway

You can use Gloo Gateway to automatically manage the lifecycle of the client TLS certificate that the Gloo agent uses to authenticate with the Gloo management server. To enable Gloo Gateway to automatically issue and rotate client TLS certificates for the Gloo agent, an intermediate CA certificate and key must exist in the relay-tls-signing-secret Kubernetes secret so that the Gloo management server can act as a certificate authority for any Gloo agents that are registered. You can choose between the following options to provide this secret to Gloo Gateway:

Client TLS certificates that are automatically generated by Gloo Gateway, have a default expiration period (TTL) of 1 year.

Gloo Gateway can be used to manage the client TLS certificate for you. However, other certificates that are used in the relay architecture, such as the server TLS certificate or the root and intermediate CA certificates that are used to sign client TLS certificates are not automatically rotated. Depending on the setup option that you choose, make sure that you are aware of the certificates that you must manually monitor and rotate.

Client TLS certificate expiration settings

Client TLS certificates that are automatically generated by Gloo Gateway, have a default expiration period (TTL) of 1 year. Customizing the default expiration period for generated client TLS certificates is currently not supported. However, you can set the grace period (clientTlsSecretRotationGracePeriodRatio) that determines when Gloo Gateway starts to rotate the client TLS certificate before they expire. For example, if you set the clientTlsSecretRotationGracePeriodRatio to 0.1, then Gloo Gateway starts to rotate the certificate 36.5 days before they expire (365 days x 0.1).

You can set the grace period during your Gloo agent installation by using the following Helm values:

        # Custom certs: Secret containing client TLS certs used to identify the Gloo agent to the management server. If you do not specify a clientTlssSecret, you must specify a tokenSecret and a rootTlsSecret.
            name: relay-client-tls-secret
        # The ratio of the client TLS certificate lifetime to when the management server starts the certificate rotation process.
        clientTlsSecretRotationGracePeriodRatio: ""

Client TLS certificate rotation process

To understand how Gloo Gateway monitors the lifecycle of a client TLS certificate, let's take a look at the components that run inside the Gloo agent that are responsible for monitoring and rotating the certificate.

Gloo agent components to manage the client TLS certificate lifecycle

If you have multiple Gloo agent replicas in the same deployment, Gloo Gateway elects one agent pod as the leader.

Component Description
grpc client The gRPC client is used to connect with the Gloo management server.
provider The provider component holds the most current TLS certificate. The agent uses this certificate to connect to the Gloo management server via a TLS handshake. Note the following considerations about expiring TLS certificates. Even if the TLS certificate expires, the TLS connection is still considered valid. This is because the connection uses a valid session key. If the connection closes, the agent reconnects by getting the current TLS certificate from the provider. If the current TLS certificate is still expired, the connection cannot be established.
watcher The watcher component monitors the relay-tls-client-secret Kubernetes secret for changes. If a new certificate is detected, the watcher writes this information to the provider component. Note that the secret is automatically updated in the case that Gloo Gateway manages the client TLS certificate lifecycle for you. If you chose not to use the Gloo Gateway-managed certificate lifecycle, you must manually update this secret.
rotator The rotator component is responsible to monitor the expiration date of the client TLS certificate. If the certificate is about to expire, the rotator sends a certificate signing request to the Gloo management server so that a new client TLS certificate can be issued. The new certificate is stored in the relay-tls-client-secret Kubernetes secret. To avoid sending multiple certificate signing requests to the Gloo management server, the rotator component is started only on the Gloo agent pod that was elected leader. Note that the component is not started if you bring your own certificate lifecycle management process.

Automatic reloading of server TLS credentials

Gloo Gateway monitors the relay-server-tls-secret Kubernetes secret for changes and automatically reloads the credentials in the Gloo management server in case the secret was updated. Note that the server TLS certificate is not automatically rotated by Gloo Gateway and must be manually rotated before it expires.

Bring your own certificate lifecycle management tools

If you do not want or cannot use the Gloo Gateway-provided certificate lifecycle management feature, you are responsible to rotate client TLS certificates yourself. You can manually rotate the certificates or use tools, such as cert-manager, to manage the rotation for you.

For more information, see: