Installing and configuring etcd

Installation

Debian/Ubuntu packages

To install etcd from the official Debian/Ubuntu apt repositories:

$ sudo apt-get -y install etcd

You can check the version installed and the latest available version. If the version installed is out of date and you want to install the latest one, use the prebuilt binaries method.

RedHat-compatible packages

The PGDG yum extras repositories contains etcd packages.

To set up and use yum.postgresql.org on your systems, see the PostgreSQL Linux downloads website.

Depending on your system, enable the following repositories:

RHEL 9: pgdg-rhel9-extras
RHEL 8: pgdg-rhel8-extras
RHEL 7: pgdg-rhel7-extras

For example, this command installs etcd on RHEL 8:

$ sudo dnf --enablerepo=pgdg-rhel8-extras install -y etcd

You can check the version installed and the latest available version. If the version installed is out of date and you want to install the latest one, use the prebuilt binaries method.

Prebuilt binaries

These commands output the version of the installed etcd binary and get the latest version from the etcd-io website:

$ etcd --version |head -1
etcd Version: 3.5.7

$ ETCD_RELEASE=$(curl -s https://api.github.com/repos/etcd-io/etcd/releases/latest|grep tag_name | cut -d '"' -f 4)
$ echo "Latest etcd version released: $ETCD_RELEASE"
Latest etcd version released: v3.5.7

The easiest way to install the etcd latest release is from prebuilt binaries.

On amd64 hosts, use the following commands:

$ ETCD_RELEASE=$(curl -s https://api.github.com/repos/etcd-io/etcd/releases/latest|grep tag_name | cut -d '"' -f 4)
$ curl -sL https://github.com/etcd-io/etcd/releases/download/${ETCD_RELEASE}/etcd-${ETCD_RELEASE}-linux-amd64.tar.gz \
 | sudo tar xz -C /usr/bin --strip=1 --wildcards --no-anchored etcdctl etcd
$ etcd --version |head -1
etcd Version: 3.5.7

Then, create the data directory and system user:

$ sudo mkdir -p /var/lib/etcd/
$ sudo mkdir /etc/etcd
$ sudo groupadd --system etcd
$ sudo useradd -s /sbin/nologin --system -g etcd etcd
$ sudo chown -R etcd:etcd /var/lib/etcd/
$ sudo chmod -R a+rw /var/lib/etcd

Configure the systemd unit file:

$ cat <<EOF | sudo tee /etc/systemd/system/etcd.service
[Unit]
Description=etcd key-value store
Documentation=https://github.com/etcd-io/etcd
After=network-online.target local-fs.target remote-fs.target time-sync.target
Wants=network-online.target local-fs.target remote-fs.target time-sync.target

[Service]
User=etcd
Type=notify
Environment=ETCD_DATA_DIR=/var/lib/etcd
Environment=ETCD_NAME=%H
EnvironmentFile=-/etc/etcd/etcd.conf
ExecStart=/usr/bin/etcd
Restart=always
RestartSec=10s
LimitNOFILE=40000

[Install]
WantedBy=multi-user.target
EOF

$ sudo systemctl daemon-reload

Configuration

Configure the firewall if needed:

$ sudo firewall-cmd --quiet --zone=public --add-port=2379/tcp --permanent
$ sudo firewall-cmd --quiet --zone=public --add-port=2380/tcp --permanent
$ sudo firewall-cmd --quiet --reload

To configure and create a new etcd cluster, you need to define the initial cluster configuration by setting the ETCD_INITIAL_CLUSTER variable. That list must contain all the etcd hosts and their IP addresses.

This example shows three etcd hosts:

$ ETCD_INITIAL_CLUSTER="etcd1=http://192.168.121.35:2380,etcd2=http://192.168.121.245:2380,etcd3=http://192.168.121.191:2380"

To fetch it dynamically, you can use this simple shell script, where etcd1 etcd2 etcd3 are the three etcd hosts:

# Fetch the IP addresses of all etcd hosts
etcd_nodes=( etcd1 etcd2 etcd3 )
i=0
for node in "${etcd_nodes[@]}"
do
  i=$i+1
  target_ip=$(dig +short $node)
  target_array[$i]="$node=http://$target_ip:2380"
done
ETCD_CLUSTER_URL=$(printf ",%s" "${target_array[@]}")
export ETCD_CLUSTER_URL=${ETCD_CLUSTER_URL:1}
echo "ETCD_CLUSTER_URL=\"$ETCD_CLUSTER_URL\""

Then, set up the local etcd configuration and start the service:

$ MY_IP=$(hostname -I | awk ' {print $1}')
$ MY_NAME=$(hostname --short)
$ cat <<EOF | sudo tee /etc/etcd/etcd.conf
#[Member]
ETCD_LISTEN_PEER_URLS="http://$MY_IP:2380"
ETCD_LISTEN_CLIENT_URLS="http://localhost:2379,http://$MY_IP:2379"
ETCD_NAME="$MY_NAME"
#[Clustering]
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://$MY_IP:2380"
ETCD_INITIAL_CLUSTER="$ETCD_CLUSTER_URL"
ETCD_ADVERTISE_CLIENT_URLS="http://$MY_IP:2379"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-1"
ETCD_INITIAL_CLUSTER_STATE="new"
EOF
$ sudo systemctl enable etcd.service
$ sudo systemctl start etcd.service

Note

When using the prebuilt binaries method or the Red Hat-compatible packages, the configuration file is /etc/etcd/etcd.conf. When using the Debian/Ubuntu packages, the configuration file is /etc/default/etcd.

Start the service and listen on ports 2379 and 2380. Check the cluster status:

$ ss -tunelp | grep 2379
tcp   LISTEN 0      4096       127.0.0.1:2379      0.0.0.0:*    ...
tcp   LISTEN 0      4096   192.168.121.7:2379      0.0.0.0:*    ...

$ ss -tunelp | grep 2380
tcp   LISTEN 0      4096   192.168.121.245:2380      0.0.0.0:*    ...

$ etcdctl member list
3078f511def8f5a9, started, etcd1, http://192.168.121.7:2380, http://192.168.121.7:2379, false
493bb0ea8338d60a, started, etcd2, http://192.168.121.174:2380, http://192.168.121.174:2379, false
bfdda4bcab677625, started, etcd3, http://192.168.121.226:2380, http://192.168.121.226:2379, false

$ etcdctl endpoint health
127.0.0.1:2379 is healthy: successfully committed proposal: took = 2.103463ms

$ etcdctl endpoint status
127.0.0.1:2379, 3078f511def8f5a9, 3.5.4, 29 kB, true, false, 2, 12, 12,

Could this page be better? Report a problem or suggest an addition!