Manage instance groups

Describes how to create PostgreSQL instance groups and manage connection, volumes, and parameter groups.

Log storage management

To operate PostgreSQL instance groups stably, we recommend regularly monitoring and managing log storage usage so that it does not exceed 80%. If usage exceeds a certain level, old archived WAL files (archive logs) may be deleted to ensure service stability.

Create PostgreSQL instance group

A PostgreSQL instance group is an object that manages the lifecycle of instances and backups. It has various status values, including operational and terminated states, which users can view and manage.

To create an instance group in the PostgreSQL service:

1. Go to the KakaoCloud console > Data Store > PostgreSQL.

2. Click [Create instance group].

3. Enter the required information, then click [Create].

   Item	Category	Description
   Basic settings	Instance group name	Name of the PostgreSQL instance group - Must be unique within the same project - Example: postgresql-instance-01
   	Description (optional)	Optional description up to 100 characters
   Instance availability	High availability (Primary, Standby instances)	Creates a Primary instance and multiple Standby instances - Single AZ or multi-AZ
   	Single (Primary instance)	Creates only one Primary instance - Single AZ only
   PostgreSQL settings	Engine version	PostgreSQL database version is selected automatically - 14.14, 14.17 are available
   	Primary port	Port used to communicate with the PostgreSQL Primary instance. You can specify a port in the 1024-65535 range. - Default: 5432 * Reserved ports cannot be used
   	Standby port	Port used to communicate with PostgreSQL Standby instances. Specify this when high availability is selected. - Default: 5433 * Reserved ports cannot be used
   	ID	ID of the PostgreSQL database user account - Example: admin * Reserved account names (root, postgres, replication, rewind, orafce_set_umask, plprofiler) cannot be used
   	Password	Initial password for the PostgreSQL database user account - Format: 8-16 characters - Spaces and /, ', ", @ cannot be used ⚠️ The administrator account password can be changed after the database starts ⚠️ Administrator account passwords changed by users after database startup cannot be retrieved
   Parameter group		Select a parameter group that matches the selected engine version
   Instance type		Select an instance type for database compute resources - For more information, see Instance types
   Base storage	SSD	Configure the volume type and size used by the database - Volume type: Currently, only SSD is supported. Other types will be supported in the future. - Volume size: You can create volumes from 100 GB to 16,384 GB. * The minimum capacity may vary depending on the selected instance type.
   Log storage	SSD	Storage used for database logs. The type cannot be changed after creation. - Volume type: Currently, only SSD is supported. Other types will be supported in the future. - Volume size: You can create volumes from 100 GB to 16,384 GB. * The minimum capacity may vary depending on the selected instance type.
   Network settings	Multi-AZ option	Option available when high availability is selected. Specify subnets and the number of instances for each AZ.
   	VPC	Select the network where the PostgreSQL instance database is configured
   	Subnet and instance count settings	Select the subnet for the Primary instance and the subnet for Standby instances, then enter the number of instances - Up to 6 instances can be created per instance group - We recommend creating at least 2 instances in the subnet where the Primary instance is created for data redundancy
   	Security group	Create a new security group or select existing security groups to apply to the instance group - Multiple selections are allowed
   Automatic backup	Automatic backup option	Whether to use automatic backup. When enabled, backups run automatically once a day.
   	Backup retention period	Automatic backup retention period. You can select from 1 to 35 days. - Changes the retention period for all automatic backups created in the instance group
   	Automatic backup start time	Automatic backup start time. Backup starts within 15 minutes from the selected time.

Creation and usage notes

• If instance group creation fails due to unexpected causes such as network errors or insufficient resources, you can check the history in Cloud Trail.
• Even if you expand a volume after creating an instance group, the maximum IOPS is fixed at the initially specified value. To ensure stable performance, set an appropriate volume size when creating the instance group.
• KakaoCloud PostgreSQL recommends creating and using a new database after creating an instance group.
  New databases are created based on template1, and all extensions provided by KakaoCloud PostgreSQL can be used without additional work, such as restarting the database.

User accounts in instance groups

When creating a PostgreSQL instance group, users can create a user account with the ID and password they set.
This account has the Admin role and can access resources after authentication. The role and privileges of the user account are as follows:

Reserved accounts

• User accounts cannot be created with account IDs reserved for management (root, postgres, replication, rewind, orafce_set_umask, plprofiler).
• If the replication account is deleted, high availability mode may not operate properly.

Type	Privileges
User account	Create role, Create DB, Bypass RLS, Password valid until infinity

Connect to PostgreSQL instance group

This section describes how to access an instance group by using PostgreSQL Client.
After creating a PostgreSQL instance group and configuring the access environment, you can access it from PostgreSQL Client by entering the endpoint and user account information.

Prepare the access environment

To access a PostgreSQL instance group, prepare the following access environment:

