etcd (etcd)
Distributed, consistent key value store used for coordination, configuration and leader election. Single member or odd cluster.
Generated from catalog/services/etcd.yaml: do not edit by hand.
Summary
| Version | 3.5.35 |
| Use | install and configure |
| Layer | infrastructure (shown apart) |
| Category | Data platforms |
| Installation methods | binary, podman |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | etcd |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | quay.io/coreos/etcd | v3.5.35 | Apache-2.0 | image key etcd, used by etcd, digest sha256:60eea0773022eb2c38b73091e93d6784e0663212e6c4b98faf5547e99058e35d |
| binary archive | etcd-v3.5.35-linux-amd64.tar.gz | 3.5.35 | Apache-2.0 | https://github.com/etcd-io/etcd/releases/download/v3.5.35/etcd-v3.5.35-linux-amd64.tar.gz, x86_64, checksum sha256 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 1024 MB of memory (blocking,
memory). - a synchronized clock (blocking,
time_sync).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
etcd | client | 2379/tcp | yes |
etcd | peer | 2380/tcp | yes |
etcd | metrics | 2381/tcp | yes |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
etcd member (etcd) | master | binary, podman | 2379/tcp, 2380/tcp, 2381/tcp |
Single member (standalone) (default)
One etcd member, without fault tolerance.
What the mode deploys:
| Component | Placement |
|---|---|
etcd | min 1, max 1 |
Cluster (cluster)
An odd number of members (3, 5 or 7) keeping a Raft quorum.
What the mode deploys:
| Component | Placement |
|---|---|
etcd | min 3, max 7, odd number, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select etcd. The card shows the licence
Apache-2.0. Pick the Method amongbinary,podman(defaultbinary). -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
standalone(default),cluster. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Writes a key, reads it back through etcdctl and deletes it.
High availability
| Cluster | native (native) |
| High availability | native (native) |
| Failover | native (native) |
| Replication | native (native) |
| Quorum | Raft (raft) |
| Discovery | static (static) |
| Entry point | client discovery (client-discovery) |
| Official documentation | https://etcd.io/docs/v3.5/op-guide/clustering/ |
| Peer TLS parameter | tls_enabled |
| Cluster status command | endpoint_status |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
standalone | standalone (standalone) | single (single) | - | 1 | One member, without fault tolerance. |
cluster | cluster (cluster) | active-active (active-active) | etcd | 3 | 3, 5 or 7 Raft members; the cluster survives the loss of a minority. |
Notes
- Each member needs a persistent, low latency disk: Raft writes every change to the disk of the majority before answering.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Client port (client_port) | port | 2379 | - | no | no | no | Port of the client API. |
Peer port (peer_port) | port | 2380 | - | no | no | no | Port of the Raft traffic between members. |
Metrics port (metrics_port) | port | 2381 | - | no | no | no | Port of /metrics and /health without client authentication. |
Storage
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Backend quota (quota_backend_mb) | int | 2048 | min 256, max 8192, MB | no | no | no | Maximum size of the database before alarms. |
Compaction retention (auto_compaction_retention) | string | 1h | - | no | no | no | History kept before automatic compaction. |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
TLS (tls_enabled) | bool | false | - | no | no | no | Encrypt client and peer traffic with certificates of the manager CA. |
Cluster token (cluster_token) | string | navin-etcd | ^[a-z0-9-]{3,64}$ | no | no | no | Initial cluster token, unique per etcd cluster. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
client | http | etcd | 2379 (client_port) | - | tls_enabled | - | - | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
List members (member_list) | etcd | first host | Lists the members of the etcd cluster. |
Endpoint status (endpoint_status) | etcd | first host | Shows leader, Raft index and database size of every member. |
Take a snapshot (snapshot) | etcd | first host | Saves a snapshot of the key space under the data directory. |
Defragment (defragment) | etcd | every host | Releases the free space of the database of every member. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
etcd | HTTP http://{{ host.ip or '127.0.0.1' }}:{{ config.metrics_port }}/health | Expected 200; 60 retries |
Readiness (service check)
| Check | Details |
|---|---|
HTTP http://{{ host.ip or '127.0.0.1' }}:{{ config.metrics_port }}/health | Expected 200 |
Smoke test
Writes a key, reads it back through etcdctl and deletes it. (etcd: put, get, delete)
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
memory | memory_mb {"min": 1024} | at least 1024 MB of memory | blocking | every component |
time_sync | time_sync {} | a synchronized clock | blocking | every component |
client_port_free | port_free {"param": "client_port"} | port 2379 free on the host | blocking | every component |
Backup and restore
Consistent snapshot of the key space (etcdctl snapshot save); the restore rebuilds the data directory of a single member with etcdutl.
| Format | etcd-snapshot |
| Component | etcd |
| Files | {{ backup.dir }}/etcd.db |
| Restore test | yes |
| Instances stopped for the restore | yes |
Upgrade
| Supported from | 3.5.21 |
| Stateful | yes |
| Backup before the upgrade | yes |
| Rollback | yes |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Upstream documentation
- Homepage: https://etcd.io
- Source: https://github.com/etcd-io/etcd
- High availability: https://etcd.io/docs/v3.5/op-guide/clustering/