Managing PostgreSQL cluster hosts

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

By default, the CLI uses the folder specified when creating the 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 parameter.

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

yc managed-postgresql host list \
  --cluster-name <cluster_name>

Result:

+----------------------------+----------------------+---------+--------+--------------------+
|            NAME            |      CLUSTER ID      |  ROLE   | HEALTH |      ZONE ID       |
+----------------------------+----------------------+---------+--------+--------------------+
| rc1b***mdb.yandexcloud.net | c9qp71dk1dfg******** | MASTER  | ALIVE  | ru-central1-b      |
| rc1a***mdb.yandexcloud.net | c9qp71dk1dfg******** | REPLICA | ALIVE  | ru-central1-a      |
+----------------------------+----------------------+---------+--------+--------------------+

You can get the cluster name from the folder’s cluster list.

1. Get an IAM token for API authentication and place it in an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Cluster.ListHosts method, for instance, via the following cURL request:

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

   You can get the cluster ID from the folder’s cluster list.

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

1. Get an IAM token for API authentication and place it in 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 the repository contents are stored in the ~/cloudapi/ directory.

3. Call the ClusterService.ListHosts method, for instance, via the following gRPCurl request:

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

   You can get the cluster ID from the folder’s cluster list.

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

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

By default, the CLI uses the folder specified when creating the 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 parameter.

To create a host:

1. To choose a subnet for your new host, first 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]  |
   | e9b0phq1w2e3******** | a-2       | enp6rq71w2e3******** | ru-central1-a | [172.16.**.**/20] |
   | 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 a host:

   yc managed-postgresql host add --help
   

3. Run the command for adding a host:

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

   If your availability zone contains multiple subnets, make sure to specify the subnet ID; otherwise, Managed Service for PostgreSQL will select the subnet automatically. You can get the cluster name from the folder’s cluster list.

   You can specify extra options in the --host argument to manage public access to the host and cluster replication:

   • Use the host’s replication-source option for manual replication stream management.
   • Use the assign-public-ip option to make the host accessible from outside Yandex Cloud:
     • true: Public access enabled.
     • false: Public access disabled.

Managed Service for PostgreSQL will start the host addition process.

To create a host:

1. Open the current Terraform configuration file describing your infrastructure.

   To learn how to create this file, see Creating clusters.

   For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

2. Add a host section to the Managed Service for PostgreSQL cluster description:

   resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
     ...
     host {
       name                    = "<host_name>"
       zone                    = "<availability_zone>"
       subnet_id               = "<subnet_ID>"
       replication_source_name = "<replication_source>"
       assign_public_ip        = <public_access_to_host>
     }
   }
   

   Where:

   • name: Host name.
   • zone: Availability zone.
   • subnet_id: Subnet ID.
   • replication_source_name: Replication source, i.e., the name attribute of the relevant host section.
   • assign_public_ip: Public access to the host, true or false.

3. Validate your configuration.

   1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Confirm resource changes.

   1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

   Timeouts

   The Terraform provider sets the following timeouts for Managed Service for PostgreSQL cluster operations:

   • Creating a cluster, including restoration from a backup: 30 minutes.
   • Updating a cluster: 60 minutes.
   • Deleting a cluster: 15 minutes.

   Operations exceeding the timeout are aborted.

   How can I change these timeouts?

   Add a timeouts section to the cluster description, e.g.:

   resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # 1 hour 30 minutes
       update = "2h"    # 2 hours
       delete = "30m"   # 30 minutes
     }
   }
   

1. Get an IAM token for API authentication and place it in an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Cluster.AddHosts method, for instance, 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-postgresql/v1/clusters/<cluster_ID>/hosts:batchCreate' \
     --data '{
               "hostSpecs": [
                 {
                   "zoneId": "<availability_zone>",
                   "subnetId": "<subnet_ID>",
                   "assignPublicIp": <allow_public_access_to_host>,
                   "replicationSource": "<host_FQDN>",
                   "priority": "<host_priority>",
                   "configSpec": {
                     "postgresqlConfig_<PostgreSQL_version>": {
                       <PostgreSQL_settings>
                     }
                   }
                 },
                 { <similar_settings_for_new_host_2> },
                 { ... },
                 { <similar_settings_for_new_host_N> }
               ]
             }'
   

   Where hostSpecs is an 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: Internet access to the host via a public IP address, true or false.

   • replicationSource: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

   • priority: Host priority relative to all other hosts.

   • configSpec.postgresqlConfig_<PostgreSQL_version>: PostgreSQL settings. Specify each setting on a separate line, separated by commas.

     See the method description for the list of PostgreSQL versions supporting this option. See PostgreSQL settings for descriptions and possible values of the settings.

   You can get the cluster ID from the folder’s cluster list.

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

1. Get an IAM token for API authentication and place it in 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 the repository contents are stored in the ~/cloudapi/ directory.

3. Call the ClusterService.AddHosts method, for instance, via the following gRPCurl request:

   grpcurl \
     -format json \
     -import-path ~/cloudapi/ \
     -import-path ~/cloudapi/third_party/googleapis/ \
     -proto ~/cloudapi/yandex/cloud/mdb/postgresql/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>,
               "replication_source": "<host_FQDN>",
               "priority": "<host_priority>",
               "config_spec": {
                 "postgresql_config_<PostgreSQL_version>": {
                   <PostgreSQL_settings>
                 }
               }
             },
             { <similar_settings_for_new_host_2> },
             { ... },
             { <similar_settings_for_new_host_N> }
           ]
         }' \
     mdb.api.cloud.yandex.net:443 \
     yandex.cloud.mdb.postgresql.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: Internet access to the host via a public IP address, true or false.

   • replication_source: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

   • priority: Host priority relative to all other hosts.

   • config_spec.postgresql_config_<PostgreSQL_version>: PostgreSQL settings. Enter each setting on a new line, separated by commas.

     See the method description for the list of PostgreSQL versions supporting this option. See PostgreSQL settings for descriptions and possible values of the settings.

   You can get the cluster ID from the folder’s cluster list.

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

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

By default, the CLI uses the folder specified when creating the 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 parameter.

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

yc managed-postgresql host update <host_name> \
  --cluster-name <cluster_name> \
  --replication-source <source_host_name> \
  --assign-public-ip=<public_access_to_host>

Where:

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

You can get the host name from the cluster’s host list, and the cluster name from the folder’s cluster list.

For manual replication stream management within your cluster, change the value of the host's --replication-source argument.

To change the cluster host settings:

1. Open the current Terraform configuration file describing your infrastructure.

   To learn how to create this file, see Creating clusters.

   For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

2. In the Managed Service for PostgreSQL cluster description, change the attributes of the host block referring to the host you want to update.

   resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
     ...
     host {
       replication_source_name = "<replication_source>"
       assign_public_ip        = <public_access_to_host>
     }
   }
   

Where:

• replication_source_name: Replication source, i.e., the name attribute of the relevant host section.
• assign_public_ip: Public access to the host, true or false.

1. Validate your configuration.

   1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

2. Confirm resource changes.

   1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

   Timeouts

   The Terraform provider sets the following timeouts for Managed Service for PostgreSQL cluster operations:

   • Creating a cluster, including restoration from a backup: 30 minutes.
   • Updating a cluster: 60 minutes.
   • Deleting a cluster: 15 minutes.

   Operations exceeding the timeout are aborted.

   How can I change these timeouts?

   Add a timeouts section to the cluster description, e.g.:

   resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # 1 hour 30 minutes
       update = "2h"    # 2 hours
       delete = "30m"   # 30 minutes
     }
   }
   

1. Get an IAM token for API authentication and place it in an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Cluster.UpdateHosts method, for instance, 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-postgresql/v1/clusters/<cluster_ID>/hosts:batchUpdate' \
     --data '{
               "updateHostSpecs": [
                 {
                   "updateMask": "assignPublicIp,replicationSource,priority,configSpec.postgresqlConfig_<PostgreSQL_version>",
                   "hostName": "<host_FQDN>",
                   "assignPublicIp": <allow_public_access_to_host>,
                   "replicationSource": "<host_FQDN>",
                   "priority": "<host_priority>",
                   "configSpec": {
                     "postgresqlConfig_<PostgreSQL_version>": {
                       <PostgreSQL_settings>
                     }
                   }
                 },
                 { <similar_settings_for_host_2_being_changed> },
                 { ... },
                 { <similar_settings_for_host_N_being_changed> }
               ]
             }'
   

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

   • updateMask: Comma-separated list of settings you want to update.

   • hostName: Target host FQDN.

   • assignPublicIp: Internet access to the host via a public IP address, true or false.

   • replicationSource: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

   • priority: Host priority relative to all other hosts.

   • configSpec.postgresqlConfig_<PostgreSQL_version>: PostgreSQL settings. Specify each setting on a separate line, separated by commas.

     See the method description for the list of PostgreSQL versions supporting this option. See PostgreSQL settings for descriptions and possible values of the settings.

   You can get the cluster ID from the folder’s cluster list.

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