• A virtual machine (VM) instance that uses the same network as the PostgreSQL instance group you want to access
• Security group settings that allow access to the endpoint of the PostgreSQL instance group

Allow the port configured when the instance group was created in the connected security group.

• If the user specified a port: the specified port in the 1024-65535 range
• If the default ports are used: Primary instance TCP 5432, Standby instance TCP 5433

Access instance group

You can access the instance group by using PostgreSQL Client.

1. Refer to Virtual Machine > Create and connect to instance to access a VM instance and prepare PostgreSQL Client. If the PostgreSQL command is not recognized, install PostgreSQL Client separately.

2. Go to the KakaoCloud console > Data Store > PostgreSQL.

3. From the Instance Group menu, select the PostgreSQL instance group to access.

4. In the Details tab, check the Endpoint and user account ID. This information is required when running PostgreSQL commands, so copy it to the clipboard or prepare it in advance.

5. To access the instance group through PostgreSQL Client, run the PostgreSQL access command from the VM instance you created.

   PostgreSQL instance group access method 1

   PGPASSWORD={USER_PASSWORD} psql -h {ENDPOINT} -U {USER_ID} -d {DATABASE} -p {PORT}

   PostgreSQL instance group access method 2

   psql postgresql://{USER_ID}:{USER_PASSWORD}@{ENDPOINT}:{PORT}/{DATABASE}

   Item	Description
   {USER_ID}	Database user ID - ID of the DB administrator account used to access the PostgreSQL instance
   {USER_PASSWORD}	Password of the administrator account used to access the PostgreSQL instance - Password entered when creating PostgreSQL
   {ENDPOINT}	Endpoint information checked in the Details tab - Endpoint of the PostgreSQL instance group
   {DATABASE}	Name of the database to access - KakaoCloud creates the postgres database by default - If the user created a separate database, enter that database name to access it
   {PORT}	Port number set when creating the instance group - Default ports: Primary 5432, Standby 5433 * Reserved ports cannot be used

Failover and restart

If the Primary instance changes due to automatic or manual failover or restart, internal access information may change and access may be temporarily interrupted.

Manage instance groups

This section describes how to manage active PostgreSQL instances and instance groups.

Storage-Full and Storage-Error

If the instance group status is Storage-Full (Log or Data disk usage of an instance in the PostgreSQL instance group is 85% or higher, or available capacity is 30 GB or less), or the instance status is Storage-Error (Log or Data disk usage is 95% or higher, or available capacity remains 10 GB or less for more than 5 minutes), only volume expansion can be performed to ensure service stability.

View PostgreSQL instance group list

You can view a list of currently running PostgreSQL instance groups.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.

2. From the Instance Group menu, view the instance group list.

   Item	Description
   Instance group name	PostgreSQL instance group name entered during creation - Click the instance group to view details
   Status	PostgreSQL instance group status - For more information, see Instance group
   Engine version	PostgreSQL database version selected during creation
   Instance type	PostgreSQL instance type selected during creation
   Availability	Instance availability selected during creation
   Multi-AZ	Whether multi-AZ is used
   Automatic backup retention period	Configured automatic backup retention period - Hover to check the start time
   Created at	Creation date and time of the PostgreSQL instance group
   Created by	User who first created the PostgreSQL instance
   [⋮] button	Start: Start all stopped instances in the instance group and transition the instance group to Available Stop: Stop all instances in the instance group for up to 14 days Set automatic backup: Configure automatic backup settings, whether to use automatic backup, retention period, and backup start time Expand volume: Expand PostgreSQL instance group volumes (base and log storage) Change parameter group: Change the parameter group applied to the instance group Modify security groups: Modify security groups applied to the instance group Change instance type: Change the instance type of the instance group Manual failover: Perform failover for the instance group (only works in high availability) Create backup: Create a backup for the instance group Delete: Return the instance resources included in the PostgreSQL instance group and delete backups

View PostgreSQL instance group details

You can view details of a PostgreSQL instance group.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.

2. From the Instance Group menu, select the PostgreSQL instance group whose details you want to view.

3. View the details of the selected PostgreSQL instance group.

   Tab	Description
   Details	Instance group, connected network, backup, and PostgreSQL settings information
   Instances	List and information of instances included in the instance group
   Topology	Topology where PostgreSQL resources and network structure can be viewed
   Security	Security groups connected to the instance group
   Backup	Backups created for the instance group
   Monitoring	Monitoring information for the instance group

PostgreSQL instance group security groups

View security groups

In the Security tab of the details page, you can view the security groups applied to the instance group and their detailed policies. To access an instance group, the port specified in the security group must be allowed. Click a connected security group name in the list to go to the VPC > Security Group details page for policy management. You can select up to 20 security groups.

Modify security groups

You can modify the security groups connected to an instance group. At least one security group must be connected.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.

