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 Network
You can use Gloo Network 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 Network 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 Network:
- Setup Option 2: Gloo Network self-signed CAs with automatic client certificate rotation
- Setup Option 3: Custom CAs with automatic client TLS certificate rotation
Client TLS certificates that are automatically generated by Gloo Network have a default expiration period (TTL) of 1 year.
Gloo Network 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 Network, 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 Network starts to rotate the client TLS certificate before they expire. For example, if you set the
clientTlsSecretRotationGracePeriodRatio to 0.1, then Gloo Network 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.
# The ratio of the client TLS certificate lifetime to when the management server starts the certificate rotation process.
Client TLS certificate rotation process
To understand how Gloo Network 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.
If you have multiple Gloo agent replicas in the same deployment, Gloo Network elects one agent pod as the leader.
|The gRPC client is used to connect with the Gloo management server.
|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.
|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 Network manages the client TLS certificate lifecycle for you. If you chose not to use the Gloo-managed certificate lifecycle, you must manually update this secret.
|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 Network 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 Network 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-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: