An Etcd Cluster is a managed distributed key-value store for service discovery, coordination, and configuration storage. Each instance runs on its own dedicated VM; the cluster is described as a single resource with one entry per node in spec.instances — there is no separate node-group resource.

Key concepts

• Cluster-wide sizing, per-instance identity — spec.vmOfferId/spec.volumeOfferId/spec.volumeSizeGiB apply identically to every instance (the cluster is homogeneous by design); only each instance's id and subnet (spec.instances[].id/vpcSubnetId) vary per node

• Instance id is caller-supplied — the platform diffs the desired instances array against the current one on every modify; reuse an instance's existing id to keep it, or supply a new id to add a node

• Scaling moves one step between valid sizes — a single request may only move the instance count to the adjacent allowed size (1↔3, 3↔5, 5↔7), and cannot add and remove instances in the same request (submit two separate modifies instead). To go from 1 node to 5, apply two separate modify requests: 1→3, then 3→5

• Subnet placement — every instance must share one Vpc (etcd peers across different VPCs cannot reach each other); an existing instance's vpcSubnetId is immutable — to move an instance to a different subnet, add a new instance there and remove the old one

• Cluster size — must be odd and between 1 and 7 (etcd needs a raft quorum to stay available, so an even count tolerates no more failures than the next-lower odd one, and 7 is etcd's own documented practical ceiling); any other count is rejected with a validation error

• Public access — private by default; set spec.createPublicIpv4 to give every instance a public IPv4. Immutable after creation

• Monitoring addons are opt-in — spec.addons is empty by default and nothing extra runs on a node until you name an addon. Today one is offered: node_exporter 1.12.1 on port 9100, bound to each node's private address and reachable only from inside the cluster's VPC. It carries no authentication, so it is never exposed on the public address even on a cluster with createPublicIpv4. Removing it from the list is a real instruction: the process is stopped and its binary deleted

• Provisioning needs no outbound internet — the etcd release, the TLS tooling and the addon binaries all ship in the platform's provisioning image, and Ansible itself is pushed to each node from it. A cluster in a VPC with no NAT and no floating IP provisions exactly like any other; an existing cluster picks this up on its next modify

Examples

A private 3-node cluster on an existing subnet.

Terraform

Python SDK

kc CLI

Related pages

Resource docs

• VPC Subnet resource docs

Examples

• CLI etcd example
• Terraform etcd example
• Python SDK etcd example