Placement Group

A Placement Group controls how Zenlayer Elastic Compute (ZEC) lays out a set of instances across the physical hosts of a region. To manage placement groups, navigate to the Placement Group page in the console. Without one, the scheduler is free to land any two instances on the same host — so a single host failure can take down both replicas of your service. A placement group declares the opposite: the listed instances belong together as one fault-tolerant set, and the platform spreads them across different underlying hosts so that no single host failure can take more than a known share of them down.

---

What a Placement Group Is

A placement group is a region-scoped object that pins a set of instances to distinct physical hosts. Two parameters shape it:

• partition_num — the maximum number of member instances the group can hold. The platform aims to put each member on its own host. Range 2–5, default 3.

• affinity — how many group members the platform is allowed to co-locate on the same host when full spread isn't achievable. It is a tolerance, not a target or a multiplier. Range 1 to partition_num / 2, default 1.

The group's capacity is partition_num instances. The platform's first choice is always full spread — one member per host. affinity only governs the fallback: if the region cannot give each member a distinct host, up to affinity members may share a host rather than fail the placement. Anything beyond affinity is refused.

The platform reports a constraint_status so you can confirm at a glance whether the spread is currently honored.

A placement group lives entirely in one region (for example asia-east-1). It does not stretch across regions. To survive the loss of an entire region, run a separate placement group per region and replicate at the application layer.

Partition granularity is host-level today.

---

Why Use One

Scenario	Placement Group?	Notes
Distributed quorum (etcd, ZooKeeper, Consul) — odd-number cluster	✅ Yes	Each member on its own host. A single host failure loses at most one quorum member.
Stateful replicas (DB primary + replicas, Kafka brokers, Cassandra ring)	✅ Yes	Co-locating replicas defeats the point of having them.
Stateless web tier with N>1 replicas behind a load balancer	✅ Yes	Keeps a single host fault from taking out the whole tier behind the VIP.
Cross-region HA — survive a full region outage	❌ Not enough	Use one placement group per region plus application-level replication.
A single VM, no replicas	❌ Overkill	A group with one member adds nothing.
HPC / latency-sensitive workloads that want VMs closer, not apart	❌ Wrong primitive	Placement groups enforce anti-affinity. There is no co-location mode today.

---

How partition_num and affinity Work Together

Each member ideally lands on its own physical host

partition_num and affinity express two different things:

• partition_num sets how many members the group can hold (and equivalently, how many distinct hosts the group prefers to span — one per member).

• affinity sets how much co-location is tolerated when free hosts are scarce. With affinity=1, no host may carry more than one member. With affinity=2, up to two members may share a host as a fallback — but never three.

Capacity is partition_num, period. affinity does not multiply it. The setting only controls how far the spread is allowed to degrade before the scheduler refuses an assignment (or marks the group unsatisfied after a recovery event lands two members back on one host).

Two Worked Examples

partition_num=5, affinity=1 — strict spread for a 5-node quorum. The group holds at most 5 members. All 5 must land on different hosts. The platform never co-locates two members. If no qualifying host is free, the assignment is rejected.

partition_num=5, affinity=2 — fault-tolerant spread with a fallback. The group holds at most 5 members. The platform still tries to place all 5 on different hosts. If host capacity prevents that, up to 2 members may share one host — but never more. This keeps a majority of the group on distinct hosts, so a single host failure cannot take a quorum down at once.

In both cases partition_num caps the group at 5 members. affinity only changes how much spread can degrade before the platform refuses placement.

Picking partition_num

Match partition_num to the size of the cluster you want to spread:

Cluster shape	partition_num
Primary + 1 replica	2
Primary + 2 replicas	3
3-node quorum (etcd, ZK, Consul)	3
5-node quorum	5

To grow past partition_num=5, split the workload across multiple placement groups.

Picking affinity

