Kubernetes

A Kubernetes agent enables monitoring and management of your Kubernetes clusters. It acts as a bridge between ClusterControl and your Kubernetes environment, allowing you to monitor and perform operations directly from the ClusterControl interface.

Kubernetes Proxy Server Certificates

Kubernetes Proxy requires a Certificate Authority (CA) certificate, a CA private key, a server certificate, and a server private key to enable TLS for its gRPC services.

Automatic Certificate Generation (Default Behavior)

On startup, if Kubernetes Proxy does not find existing certificates at its configured paths (see Using Your Own Existing Certificates, it will automatically:

Generate a new Root Certificate Authority (CA): ca.crt (CA certificate) and ca.key (CA private key).
Generate a new server certificate (server.crt) and server private key (server.key). This server certificate will be signed by the auto-generated CA.

These files are typically created in a default directory such as /usr/share/kuber-proxy/certs/. The proxy's startup logs will indicate the exact paths used if certificates are auto-generated.

Important

The CA certificate (ca.crt), whether auto-generated by the proxy or provided by you, is crucial. During the agent registration process, the proxy sends this CA certificate to the agent. The agent then uses this CA certificate to verify the proxy's server certificate in all subsequent mTLS connections, ensuring secure communication. The initial registration call from the agent to the proxy uses InsecureSkipVerify = true, so the agent does not need this CA certificate before its first successful registration.

Using Your Own Existing Certificates

For production environments or when you have specific PKI requirements, you will likely want to use your own existing CA and server certificates rather than relying on auto-generated ones.

Certificate Requirements

CA Certificate: Your CA's public certificate file (e.g., my_company_ca.crt).
CA Private Key: Your CA's private key file (e.g., my_company_ca.key). The proxy needs this to be able to issue mTLS certificates for agents during their registration.
Server Certificate: The proxy's server certificate (e.g., kuber_proxy_server.crt), which must be signed by your CA. This certificate should have the correct Common Name (CN) and Subject Alternative Names (SANs) matching the hostname(s) and/or IP address(es) Kubernetes Proxy will be accessible on (e.g., DNS:kubernetes-proxy.example.com, IP:192.168.1.100).
Server Private Key: The private key corresponding to the proxy's server certificate (e.g., kuber_proxy_server.key).

File Permissions

The Kubernetes Proxy process must have read access to these certificate and key files. Ensure that the user account running Kubernetes Proxy has the necessary permissions. Private key files should be strictly protected (e.g., readable only by the proxy user/group).

Example (adjust user, group, paths, and permissions as per your setup):

# Example: Grant ownership to the 's9s_cc:severalnines' user and group
sudo chown s9s_cc:severalnines /opt/custom_certs/my_company_ca.crt
sudo chown s9s_cc:severalnines /opt/custom_certs/my_company_ca.key
sudo chown s9s_cc:severalnines /opt/custom_certs/kuber_proxy_server.crt
sudo chown s9s_cc:severalnines /opt/custom_certs/kuber_proxy_server.key

# Set restrictive permissions, especially for private keys
sudo chmod 644 /opt/custom_certs/my_company_ca.crt
sudo chmod 600 /opt/custom_certs/my_company_ca.key
sudo chmod 644 /opt/custom_certs/kuber_proxy_server.crt
sudo chmod 600 /opt/custom_certs/kuber_proxy_server.key

Configuration Methods

You can configure Kubernetes Proxy to use your existing certificates in one of two ways:

Using Default File Paths: Place your four certificate and key files (CA certificate, CA private key, server certificate, server private key) into the default directory that Kubernetes Proxy checks at startup, ensuring they are named as follows:
- CA Certificate: /usr/share/kuber-proxy/certs/ca.crt
- CA Key: /usr/share/kuber-proxy/certs/ca.key
- Server Certificate: /usr/share/kuber-proxy/certs/server.crt
- Server Key: /usr/share/kuber-proxy/certs/server.key
If Kubernetes Proxy finds these files with the correct names in its default certificate directory, it will use them.
Using Environment Variables: Set the following environment variables to point to the absolute paths of your certificate and key files. This is often the preferred method for containerized deployments or when using custom file locations. These variables can be set in the proxy's service unit file (e.g., /etc/default/kuber-proxy for systemd services) or as part of its container/pod environment.
- PROXY_CA_CERT_PATH=/path/to/your/ca.crt
- PROXY_CA_KEY_PATH=/path/to/your/ca.key
- PROXY_CERT_PATH=/path/to/your/server.crt
- PROXY_KEY_PATH=/path/to/your/server.key
Replace /path/to/your/ with the actual paths to your respective files.