How to enable TLS¶
Transport Layer Security (TLS) plays a crucial role in securing database communications. Just as it protects web traffic, TLS encrypts the data transmitted between database clients and servers, preventing unauthorised access and ensuring confidentiality.
etcd provides a secure transport layer for peer-to-peer and client-server communication, and the charm provides a simple way of enabling TLS encryption for both types.
- Peer-to-peer
All communication between members in the cluster will be encrypted and authenticated using the client certificates.
- Client-to-server
The etcd client can verify the server identity and provide transport security.
etcd also supports mutual TLS authentication, which provides an additional layer of security by requiring clients to present a certificate to the server for authentication. The server then checks whether a trusted CA signed the certificate and decide whether to serve the request.
Deploy a TLS provider¶
Charmed etcd provides the option of using different CA certificates for client-server and peer-to-peer communication. This allows you to have different levels of trust for the two types of communication. You can also use the same CA certificate for both types of communication.
You can enable peer-to-peer encryption alone, client-to-server encryption alone, or both at the same time.
This guide will use the Self-signed Certificates charm as an example for all cases.
Caution
Self-signed certificates are not recommended for a production environment.
Check this guide for an overview of all the TLS certificates charms available.
Deploy the self-signed-certificates charm. etcd uses v4 of the edge channel.
juju deploy self-signed-certificates --channel edge
Wait until self-signed-certificates is active by monitoring it with juju status.
user@host:~$ juju status --watch 1s...
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 0 no
self-signed-certificates active 1 self-signed-certificates latest/edge 238 no
...
Enable encryption in transit¶
To enable encryption in transit between etcd members, all you need to do is integrate with the TLS provider charm to generate the required certificates and keys.
Integrate on peer-certificates endpoint¶
Integrate the certificates charm with the charmed-etcd application on the peer-certificates endpoint. This will generate the required certificates and keys for peer-to-peer communication.
juju integrate self-signed-certificates:certificates charmed-etcd:peer-certificates
Check certificates in use¶
To check that etcd is using the certificates generated by the self-signed-certificates charm, run the etcdctl command shown below. You can replace the endpoint with the IP address corresponding to the unit you choose to run the command in.
If you do not have the etcdctl command installed on your local machine, see the official etcd installation instructions.
user@host:~$ etcdctl member list --endpoints http://10.73.32.122:2379 -w table+------------------+---------+---------------+---------------------------+--------------------------+------------+
| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | IS LEARNER |
+------------------+---------+---------------+---------------------------+--------------------------+------------+
| 68327020b9432fc8 | started | charmed-etcd2 | https://10.73.32.193:2380 | http://10.73.32.193:2379 | false |
| c5aec105e79a433b | started | charmed-etcd1 | https://10.73.32.131:2380 | http://10.73.32.131:2379 | false |
| c74cb15a5aeade42 | started | charmed-etcd0 | https://10.73.32.122:2380 | http://10.73.32.122:2379 | false |
+------------------+---------+---------------+---------------------------+--------------------------+------------+
You can see that etcd is running with the peer addresses using https and the client addresses using http. This indicates that the peer-to-peer communication is encrypted using the certificates generated by the self-signed-certificates charm.
Enable client-to-server encryption and authentication¶
To enable client-to-server encryption and authentication, you need to generate the required certificates and keys for the clients.
Integrate on client-certificates endpoint¶
Just like with peer-to-peer communication, integrate the self-signed-certificates charm to the charmed-etcd application but this time on the client-certificates endpoint.
juju integrate self-signed-certificates:certificates charmed-etcd:client-certificates
Check certificates in use¶
To check that the etcd server is using the certificates generated by the self-signed-certificates charm, run the following command:
user@host:~$ etcdctl member list --endpoints http://10.73.32.122:2379 -w table{"level":"warn","ts":"2025-02-14T07:14:39.578082Z","logger":"etcd-client","caller":"[email protected]/retry_interceptor.go:63","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0004a4000/10.73.32.122:2379","attempt":0,"error":"rpc error: code = DeadlineExceeded desc = latest balancer error: last connection error: connection error: desc = \"error reading server preface: EOF\""}
Error: context deadline exceeded
You can see that the request failed because etcdctl is trying to connect to the server using http instead of https. This indicates that the client-to-server communication is not encrypted. Let’s try to connect using the https endpoint.
user@host:~$ etcdctl member list --endpoints https://10.73.32.122:2379 -w table{"level":"warn","ts":"2025-02-14T07:15:56.051291Z","logger":"etcd-client","caller":"[email protected]/retry_interceptor.go:63","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc000142000/10.73.32.122:2379","attempt":0,"error":"rpc error: code = DeadlineExceeded desc = latest balancer error: last connection error: connection error: desc = \"transport: authentication handshake failed: tls: failed to verify certificate: x509: certificate signed by unknown authority\""}
Error: context deadline exceeded
The request failed because the client is trying to connect to the server using https but the server is using a certificate that is not signed by a trusted CA.
First, get the certificate authority (CA) certificate from the self-signed-certificates charm using the following command:
user@host:~$ juju run self-signed-certificates/0 get-ca-certificateRunning operation 1 with 1 task
- task 2 on unit-self-signed-certificates-0
Waiting for task 2...
ca-certificate: |-
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Save the CA certificate to a file on your local machine. You can use the following command to save the CA certificate to a file (Note: the command below requires the yq CLI tool)
juju run self-signed-certificates/0 get-ca-certificate --format yaml | yq e '.self-signed-certificates/0.results.ca-certificate' > ca.crt
Now that you have the CA certificate, you can use it to verify the server certificate.
Use the etcdctl command to connect to the server using the https endpoint and provide the CA certificate to verify the server certificate through the --cacert flag.
user@host:~$ etcdctl member list --endpoints https://10.73.32.122:2379 -w table --cacert ca.crt{"level":"warn","ts":"2025-02-14T07:36:32.220229Z","caller":"clientv3/retry_interceptor.go:63","msg":"retrying of unary invoker failed","target":"etcd-endpoints://0xc0000361e0/10.73.32.122:2379","attempt":0,"error":"rpc error: code = DeadlineExceeded desc = latest balancer error: last connection error: connection error: desc = \"error reading server preface: remote error: tls: certificate required\""}
Error: context deadline exceeded
Remember that the server is configured to also require client authentication. You need to provide the client certificate and key to authenticate the client.
You can use the etcdctl command to connect to the server using the https endpoint and provide the client certificate and key through the --cert and --key flags.
Let’s grab the client certificate and key from one of the units and provide them to the server via etcdctl:
user@host:~$ juju ssh charmed-etcd/0 "cat /var/snap/charmed-etcd/current/tls/client.key" > ./client.keyuser@host:~$ juju ssh charmed-etcd/0 "cat /var/snap/charmed-etcd/current/tls/client.pem" > ./client.pem
user@host:~$ etcdctl member list --endpoints https://10.73.32.122:2379 -w table --cacert ca.crt --cert ./client.pem --key ./client.key+------------------+---------+---------------+---------------------------+---------------------------+------------+
| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | IS LEARNER |
+------------------+---------+---------------+---------------------------+---------------------------+------------+
| 68327020b9432fc8 | started | charmed-etcd2 | https://10.73.32.193:2380 | https://10.73.32.193:2379 | false |
| c5aec105e79a433b | started | charmed-etcd1 | https://10.73.32.131:2380 | https://10.73.32.131:2379 | false |
| c74cb15a5aeade42 | started | charmed-etcd0 | https://10.73.32.122:2380 | https://10.73.32.122:2379 | false |
+------------------+---------+---------------+---------------------------+---------------------------+------------+
You can now successfully connect to the server using the https endpoint and provide the CA certificate, client certificate, and key to verify the server certificate and authenticate the client. You can also see that etcd is running with the client addresses using https. This indicates that the client-to-server communication is encrypted.
Enable peer-to-peer, client-to-server, and mutual TLS authentication¶
You can integrate the charmed-etcd application with the TLS certificates provider charm on both the peer-certificates and client-certificates endpoints at the same time.
juju integrate self-signed-certificates:certificates charmed-etcd:peer-certificates
juju integrate self-signed-certificates:certificates charmed-etcd:client-certificates
Enable encryption at deployment time¶
You can also deploy the cluster with encryption enabled from the start by integrating the charmed-etcd application with the TLS certificates provider charm at deployment time.
juju deploy self-signed-certificates --channel edge
juju deploy charmed-etcd -n 3 --channel 3.6/edge
juju integrate self-signed-certificates:certificates charmed-etcd:client-certificates
juju integrate self-signed-certificates:certificates charmed-etcd:peer-certificates