SSL & Security Checks

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/ssl-expiry-check/main.go
• cmd/ssl-handshake-check/main.go
• cmd/ssl-expiry-check/README.md
• cmd/ssl-handshake-check/README.md
• cmd/ssl-handshake-check/ssl-file-handshake-check.yaml
• README.md

Kuberhealthy provides a suite of SSL and security-oriented synthetic checks designed to ensure the integrity and availability of encrypted communication within and outside the Kubernetes cluster. These checks function by replicating real-world client behavior, such as performing TLS handshakes or verifying certificate validity periods, to identify issues that traditional monitoring might miss.

The primary focus of these modules is to prevent service outages caused by expired certificates and to verify that infrastructure components (like Load Balancers or Ingresses) are correctly configured for secure communication. The results of these checks are reported back to the Kuberhealthy operator and made available via a JSON status page or Prometheus metrics endpoint. Sources: README.md, cmd/ssl-expiry-check/README.md

SSL Expiry Check

The SSL Expiry Check verifies that certificates for a given domain and port are not currently expired and will not expire within a specified threshold of days. Sources: cmd/ssl-expiry-check/README.md:3-5

Logic and Architecture

The check operates as a standalone pod within the cluster. It retrieves configuration from environment variables, waits for the node to be ready via nodeCheck.WaitForKuberhealthy, and then executes the expiration logic. It supports both CA-issued certificates and self-signed certificates. For self-signed certificates, the INSECURE flag can be set to true, which bypasses the full TLS handshake and only inspects the certificate's expiration metadata. Sources: cmd/ssl-expiry-check/main.go:34-70, cmd/ssl-expiry-check/README.md:46-52

The diagram shows the lifecycle of the SSL Expiry checker, from initialization to the reporting of results. Sources: cmd/ssl-expiry-check/main.go:101-135

Configuration Variables

Variable	Description	Default
DOMAIN_NAME	The domain to check	Required
PORT	The port the SSL service is listening on	443
DAYS	Threshold days before expiration to trigger a warning	60
INSECURE	Set to "true" to skip TLS handshake (for self-signed)	"false"

Sources: cmd/ssl-expiry-check/main.go:47-68, cmd/ssl-expiry-check/README.md:18-35

SSL Handshake Check

The SSL Handshake Check ensures that a complete TLS handshake can be successfully established with a specified endpoint. This verifies not only expiration but also certificate chain validity and server configuration. Sources: cmd/ssl-handshake-check/README.md:3-4

Architecture and Execution

This check creates a custom certificate pool for every run. If configured for self-signed certificates (SELF_SIGNED="true"), it can either attempt to automatically retrieve the host certificate or use a certificate provided via a mounted volume from a ConfigMap. Sources: cmd/ssl-handshake-check/main.go:121-131, cmd/ssl-handshake-check/README.md:46-52

The sequence diagram illustrates the interaction between the checker, the target server, and the Kuberhealthy reporting API. Sources: cmd/ssl-handshake-check/main.go:88-117

Implementation Details

• Cert Pool Creation: Uses ssl_util.CreatePool() to initialize a fresh pool for validation. Sources: cmd/ssl-handshake-check/main.go:126-128
• Handshake Method: Executes ssl_util.SSLHandshakeWithCertPool to perform the actual connection attempt. Sources: cmd/ssl-handshake-check/main.go:131
• Timeout Management: Utilizes a context-aware deadline retrieved from the Kuberhealthy operator to ensure the check terminates gracefully. Sources: cmd/ssl-handshake-check/main.go:42-50

Handshake Check Configuration

Variable	Description	Default
DOMAIN_NAME	Target domain for the handshake	Required
PORT	Target port (usually 443)	443
SELF_SIGNED	Set to "true" to allow self-signed certs	"false"

Sources: cmd/ssl-handshake-check/main.go:52-68, cmd/ssl-handshake-check/README.md:25-36

Security and Self-Signed Certificates

Kuberhealthy allows for advanced verification of internal or self-signed certificates through two primary methods:

1. Insecure Expiry Verification: By setting INSECURE: "true" in the expiry check, the system bypasses validity checks to only monitor the NotAfter date. Sources: cmd/ssl-expiry-check/README.md:11-12
2. ConfigMap Mounted Certificates: Users can provide their own .pem formatted certificates via a ConfigMap, which the ssl-handshake-check mounts at /etc/ssl/selfsign to validate the handshake against a known private CA. Sources: cmd/ssl-handshake-check/README.md:59-62, cmd/ssl-handshake-check/ssl-file-handshake-check.yaml:23-25

# Snippet from ssl-file-handshake-check.yaml
volumeMounts:
  - name: certificate-vol
    mountPath: /etc/ssl/selfsign
volumes:
  - name: certificate-vol
    configMap:
      name: certificate-config

Sources: cmd/ssl-handshake-check/ssl-file-handshake-check.yaml:22-31

Conclusion

SSL & Security checks in Kuberhealthy are essential for maintaining the operational security of a cluster. By implementing both Expiry and Handshake checks, administrators can ensure that certificates are not only valid in terms of time but are also functionally correct and trusted by the system components. Sources: README.md, cmd/ssl-expiry-check/README.md