2. From the Instance Group menu, select [⋮] button > Modify security groups for the instance group to configure.

3. In the Modify security groups popup, select the security groups to apply to the instance group.

   Item	Description
   Selected instance group name	Name of the instance group whose security groups are being modified
   Select security groups	Select security groups to apply. Selected security groups are displayed as chips below the selection box.
   Applied rules	View inbound and outbound rules for each security group

4. Click [Apply].

Guide

You can manage inbound and outbound rules in VPC > Security Group.

Expand PostgreSQL instance group volumes

Expand the volumes of a PostgreSQL instance group. Both base and log storage can be expanded up to 16 TB (16,384 GB).

Log storage usage

We recommend regularly monitoring and managing log storage usage so that it does not exceed 80%.
In KakaoCloud Alert Center, you can set alert policies based on disk usage or usage rate. In PostgreSQL instance group details, volume expansion is guided through Expand volume when usage reaches 85% or higher.
If storage usage reaches 90% or higher, old archived WAL files (archive logs) are deleted to ensure service stability.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Expand volume for the instance group to expand.
3. Enter the storage size to expand for base or log storage, then click [OK].

Volume expansion events

• Volume expansion means increasing disk capacity. Maximum IOPS does not increase. Support for increasing maximum IOPS based on expanded volume size is planned for the future.
• When volume expansion is complete, the Cloud Trail Instance Group Volume Extend End event occurs. If any instance fails volume expansion, the information can be checked in Additional Info in the Cloud Trail log. For instances that failed volume expansion, the Instance Volume Extend End event occurs based on retry behavior. For more information, see Cloud Trail, PostgreSQL events.

Change parameter group

You can change the parameter group connected to an instance group.
When changing a parameter group, select one that matches the engine version of the instance group. If parameter values change, the PostgreSQL service currently in operation may be affected. Therefore, we recommend checking the parameter values to be applied before making changes.

If a parameter group change is already in progress, additional change requests may fail. For more information, see the Parameter group document.

Caution

• If you change from a predeploy parameter group to another parameter group where pgaudit is enabled, PostgreSQL restarts once to apply the setting changes.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Change parameter group for the instance group to change.
3. In the Change parameter group popup, select the parameter group to change to, then click [OK].

Change instance type

You can change the instance type of an instance group to one of the specifications provided by the PostgreSQL service.
Depending on the situation, you can change to a higher or lower specification. When changed, the type of every instance in the instance group is changed.
If the type change fails, all instances are reverted to their previous specifications. For details, check the additional event log of the Instance Group Scaling Up/Down Error event in Cloud Trail.

Caution

• Switchover occurs during an instance type change, and temporary interruption may occur.
• Check workload and memory usage before changing. If workload is high or the memory of the target specification is insufficient for current usage, data loss, performance degradation, or change request failure may occur.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Change instance type for the instance group to change.
3. In the popup, select the instance type to change to, then click [Change].

Stop and start PostgreSQL instance group

PostgreSQL supports stopping and starting instance groups for cost optimization and short-term testing.
You can stop an instance group for up to 14 days, after which it automatically restarts. Most instance group features are restricted while stopped. After you start the stopped instance group and it becomes Available, you can use it normally. Start is available when at least one instance in the instance group is in the Stopped state.

Instance group status when stopped or started

Action	Description	Instance group status after execution
Start	Start all stopped instances in the instance group and transition the instance group to Available	Starting -> Available
Stop	Stop all instances in the instance group for up to 14 days	Stopping -> Stopped

Stop instance group

When you stop an instance group, all instances included in the instance group are stopped, which may affect services using the instance group.
When an instance group is in the Stopped state, hover over the status to check the expected restart time.

Caution

• Even when an instance group is stopped, storage and manual backup charges are incurred.
• If automatic backup is enabled, it is switched to unused and all existing automatic backups are deleted.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Stop for the instance group to stop.
3. In the popup, review and select the stop precautions. To create a manual backup before stopping, select the manual backup creation option. Click [OK].

Start instance group

Guide

When starting an instance group after a long stop period, it may take some time for the instance group to transition to the Available state.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Start for the stopped instance group.
3. Check the information in the popup, then click [OK].

Delete PostgreSQL instance group

You can delete PostgreSQL instance groups that are no longer needed.
When deleting a PostgreSQL instance group, all instances are stopped and the user's instances are fully returned. After the instance group is deleted, resource usage charges are no longer incurred.

Cannot be recovered after deletion

The instance resources and backups of a deleted PostgreSQL instance group are fully returned after deletion and cannot be recovered.

1. Go to the KakaoCloud console > Data Store > PostgreSQL.
2. From the Instance Group menu, select [⋮] button > Delete for the PostgreSQL instance group to delete.
3. Enter the information in the popup, then click [Delete].