Certificates and encryption

kcore uses mutual TLS (mTLS) for all management-plane communication. Disk encryption with LUKS2 protects data at rest.

PKI hierarchy

Root CA — created by kctl create cluster
Sub-CA — lives on the controller, signs node leaf certificates
Controller cert — identifies the controller to nodes and clients
kctl client cert — authenticates CLI operations
Per-node certs — generated during kctl node install

mTLS bootstrap

kctl create cluster generates the full PKI (root CA, sub-CA, controller cert, kctl client cert). kctl node install pushes the node certificate, private key, and CA chain to the target node. Controller nodes also receive the sub-CA key pair.

Certificate auto-renewal

The node-agent checks certificate expiry daily. If a certificate expires within 30 days, the agent calls the RenewNodeCert RPC. The sub-CA signs a new leaf certificate and returns the updated chain.

Manual rotation

# Rotate the sub-CA
kctl rotate sub-ca --certs-dir ~/.kcore/<context>/

# Re-sign the controller cert and trigger TLS reload
kctl rotate certs --controller <host:port> --certs-dir ~/.kcore/<context>/

rotate sub-ca generates a new sub-CA and pushes it to the controller. rotate certs re-signs the controller certificate and triggers ReloadTls on the controller.

Inspecting certificates

kctl get nodes shows cert_expiry_days per node. The compliance report includes a Certificate Lifecycle section with expiring and unknown certificate counts.

LUKS2 disk encryption

LUKS2 encryption is mandatory for the OS disk on every node.

TPM2 path — systemd-cryptenroll seals the LUKS key to the TPM2 device.
Key-file path — passphrase-based unlock using a key file.
Recovery key — stored at /etc/kcore/recovery/luks-recovery-key.txt (root-only, mode 0400).

LUKS reporting

The node-agent detects the LUKS unlock method at registration: tpm2 if /dev/mapper/cryptroot exists and a TPM device is present, key-file otherwise. kctl get compliance-report shows the cluster-wide LUKS breakdown by method.

TLS configuration

Production — mTLS required (default). All gRPC and API traffic is encrypted and mutually authenticated.
Development — kctl --insecure disables TLS for local testing over plain HTTP.

Never use --insecure in production. Disabling mTLS removes authentication and encryption from the management plane.