{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:23+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "clustering/placement",
            "title": "Placing Machines in a Cluster",
            "category": "Clustering",
            "url": "https://stratum.cenvero.com/docs/clustering/placement",
            "headings": [
                {
                    "level": 1,
                    "text": "Placing Machines in a Cluster"
                },
                {
                    "level": 2,
                    "text": "Choosing the member for a new machine"
                },
                {
                    "level": 2,
                    "text": "Seeing every member's answer"
                },
                {
                    "level": 2,
                    "text": "Which members are eligible"
                },
                {
                    "level": 2,
                    "text": "The machine's processor model"
                },
                {
                    "level": 2,
                    "text": "Anti-affinity"
                },
                {
                    "level": 2,
                    "text": "Who can do what"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 1972,
            "markdown": "# Placing Machines in a Cluster\n\nWhen a cluster has several members, a new machine can be placed on the member\nthat suits it best, instead of on the member you happened to ask. One rule\ndecides that choice for every create. It looks at each member's free processors,\nmemory and disk, the networks and the image the machine needs, its tenant's\nlimits, its licence, its processor, and the machines of its anti-affinity group.\nEvery member that cannot take the machine is listed with the reason.\n\n> Part of [Clustering](/docs/clustering/overview) and [Compute](/docs/compute/overview),\n> in early access. Placement needs every member to run a version that supports it.\n\nUntil every member does, a placement request is answered with **\"Every member must\nrun a version that supports this.\"**, and on a node in no cluster with **\"This needs a\ncluster of servers: create one or join one first.\"**\n\nPlacement only chooses. It never creates a machine by itself, and the member it\nchooses judges the create by its own licence, its freeze, its tenant limit and its\nroom, as it would for any create it receives.\n\n## Choosing the member for a new machine\n\nLet the cluster choose:\n\n```bash\nsudo cenvero-str-ctl vm create --name web-1 --tenant t-acme --image img-3f9a1c2e \\\n  --vcpus 2 --memory 4096 --disk 20 --network tier-web --placement auto\n```\n\nOr name the member that should create it. The root `--node` flag runs the command\non that member, and that member creates the machine:\n\n```bash\nsudo cenvero-str-ctl --node edge-2 vm create --name web-1 --image img-3f9a1c2e --vcpus 2\n```\n\n`--placement` takes only `auto`, and it cannot be combined with `--node`: a\nplacement chooses the member itself. Without either, the node you type on creates\nthe machine.\n\nOver the API, a create takes `\"placement\": \"auto\"` or `\"node\": \"<member id>\"`, and\nnot both (**\"Give placement or node, not both.\"**). A placed create answers as a\ncreate does on a single node, **201** with the machine and its task. When no member\ncan take the machine, the answer is **409**, with the sentence **\"No member can take\nthis machine. The reasons are listed for each member.\"** and the reasons of every\nmember. A named member that cannot take it is answered the same way, with that\nmember's reasons only.\n\n## Seeing every member's answer\n\nAsk the cluster where a machine of a given size would go, without creating anything:\n\n```bash\ncenvero-str-ctl cluster placement --vcpus 2 --memory-mib 4096 --disk-gib 20 \\\n  --image img-3f9a1c2e --network tier-web --tenant t-acme\n```\n\nOver the API: `GET /api/v1/cluster/placement`, with the query parameters `vcpus`,\n`memory_mib`, `disk_gib`, `image`, `tenant`, `group`, `routed`, `cpu_model`, and\n`networks` (repeated for each network). It answers **200** with the request as it\nwas judged, in `request`, and one entry for each member, in `candidates`:\n\n```json\n{\n  \"request\": { \"vcpus\": 2, \"memory_mib\": 4096, \"disk_gib\": 20, \"tenant\": \"t-acme\" },\n  \"candidates\": [\n    { \"node\": \"edge-1\", \"eligible\": true, \"rank\": 1, \"reasons\": [] },\n    { \"node\": \"edge-2\", \"eligible\": false, \"rank\": null,\n      \"reasons\": [\"This member does not have the room the machine's disk needs.\"] }\n  ]\n}\n```\n\nEach entry says whether the member is `eligible`, gives its `rank` (`null` when it is\nnot eligible), and lists its `reasons`. The eligible members come first, in rank order. The others follow by member id, each\nwith its reasons. The answer shows no tenant's names and no address of another\ntenant's.\n\n## Which members are eligible\n\nA member is excluded, with the reason in its answer, when:\n\n- **It cannot be reached** from the node that asks, or it is stale: **\"This member\n  cannot be reached from this node right now, so nothing is placed on it.\"**\n- **It does not run a version that supports placement.** The answer is\n  **\"Every member must run a version that supports this.\"**\n- **The tenant is suspended.** **\"This tenant is suspended, so its machines cannot\n  move or be placed.\"**\n- **The tenant has used its machines across the cluster.** **\"This tenant has used\n  all of its machines across the cluster.\"** (see [the tenant quota](/docs/tenants#the-tenant-quota))\n- **Its licence does not allow the change.** **\"This member's licence does not allow\n  this change.\"**\n- **It is in maintenance.** **\"This member is in maintenance, so nothing is placed on it and nothing moves onto it.\"** (see [Maintenance and evacuation](/docs/clustering/maintenance))\n- **Machines cannot run on it.** **\"Machines cannot run on this member right now.\"**\n- **It does not hold the image** the machine starts from. **\"The image is not on this\n  member. Copy it to this member first.\"** (see [the image library](/docs/clustering/images)).\n  A move is the exception: a member that lacks the image can take the machine when the library\n  holds a copy, and the move copies it there ([Moving machines between nodes](/docs/clustering/live-migration#choosing-the-new-member)).\n- **It already runs a machine of the same anti-affinity group.** **\"Another machine of\n  this group is on that member.\"**\n- **It does not have the room.** The machine's disk, plus 1 GiB kept free, must fit\n  in the member's disk pool. **\"This member does not have the room the machine's disk\n  needs.\"**\n- **It does not have enough free processors or memory.** The machine's vCPUs,\n  added to the vCPUs already committed there, may not exceed the member's processor\n  count times the cluster's overcommit ratio (four by default). Its memory, added to\n  the memory already committed, may not exceed the member's memory; memory is not\n  overcommitted. **\"This member does not have enough free processors or memory for the\n  machine.\"**\n- **It lacks a network the machine needs.** A cluster network counts as present on\n  every member that can carry the cluster's networks. **\"This member does not have a\n  network the machine needs.\"**\n- **It cannot carry the cluster's networks, and the machine names one.** A member carries\n  them when its traffic checks are loaded and cover its overlay address. **\"This member\n  cannot carry the cluster's networks.\"**\n- **It does not hold the public address the machine asks for.** **\"This member does\n  not hold the public address the machine asks for.\"**\n- **It cannot give the processor model the machine needs**, or, for a machine that\n  gets a named model, it is a hardware member whose processor is not reported.\n  **\"This member cannot give the machine the processor model it asks for.\"**\n- **It cannot give the firmware the machine needs** (UEFI, Secure Boot or a TPM).\n  Firmware a member has not confirmed is not offered. **\"This member cannot start a\n  machine that needs UEFI, Secure Boot or a TPM.\"**\n- **It cannot give hardware acceleration**, which the machine needs. **\"This member\n  cannot give the machine hardware acceleration.\"**\n\n- **A move would change its name servers.** A machine with name servers of its own keeps\n  them. A machine without its own takes its member's, so a member whose list differs cannot\n  take it on a move: **\"This member's name servers differ from the machine's, and the machine\n  has none of its own. Set the machine's name servers first.\"** (see\n  [Moving machines between nodes](/docs/clustering/live-migration))\n\nAmong the eligible members, the first is the one that **already holds the image**,\nthen the member with **the most memory left** after the machine, then the one with\n**the fewest machines**, and then the one with the lower member id.\n\n## The machine's processor model\n\nA machine's processor is either the processor of the member it runs on, or a\n**named model** that every member with hardware acceleration in the cluster can\nrun. The policy is a cluster setting, `cluster_cpu_policy`, with two values:\n\n- **`baseline`**, the default. A new machine created on a member with hardware\n  acceleration gets the cluster's common named model, once every member runs a version\n  that supports it, two or more members have hardware acceleration and report their\n  processors,\n  and those processors share a named model.\n- **`host`**. A new machine keeps its member's own processor.\n\nA machine created under emulation keeps the emulator's processor. A machine created\nbefore every member ran a version that supports it keeps the definition it was created with.\n\nThe model is recorded when the machine is created. Every later definition of the\nmachine uses that record: a start, and a change of its size. The policy does not\nchange a machine that already exists.\n\nWhen a machine gets a named model, placement excludes a member with hardware\nacceleration whose processor is not reported, with **\"This member cannot give the\nmachine the processor model it asks for.\"** To find the members that can give a\nnamed model, ask with `cenvero-str-ctl cluster placement --cpu-model <model>`, or\nsend `cpu_model` in the query. A member gives a named model when it reports that model, or that model with a version number (for example EPYC-Rome-v1 for EPYC-Rome).\n\n## Anti-affinity\n\nA machine can carry an **anti-affinity group**. Machines of one tenant that carry the\nsame group are kept on different members: placement does not choose a member that\nalready runs one of them, and a member refuses a second machine of its group.\n\n- **The name** is 1 to 63 lowercase letters, digits and hyphens, and starts and ends\n  with a letter or digit. Otherwise: **\"An anti-affinity group is 1 to 63 lowercase\n  letters, digits and hyphens, starting and ending with a letter or digit.\"**\n- **A group belongs to one tenant.** Two tenants can use the same group name, and\n  their machines never keep each other apart.\n- **A machine needs a tenant.** A machine with no tenant cannot take a group:\n  **\"Anti-affinity needs a machine that belongs to a tenant.\"**\n- **It needs every member to run a version that supports it.** On a node in no cluster, or while a member does not:\n  **\"Anti-affinity needs a cluster in which every member runs cluster level 5.\"**\n- **It is a hard rule.** A create whose group no member can take is refused with\n  the placement answer. A create that names a member already running the group is\n  refused with **\"Another machine of this group is on that member.\"**\n\nSet the group when you create the machine, or change it afterwards:\n\n```bash\nsudo cenvero-str-ctl vm create --name db-1 --tenant t-acme --image img-3f9a1c2e --placement auto --anti-affinity db-pair\nsudo cenvero-str-ctl vm options set db-2 --anti-affinity db-pair\nsudo cenvero-str-ctl vm options set db-2 --anti-affinity \"\"      # clear it\n```\n\nOver the API, a create takes `\"anti_affinity\": \"<group>\"`, and\n`PUT /api/v1/vms/{id}/options` takes `{\"anti_affinity\": \"<group>\"}`, with an empty\nvalue to clear it.\n\nThree limits to know:\n\n- **A clone takes no group.** A clone starts without one, and you set its group\n  yourself.\n- **Two creates for one group that are placed at the same moment on different\n  members can both succeed.** Each member refuses a second machine of the group on\n  itself, but a group that is being placed on two members at once is not yet seen by\n  both.\n- **A group keeps machines apart; it does not bring them together.**\n\nIn the console, the create wizard offers the group once a tenant is chosen, and a\nmachine's Options tab shows the field for a tenant's machine once every member runs a\nversion that supports it.\n\n## Who can do what\n\n| Action | Privilege | Licence |\n|---|---|---|\n| Read a placement answer | `VM.Audit` | none (reads are never refused) |\n| Create a machine, placed or named | `VM.Allocate` | `compute` |\n| Set a machine's anti-affinity group | `VM.Config.Options` | `compute` |\n\nA tenant's key cannot use the placement route; it answers **403**.\n\n## See also\n\n- [The cluster image library](/docs/clustering/images) — the images a member holds.\n- [Moving machines between nodes](/docs/clustering/live-migration) — moving a machine that already exists, with the same rules.\n- [Maintenance and evacuation](/docs/clustering/maintenance) — taking a member out of placement.\n- [Cluster networks](/docs/networking/cluster-networks) — networks that span members.\n- [Virtual machines](/docs/compute/virtual-machines) — the create flags, on a single node.\n- [Tenants](/docs/tenants#the-tenant-quota) — the machine limit across the cluster.\n- [CLI Reference](/docs/cli#cluster) and [API Reference](/docs/api#cluster).\n"
        }
    ]
}