Certificate rotation overview
Learn about the options to automatically rotate certificates with Gloo Network.
Root CA
If you choose to use Gloo Network to create a self-signed certificate for the root CA, the root CA credentials are stored in the relay-root-tls-secret Kubernetes secret on the management cluster. Gloo Network does not monitor this secret for changes and does not automatically renew this certificate before it expires. You must set up internal processes to monitor the expiration of the root CA certificate and to renew this certificate before it expires. To automate this process, you can use tools such as cert-manager.
Intermediate CA
If you choose to use Gloo Network to create a self-signed certificate for the root CA that is used to create the intermediate CA certificate, the intermediate CA credentials are stored in the relay-tls-signing-secret Kubernetes secret on the management cluster. Gloo Network does not monitor this secret for changes and does not automatically renew this certificate before it expires. You must set up internal processes to monitor the expiration of the intermediate CA certificate and to renew this certificate before it expires. To automate this process, you can use tools such as cert-manager.
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. You must set up internal processes to monitor the expiration of the server TLS certificate and to renew this certificate before it expires. To automate this process, you can use tools such as cert-manager.
Client TLS certificate lifecycle management
If you choose to secure the relay connection between the Gloo management server and agent by using mutual TLS (mTLS), 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:
- Self-signed CAs with automatic client certificate rotation
- Bring your own 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:
glooAgent:
relay:
# 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.
clientTlsSecret:
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 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.
| 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 Network manages the client TLS certificate lifecycle for you. If you chose not to use the Gloo Network-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. |
Bring your own certificate lifecycle management tools
If you do not want or cannot use the Gloo Network-provided certificate lifecycle management feature, you are responsible to rotate the 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 Bring your own CAs and client TLS certificates.