Certificates¶
This page is for operators who plan rotations or read the certificates: section of
chalkctl status. It lists every CA and key of a cluster, every certificate chalkos issues with
its lifetime and the point at which it is renewed, and the notes status shows about them.
Certificates in How chalkos works explains how they chain.
Every CA has an ECDSA P-256 key. Every certificate chalkos issues is capped at its CA's own expiry
and backdated by one hour. No two CAs of a secrets file may share a key: the file is refused with
<CA> and <CA> share a key; every CA needs its own.
CAs and keys¶
chalkctl gen secrets generates each of these once, into the secrets file. The last five exist
on the Kubernetes layer.
| CA or key | Lifetime | Issues or does | Held by | Status warns |
|---|---|---|---|---|
| OS CA | 10 years | Client certificates and the node CA; path length 1 | The secrets file; its certificate is on every installed node and in every image built with osCA |
in its last year |
| Node CA | 5 years | Node certificates, for TLS servers and clients only; path length 0 | The secrets file and every control plane | in its last 18 months |
| Kubernetes CA | 10 years | The certificates of the API server, the controllers, chalkd and the kubelets, and admin kubeconfigs | The secrets file and every control plane; workers get its certificate | in its last year |
| Front-proxy CA | 10 years | The certificate the API server presents to aggregated API servers | The secrets file and every control plane | in its last year |
| etcd CA | 10 years | etcd's server and peer certificates and those of its clients | The secrets file and every control plane | in its last year |
| Service-account key | No expiry | Signs service-account tokens, with ES256 | The secrets file and every control plane | never |
| Encryption key | No expiry | Encrypts Secrets in etcd, with secretbox | The secrets file and every control plane | never |
The secrets file also holds the recovery secret, from which each node's recovery key is derived.
Certificates¶
| Certificate | Issued by | Lifetime | Renewed | Kept in |
|---|---|---|---|---|
| Node certificate | chalkctl at install; a control plane, or chalkctl node renew | 1 year | by chalkd once two thirds of its lifetime have passed, checked about hourly; on a node without Kubernetes, by chalkctl node renew | /state/chalkd/node.pem on STATE, with its key and the node CA's certificate |
| Client certificate of a client file | chalkctl client new | 1 year, or --ttl |
by issuing a new client file | the client file |
| chalkctl's admin certificate | chalkctl, from the secrets file, for one command | 1 hour | never; each command issues its own | memory |
| Control plane certificates | the control plane, from its Kubernetes share | 1 year | at every boot, and once two thirds of the lifetime of the first to expire have passed | /run/chalkos/kubernetes/pki, a tmpfs |
| chalkd's clients of the API server and etcd | chalkd on a control plane | 1 hour | at half their lifetime | memory |
| Kubelet client certificate | a worker's share at install; a control plane at every boot; then the controller-manager | 1 year | by the kubelet, once 70 to 90% of its lifetime have passed | /var/lib/kubelet/pki on VAR |
| Kubelet serving certificate | the controller-manager, on a request chalkd approves | 1 year | by the kubelet | /var/lib/kubelet/pki on VAR |
| Admin kubeconfig | chalkctl kubeconfig | 1 year, or --ttl |
by issuing a new kubeconfig | the kubeconfig |
The control plane certificates are the API server's serving certificate, its clients of the kubelets and of etcd, the front-proxy client, etcd's server and peer certificates, and the certificates in the kubeconfigs of the controller-manager and the scheduler.
A failed renewal of a node certificate keeps the current certificate and retries after a minute, doubling the wait up to an hour. chalkctl warns about a client file during its last 30 days and refuses it once it expired.
Status notes¶
chalkctl status lists each certificate a node holds with its expiry, and the CAs it trusts by the
first 16 hex digits of their fingerprints, the issuing one marked (issues). A certificate line
carries a note when something needs doing:
| Note | Shown for |
|---|---|
less than a third of its lifetime remains |
A node or control plane certificate whose renewal is due |
the node certificate expires on <date>; this image cannot renew it on its own; run chalkctl node renew <node> |
A node certificate on a node without Kubernetes, whose renewal is due; expired on once it expired |
renewal failing: <reason>; expires <date> |
A renewal that failed |
less than a tenth of its lifetime remains, though the kubelet renews it itself |
A kubelet certificate close to its end |
<CA> expires <date> |
A CA in its last year |
node CA expires <date>; run chalkctl rotate node-ca |
The node CA in its last 18 months |
expired, <CA> expired <date> |
A certificate or CA past its end |
expired; deliver a new one with chalkctl config apply <node> --kubernetes-share |
A worker's kubelet client certificate, when the one the kubelet renewed was lost with VAR and the one in its Kubernetes share has expired too |
The node CA is reported six months before the other CAs because no node certificate outlives it, so the certificates it issues get shorter in its last year.
The clock's line is time: synchronised to <source>, offset <seconds> s, or
time: not synchronised; certificates are checked against this clock.
Sources: pkg/pki, pkg/clustersecrets/kubernetes.go, pkg/kubernetes/pki, pkg/chalkd/renew.go,
pkg/chalkd/renewal, pkg/chalkd/certstatus.go, pkg/chalkd/layers/kubernetes/issuer.go,
pkg/chalkd/layers/kubernetes/certificates.go, pkg/chalkctl/credentials.go and
pkg/chalkctl/node.go.