affinity is your tolerance for co-location when full spread isn't achievable. Leave it at the default 1 for the strictest "one-member-per-host" guarantee — the right choice for small quorums and stateful replicas, where any two replicas going down together is unacceptable. Raise it (within partition_num / 2) when you'd rather accept partial co-location than have an assignment refused during a host shortage. The cap of partition_num / 2 exists so a single host failure can never bring down a majority of the group.

---

Lifecycle

Lifecycle: create the group, then assign instances one by one

A placement group is created empty and populated by assigning instances to it one at a time. Membership is a separate operation from instance creation.

1. Create the group. region_id and the initial partition_num are set up front. The region is fixed for life; partition_num and affinity can be modified later.

2. Assign an instance to the group. The instance must be in the group's region. The platform picks a host that satisfies the spread.

3. Remove an instance at any time. Its slot in the group frees up.

4. Modify partition_num or affinity later. Decreasing partition_num below the current member count is rejected.

5. Delete the group once it has no members.

Membership is exclusive: an instance belongs to at most one placement group. Reassigning across groups is a single operation — the platform removes the instance from the old group and slots it into the new one.

Hard cap: instance_count ≤ partition_num. Adding a member to a full group is rejected.

---

Constraint Status

constraint_status reports whether the current placement still honors the spread:

Status	Meaning
Constraint met	No host carries more than one member — full spread is in effect. Steady state.
Constraint at risk	Some host carries more than one member but no more than affinity. Within tolerance, but the safety margin is reduced.
Constraint violated	Some host carries more than affinity members. Rare; arises only under unusual recovery paths.

The platform actively avoids placements that would violate the rule, so most groups stay met indefinitely.

---

Working with Instances

Adding an existing instance

You can move a running instance into a placement group as long as a slot is free and the instance is in the group's region. The platform applies the placement on the instance's next placement event — typically the next stop/start. Until then, the instance is associated with the group but its host does not change.

If the instance is currently on a host that conflicts with the group, joining does not trigger a live migration. Schedule a stop/start so the platform can re-place it.

Removing an instance

Removal is immediate at the membership level. The instance keeps running on its current host; only the anti-affinity bookkeeping changes.

Replacing a failed member

Assign the replacement to the group as soon as it exists. The freed slot is reused.

---

Limits

Property	Value
Scope	One region (e.g. asia-east-1). No cross-region groups.
partition_num	2–5, default 3.
Member instances per group	≤ partition_num.
Group memberships per instance	At most 1.
affinity	1 to partition_num / 2, default 1.
Partition granularity	Host-level

---

Frequently Asked Questions

Can a placement group span regions? No. A placement group is bound to one region for life. For cross-region HA, run one group per region and replicate above.

Can I add more instances than partition_num? No. Raise partition_num (up to 5) or split the workload across multiple groups.

Does raising affinity give me more capacity? No. Capacity is always partition_num. affinity is the maximum number of members the scheduler may co-locate on a single host when full spread isn't possible — it controls how much the spread is allowed to degrade, not how many members the group holds.

What happens during live migration of a member? The destination host is chosen so the constraint still holds. Membership and constraint_status are preserved across the migration.

Can I move an instance between two placement groups? Yes. Re-assigning is one operation — the instance leaves the old group's slot and takes a free slot in the new one. Both groups must be in the instance's region.

Does a placement group cost extra? No. There is no per-group charge.

Why was my assignment rejected? Either the group is full (instance_count == partition_num) or no host in the region can satisfy the constraint at this affinity level. Raise partition_num, raise affinity (allow more co-location as a fallback), or pick a different region.

Can I spread across racks or switches instead of hosts? Not today — only host-level placement is exposed.

How is a placement group different from a resource group? A resource group is an organizational/billing boundary. A placement group is a physical-placement constraint — it controls where instances may run. They are independent.

---

Learn More

• Instance Specification — pick the instance shape for each member.

• Network Interface — how vNICs follow instances across live migration.