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:

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

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.
      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.

Figure: Gloo agent components to manage the client TLS certificate lifecycle

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

grpc clientThe gRPC client is used to connect with the Gloo management server.
providerThe 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.
watcherThe 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.
rotatorThe 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: