Contact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.

Managing Sharded PostgreSQL cluster hosts

Written by
Updated at March 25, 2026

You can manage the Managed Service for Sharded PostgreSQL cluster hosts, including the following operations:

Getting a list of cluster hosts

  1. Go to Yandex Managed Service for Sharded PostgreSQL.
  2. Click the name of your cluster and select the Hosts tab.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id options.

To get a list of cluster hosts, run this command:

yc managed-sharded-postgresql hosts list \
  --cluster-name <cluster_name>

Result:

+----------------------------+----------------------+---------+--------+--------------------+-----------+
|            NAME            |      CLUSTER ID      |  ROLE   | HEALTH |      ZONE ID       | PUBLIC IP |
+----------------------------+----------------------+---------+--------+--------------------+-----------+
| rc1b***mdb.yandexcloud.net | c9qp71dk1dfg******** | PRIMARY | ALIVE  | ru-central1-b      | true      |
| rc1a***mdb.yandexcloud.net | c9qp71dk1dfg******** | PRIMARY | ALIVE  | ru-central1-a      | false     |
+----------------------------+----------------------+---------+--------+--------------------+-----------+

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.ListHosts method, e.g., via the following cURL request:

    curl \
  --request GET \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>/hosts'

  3. View the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.ListHosts method, e.g., via the following gRPCurl request:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>"
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.ListHosts

  4. Check the server response to make sure your request was successful.

Creating a host

The number of INFRA, ROUTER, and COORDINATOR hosts in the Managed Service for Sharded PostgreSQL clusters is limited by the CPU and RAM quotas available to database clusters in your cloud. To review your resource usage, open the Quotas page and find the Managed Databases section.

To create a host:

  1. Navigate to the Yandex Managed Service for Sharded PostgreSQL service.

  2. Click the cluster name and navigate to the Hosts tab.

  3. Click Create host.

  4. Specify the following host settings:

    • Availability zone.
    • Subnet (if the required subnet is not on the list, create it).
    • Host type: INFRA (for a cluster with standard sharding), ROUTER, or COORDINATOR (for a cluster with advanced sharding).
    • To make the host accessible from outside Yandex Cloud, select Public access.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id options.

To create a host:

  1. To choose a subnet for your new host, get the list of all cluster subnets:

    yc vpc subnet list

    Result:

    +----------------------+-----------+----------------------+---------------+-------------------+
|          ID          |   NAME    |      NETWORK ID      |      ZONE     |      RANGE        |
+----------------------+-----------+----------------------+---------------+-------------------+
| b0cl69q1w2e3******** | default-d | enp6rq71w2e3******** | ru-central1-d | [172.16.**.**/20] |
| e2lkj9q1w2e3******** | default-b | enp6rq71w2e3******** | ru-central1-b | [10.10.**.**/16]  |
| e9b9v2q1w2e3******** | default-a | enp6rq71w2e3******** | ru-central1-a | [172.16.**.**/20] |
+----------------------+-----------+----------------------+---------------+-------------------+

    If the required subnet is not on the list, create it.

  2. See the description of the CLI command for adding new hosts:

    yc managed-sharded-postgresql hosts add --help

  3. Run this command to add a host:

    yc managed-sharded-postgresql hosts add \
  --cluster-name <cluster_name> \
  --host zone-id=<availability_zone>,subnet-id=<subnet_ID>,type=<host_type>

    If your availability zone contains more than one subnet, make sure to specify the subnet ID; otherwise, Managed Service for Sharded PostgreSQL will automatically select a single subnet.

    Possible host type values: infra (for a cluster with standard sharding), router, or coordinator (for a cluster with advanced sharding).

    You can also set the additional assign-public-ip option in --host to manage public access to the host:

    • true: Public access enabled.
    • false: Public access disabled.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.AddHosts method, e.g., via the following cURL request:

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>/hosts:batchCreate' \
  --data '{
            "hostSpecs": [
              {
                "zoneId": "<availability_zone>",
                "subnetId": "<subnet_ID>",
                "assignPublicIp": <allow_public_access_to_host>,
                "type": "<host_type>"
              },
              { <similar_settings_for_new_host_2> },
              { ... },
              { <similar_settings_for_new_host_N> }
            ]
          }'

    Where hostSpecs is the array of new hosts. Each array element contains the configuration for a single host and has the following structure:

    • zoneId: Availability zone.
    • subnetId: Subnet ID.
    • assignPublicIp: Host accessibility from the internet via a public IP address, true or false.
    • type: Host type, infra (for a cluster with standard sharding), router, or coordinator (for a cluster with advanced sharding).

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.AddHosts method, e.g., via the following gRPCurl request:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "host_specs": [
          {
            "zone_id": "<availability_zone>",
            "subnet_id": "<subnet_ID>",
            "assign_public_ip": <allow_public_access_to_host>,
            "type": "<host_type>"
          },
          { <similar_settings_for_new_host_2> },
          { ... },
          { <similar_settings_for_new_host_N> }
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.AddHosts

    Where host_specs is an array of new hosts, Each array element contains the configuration for a single host and has the following structure:

    • zone_id: Availability zone.
    • subnet_id: Subnet ID.
    • assign_public_ip: Host accessibility from the internet via a public IP address, true or false.
    • type: Host type, infra (for a cluster with standard sharding), router, or coordinator (for a cluster with advanced sharding).

  4. Check the server response to make sure your request was successful.

Updating a host

You can change public access settings for any host in a Managed Service for Sharded PostgreSQL cluster.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id options.

To update the cluster host’s settings, run the following command:

yc managed-sharded-postgresql hosts update <host_name> \
  --cluster-name <cluster_name> \
  --assign-public-ip=<public_access_to_host>

Where:

  • cluster-name: Cluster name.
  • assign-public-ip: Public access to the host, true or false.

You can get the host name with the list of hosts in the cluster.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.UpdateHosts method, e.g., via the following cURL request:

    Warning

    The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>/hosts:batchUpdate' \
  --data '{
            "updateHostSpecs": [
              {
                "updateMask": "assignPublicIp",
                "hostName": "<host_name>",
                "assignPublicIp": <allow_public_access_to_host>
              },
              { <similar_settings_for_host_2_being_changed> },
              { ... },
              { <similar_settings_for_host_N_being_changed> }
            ]
          }'

    Where updateHostSpecs is the array of hosts you are updating. Each array element contains the configuration for a single host and has the following structure:

    • updateMask: Comma-separated string of settings to update.
    • hostName: Target host name.
    • assignPublicIp: Host accessibility from the internet via a public IP address, true or false.

    You can get the host name with the list of hosts in the cluster.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.UpdateHosts method, e.g., via the following gRPCurl request:

    Warning

    The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the update_mask parameter as an array of paths[] strings.

    Format for listing settings
    "update_mask": {
    "paths": [
        "<setting_1>",
        "<setting_2>",
        ...
        "<setting_N>"
    ]
}

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "update_host_specs": [
          {
            "update_mask": {
                "paths": [
                  "assign_public_ip"
                ]
            },
            "host_name": "<host_name>",
            "assign_public_ip": <allow_public_access_to_host>
          },
          { <similar_settings_for_host_2_being_changed> },
          { ... },
          { <similar_settings_for_host_N_being_changed> }
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.postgresql.v1.ClusterService.UpdateHosts

    Where update_host_specs is an array of hosts you want to update. Each array element contains the configuration for a single host and has the following structure:

    • update_mask: List of settings to update as an array of strings (paths[]).
    • host_name: Target host name.
    • assign_public_ip: Host accessibility from the internet via a public IP address, true or false.

    You can get the host name with the list of hosts in the cluster.

  4. Check the server response to make sure your request was successful.

Deleting a host

You can remove an INFRA, ROUTER, or COORDINATOR type host from a Sharded PostgreSQL cluster if it is not the cluster’s only host of that type. To replace the only host, first create a new host and then delete the old one.

To delete a host from a cluster:

  1. Navigate to the Yandex Managed Service for Sharded PostgreSQL service.
  2. Click the name of your cluster and select the Hosts tab.
  3. Click next to the host you want to delete, select Delete, and confirm deletion.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id options.

To delete a host from a cluster, run this command:

yc managed-sharded-postgresql hosts delete <host_name> \
  --cluster-name <cluster_name>

You can get the host name with the list of hosts in the cluster.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Call the Cluster.DeleteHosts method, e.g., via the following cURL request:

    curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --header "Content-Type: application/json" \
  --url 'https://mdb.api.cloud.yandex.net/managed-spqr/v1/clusters/<cluster_ID>/hosts:batchDelete' \
  --data '{
            "hostNames": [
              "<host_name>"
            ]
          }'

    Where hostNames is an array of strings consisting of a single element with the host name. You can get the host name with the list of hosts in the cluster.

  3. Check the server response to make sure your request was successful.

  1. Get an IAM token for API authentication and put it into an environment variable:

    export IAM_TOKEN="<IAM_token>"

  2. Clone the cloudapi repository:

    cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi

    Below, we assume that the repository contents reside in the ~/cloudapi/ directory.

  3. Call the ClusterService.DeleteHosts method, e.g., via the following gRPCurl request:

    grpcurl \
  -format json \
  -import-path ~/cloudapi/ \
  -import-path ~/cloudapi/third_party/googleapis/ \
  -proto ~/cloudapi/yandex/cloud/mdb/spqr/v1/cluster_service.proto \
  -rpc-header "Authorization: Bearer $IAM_TOKEN" \
  -d '{
        "cluster_id": "<cluster_ID>",
        "host_names": [
          "<host_name>"
        ]
      }' \
  mdb.api.cloud.yandex.net:443 \
  yandex.cloud.mdb.spqr.v1.ClusterService.DeleteHosts

    Where host_names is an array of strings consisting of a single element with the host name. You can get the host name with the list of hosts in the cluster.

  4. Check the server response to make sure your request was successful.

Previous
Updating a cluster
Next
Managing shards