1. Get an IAM token for API authentication and place it in 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 the repository contents are stored in the ~/cloudapi/ directory.

3. Call the ClusterService.UpdateHosts method, for instance, 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/postgresql/v1/cluster_service.proto \
     -rpc-header "Authorization: Bearer $IAM_TOKEN" \
     -d '{
           "cluster_id": "<cluster_ID>",
           "update_host_specs": [
             {
               "update_mask": {
                   "paths": [
                     "assign_public_ip",
                     "replication_source",
                     "priority",
                     "config_spec.postgresql_config_16"
                   ]
               },
               "host_name": "<host_FQDN>",
               "assign_public_ip": <allow_public_access_to_host>,
               "replication_source": "<host_FQDN>",
               "priority": "<host_priority>",
               "config_spec": {
                 "postgresql_config_<PostgreSQL_version>": {
                   <PostgreSQL_settings>
                 }
               }
             }
           ]
         }' \
     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 you want to update as an array of strings (paths[]).

   • host_name: Target host FQDN.

   • assign_public_ip: Internet access to the host via a public IP address, true or false.

   • replication_source: Host’s replication source for manual replication stream management. Specify the FQDN of the host that will be used as the replication source.

   • priority: Host priority relative to all other hosts.

   • config_spec.postgresql_config_<PostgreSQL_version>: PostgreSQL settings. Specify each setting on a separate line, separated by commas.

     See the method description for the list of PostgreSQL versions supporting this option. See PostgreSQL settings for descriptions and possible values of the settings.

   You can get the cluster ID from the folder’s cluster list.

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

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

By default, the CLI uses the folder specified when creating the 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 parameter.

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

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

You can get the host name from the list of cluster hosts, and the cluster name from the folder’s cluster list.

To delete a host from a cluster:

1. Open the current Terraform configuration file describing your infrastructure.

   To learn how to create this file, see Creating clusters.

   For a complete list of configurable Managed Service for PostgreSQL cluster fields, refer to the Terraform provider guides.

2. Delete the host section referring to the host you want to delete from the Managed Service for PostgreSQL cluster description.

3. Validate your configuration.

   1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Type yes and press Enter.

   1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

   Timeouts

   The Terraform provider sets the following timeouts for Managed Service for PostgreSQL cluster operations:

   • Creating a cluster, including restoration from a backup: 30 minutes.
   • Updating a cluster: 60 minutes.
   • Deleting a cluster: 15 minutes.

   Operations exceeding the timeout are aborted.

   How can I change these timeouts?

   Add a timeouts section to the cluster description, e.g.:

   resource "yandex_mdb_postgresql_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # 1 hour 30 minutes
       update = "2h"    # 2 hours
       delete = "30m"   # 30 minutes
     }
   }
   

1. Get an IAM token for API authentication and place it in an environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Call the Cluster.DeleteHosts method, for instance, 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-postgresql/v1/clusters/<cluster_ID>/hosts:batchDelete' \
     --data '{
               "hostNames": [
                 "<host_FQDN>"
               ]
             }'
   

   Where hostNames is an array of strings, each containing an FQDN of the host targeted for deletion.

   You can get the cluster ID from the folder’s cluster list.

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

1. Get an IAM token for API authentication and place it in 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 the repository contents are stored in the ~/cloudapi/ directory.

3. Call the ClusterService.DeleteHosts method, for instance, via the following gRPCurl request:

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

   Where host_names is an array of strings, each containing an FQDN of the host targeted for deletion.

   You can get the cluster ID from the folder’s cluster list.

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