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

# POST /v2/UpdateClusterLayout

`POST /v2/UpdateClusterLayout`

Send modifications to the cluster layout. These modifications will be included in the staged role changes, visible in subsequent calls of `GET /GetClusterHealth`. Once the set of staged changes is satisfactory, the user may call `POST /ApplyClusterLayout` to apply the changed changes, or `POST /RevertClusterLayout` to clear all of the staged changes in the layout.

Setting the capacity to `null` will configure the node as a gateway.
Otherwise, capacity must be now set in bytes (before Garage 0.9 it was arbitrary weights).
For example to declare 100GB, you must set `capacity: 100000000000`.

Garage uses internally the International System of Units (SI), it assumes that 1kB = 1000 bytes, and displays storage as kB, MB, GB (and not KiB, MiB, GiB that assume 1KiB = 1024 bytes).

## Request body

- UpdateClusterLayoutRequest
  - `parameters` 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.
  - `roles` NodeRoleChangeRequest[] — New node roles to assign or remove in the cluster layout
    - union
      - object
        - `id` string, required — ID of the node for which this change applies
        - `remove` boolean, required — Set `remove` to `true` to remove the node from the layout
      - 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

## Response `200`

Proposed changes have been added to the list of pending changes

- UpdateClusterLayoutResponse
  - `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

## 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)