---
title: "POST /v2/ApplyClusterLayout"
method: POST
path: "/v2/ApplyClusterLayout"
tags: ["Cluster layout"]
---

# POST /v2/ApplyClusterLayout

`POST /v2/ApplyClusterLayout`

Applies to the cluster the layout changes currently registered as staged layout changes.

*Note: do not try to parse the `message` field of the response, it is given as an array of string specifically because its format is not stable.*

## Request body

- ApplyClusterLayoutRequest
  - `version` integer, required — As a safety measure, the new version number of the layout must be specified here

## Response `200`

The updated cluster layout has been applied in the cluster

- ApplyClusterLayoutResponse
  - `layout` GetClusterLayoutResponse, required
    - `parameters` LayoutParameters, required
      - `zoneRedundancy` union, required
        - object — Partitions must be replicated in at least this number of distinct zones.
          - `atLeast` integer, required — Partitions must be replicated in at least this number of distinct zones.
        - 'maximum' — Partitions must be replicated in as many zones as possible: as many zones as there are replicas, if there are enough distinct zones, or at least one in each zone otherwise.
    - `partitionSize` integer, required — The size, in bytes, of one Garage partition (= a shard)
    - `roles` LayoutNodeRole[], required — List of nodes that currently have a role in the cluster layout
      - `capacity` integer, nullable — Capacity (in bytes) assigned by the cluster administrator, absent for gateway nodes
      - `id` string, required — Identifier of the node
      - `storedPartitions` integer, nullable — Number of partitions stored on this node (a result of the layout computation)
      - `tags` string[], required — List of tags assigned by the cluster administrator
      - `usableCapacity` integer, nullable — Capacity (in bytes) that is actually usable on this node in the current layout, which is equal to `stored_partitions` × `partition_size`
      - `zone` string, required — Zone name assigned by the cluster administrator
    - `stagedParameters` LayoutParameters
      - `zoneRedundancy` union, required
        - object — Partitions must be replicated in at least this number of distinct zones.
          - `atLeast` integer, required — Partitions must be replicated in at least this number of distinct zones.
        - 'maximum' — Partitions must be replicated in as many zones as possible: as many zones as there are replicas, if there are enough distinct zones, or at least one in each zone otherwise.
    - `stagedRoleChanges` NodeRoleChange[], required — List of nodes that will have a new role or whose role will be removed in the next version of the cluster layout
      - union
        - object
          - `remove` boolean, required — Set `remove` to `true` to remove the node from the layout
          - `id` string, required — ID of the node for which this change applies
        - object
          - `capacity` integer, nullable — Capacity (in bytes) assigned by the cluster administrator, absent for gateway nodes
          - `tags` string[], required — List of tags assigned by the cluster administrator
          - `zone` string, required — Zone name assigned by the cluster administrator
          - `id` string, required — ID of the node for which this change applies
    - `version` integer, required — The current version number of the cluster layout
  - `message` string[], required — Plain-text information about the layout computation (do not try to parse this)
  - `statistics` ComputationStat
    - `effectiveCapacity` integer, required — The final effective capacity of the cluster, accounting for replication
    - `effectiveZoneRedundancy` integer, required — The zone redundancy factor achieved by this layout
    - `lowPartitionSize` boolean, required — Warning flag indicating when partitions are very small
    - `lowUsableCapacity` boolean, required — Warning flag indicating that the raw node capacity could not be used effectively
    - `partitionSize` integer, required — The size of a partition, in bytes
    - `previousPartitionSize` integer, nullable — The size of a partition, in bytes, in the previous layout
    - `replicationFactor` integer, required — The cluster's replication factor
    - `totalCapacity` integer, required — The total raw capacity of nodes
    - `totalMovedPartitions` integer, nullable — The total number of partitions that will be moved to a new storage node
    - `usableCapacity` integer, required — The portion of total raw node capacity that is used by partitions
    - `zones` ComputationStatZone[], required — Per-zone storage statistics
      - `name` string, required — The name of the zone
      - `nodes` ComputationStatNode[], required — Per-node storage statistics for nodes in this zone
        - `id` string, required — The node's ID
        - `newPartitions` integer, required — The number of partitions that are newly replicated on this node
        - `storedPartitions` integer, required — The number of partitions that are replicated on this node
        - `tags` string[], required — The node's tags as defined in the layout
        - `totalCapacity` integer, required — The node's raw capacity
        - `usableCapacity` integer, required — The portion of the node's raw capacity that is used by partitions it stores
      - `totalCapacity` integer, required — The total raw capacity of nodes in this zone
      - `totalReplicatedPartitions` integer, required — The total number of partition replicas in this zone
      - `uniquePartitions` integer, required — The number of unique partitions that have at least one replica in this zone
      - `usableCapacity` integer, required — The used portion of the raw capacity of nodes in this zones

## Other responses

- `500` — Internal server error

---

[API](https://skmtc.dev/deuxfleurs/apis/garage-administration-api.md) · [All operations](https://skmtc.dev/deuxfleurs/apis/garage-administration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/deuxfleurs/garage-administration-api/revisions/07ffb2d0febb/schema)