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

# POST /v2/PreviewClusterLayoutChanges

`POST /v2/PreviewClusterLayoutChanges`

Computes a new layout taking into account the staged parameters, and returns it with detailed statistics. The new layout is not applied in the cluster.

*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.*

## Response `200`

Information about the new layout

- union
  - object
    - `error` string, required — Error message indicating that the layout could not be computed with the provided configuration
  - object
    - `message` string[], required — Plain-text information about the layout computation (do not try to parse this)
    - `newLayout` 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
    - `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)