Generate and Configure TLS Certificates for etcd (2026)

The most surprising thing about TLS certificates for etcd is that they aren’t just for encryption; they’re primarily for authentication and authorization in a distributed system where trust is paramount.

Let’s see etcd in action with TLS. Imagine a simple two-node etcd cluster.

On etcd-node-1, we’ll have our certificates and key.

# On etcd-node-1
export ETCDCTL_CACERT=/etc/etcd/ssl/ca.pem
export ETCDCTL_CERT=/etc/etcd/ssl/etcd-server.pem
export ETCDCTL_KEY=/etc/etcd/ssl/etcd-server-key.pem
export ETCDCTL_ENDPOINTS=https://etcd-node-1:2379,https://etcd-node-2:2379

# Check cluster health
etcdctl endpoint health
# Output should show both endpoints healthy

And on etcd-node-2:

# On etcd-node-2
export ETCDCTL_CACERT=/etc/etcd/ssl/ca.pem
export ETCDCTL_CERT=/etc/etcd/ssl/etcd-server.pem
export ETCDCTL_KEY=/etc/etcd/ssl/etcd-server-key.pem
export ETCDCTL_ENDPOINTS=https://etcd-node-1:2379,https://etcd-node-2:2379

# Check cluster health
etcdctl endpoint health
# Output should show both endpoints healthy

This works because each etcd node presents its etcd-server.pem certificate to other nodes and to clients. The CA (ca.pem) verifies that these server certificates are legitimate, and the etcdctl client verifies that the server it’s talking to is indeed an etcd server it trusts.

The Problem etcd TLS Solves

In a distributed system like etcd, nodes need to communicate and agree on state. Without TLS, this communication is unencrypted and, more importantly, unauthenticated. Any node or client could impersonate another, leading to data corruption, unauthorized access, or complete cluster failure. TLS provides a cryptographic identity for each etcd member and client, ensuring that only authenticated parties can participate in the cluster and that communication is private.

How it Works Internally

1. CA Generation: You start with a Certificate Authority (CA) that acts as the trusted root. This CA signs all other certificates.
2. Server Certificate Generation: Each etcd server (node) needs its own certificate. This certificate is signed by the CA. Crucially, the certificate must include the IP addresses and DNS names that etcd will use to communicate with other nodes and clients (e.g., etcd-server.example.com, 192.168.1.10, localhost).
3. Client Certificate Generation: Clients (like etcdctl or Kubernetes API servers) also need certificates, signed by the same CA. These are used to authenticate to the etcd server.
4. Peer Communication: When etcd node A connects to etcd node B, A presents its server certificate to B. B verifies A’s certificate against its trusted CA. If valid, B then presents its server certificate to A for A to verify. This mutual TLS (mTLS) handshake ensures both nodes are who they claim to be.
5. Client Communication: When a client connects to an etcd server, the server presents its certificate. The client verifies it against its trusted CA. If the client also needs to authenticate itself (e.g., for authorization), it presents its own client certificate, which the server then verifies against its trusted CA.

Your Levers of Control

• --cert-file / ETCD_CERTFILE: Path to the etcd server’s public certificate. This is what it presents to clients and peers.
• --key-file / ETCD_KEYFILE: Path to the etcd server’s private key. This must be kept secret.
• --trusted-ca-file / ETCD_TRUSTED_CA_FILE: Path to the CA certificate. This is used to verify the certificates presented by peers and clients.
• --peer-cert-file / ETCD_PEER_CERT_FILE: Path to the certificate used for peer-to-peer communication. Often, this is the same as --cert-file.
• --peer-key-file / ETCD_PEER_KEY_FILE: Path to the private key used for peer-to-peer communication. Often, this is the same as --key-file.
• --peer-trusted-ca-file / ETCD_PEER_TRUSTED_CA_FILE: Path to the CA certificate used to verify peer certificates. Often, this is the same as --trusted-ca-file.
• --client-cert-auth: A boolean flag. If true, etcd requires clients to present a valid certificate signed by the trusted CA. This is crucial for authorization.
• --listen-client-urls and --listen-peer-urls: These specify the network interfaces and ports etcd listens on. When TLS is enabled, these URLs must use the https scheme. For example: https://192.168.1.10:2379 for client URLs and https://192.168.1.10:2380 for peer URLs.

The sans Field is King

The Subject Alternative Name (SAN) field within the etcd server certificate is non-negotiable. It’s a list of DNS names and IP addresses that the certificate is valid for. If an etcd node tries to connect to another node using an IP address or DNS name that isn’t listed in that node’s certificate’s SANs, the connection will fail with a certificate verification error, even if the CA is trusted. When generating certificates, ensure all IPs and hostnames used for communication (--initial-advertise-peer-urls, --advertise-client-urls, and the IPs/hostnames in --listen-client-urls and --listen-peer-urls) are correctly populated in the SANs.

Once you have TLS configured, the next logical step is to understand etcd’s authorization capabilities, which leverage these client certificates to grant or deny access to specific keys.