When cluster mode is disabled

The following APIs can be used when Cluster Mode is set to Disabled.

caution

• The value of the user.password field must be encrypted for the creation to succeed.

Create instance set

Create new instance set

Creates a new instance set.

Request

Create Instance Set Request Syntax

curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

Type	Parameter	Data Type	Description
Header	{token-id}*	String	Refer to API Authentication Token
	Content-Type*	String	Default content type: application/json
Body	description	String	Description of the instance set - Max 100 characters - Emojis not allowed - Line breaks (CR, LF) not allowed
	replicas*	Integer	Number of nodes - Includes both Primary and Replicas
	flavorId*	String	Flavor ID
	instanceSetName*	String	Name of the instance set - 4 to 20 characters - Only lowercase letters, numbers, and - allowed - - cannot be consecutive - Must start with a letter - Must end with a letter or number - Spaces not allowed
	recoveryEnabled*	Boolean	Enable High Availability mode - true: Use HA mode - false: Do not use HA mode
	subnets[]*	Object Array	List of subnets available for deployment
	subnets[].id*	String	Subnet ID - Can be found in Console > VPC > Subnets
	subnetAssignments[]*	Object Array	List of subnet assignments - Only subnets listed in the subnets field can be used
	subnetAssignments[].primary*	Object	Subnet to assign to Primary
	subnetAssignments[].primary.id*	String	Subnet ID assigned to Primary
	subnetAssignments[].replicas[]*	Object Array	List of subnets assigned to Replicas
	subnetAssignments[].replicas[].id*	String	Subnet ID assigned to Replica
	securityGroups[]*	Object Array	List of security groups to associate with the instance set
	securityGroups[].id*	String	Security group ID - Can be found in Console > VPC > Security Groups
	backupSchedule	Object	Automatic backup policy - If omitted, automatic backup is disabled
	backupSchedule.cron	String	Cron expression for backup schedule - Only hour-based scheduling supported - 5-field cron format (e.g., "* 1 * * *" → daily backup at 1 AM KST) - Hour field must be 0–23 (no special characters) - Other fields must use asterisks (*) only
	backupSchedule.retentionLimit	Integer	Retention period for backups (in days) - Minimum 1 day, maximum 35 days
	user	Object	Database user information - Used when accessing the DB
	user.name	String	Database username
	user.password	String	Encrypted database password or password hash See How to Encrypt Database Password
	tlsEnabled	Boolean	Enable TLS
	parameterGroupId*	String	Parameter group ID to apply to the instance set
	port*	Integer	Redis port number - Must be within 2000–50000
	projectId*	String	Project ID
	version*	String	Redis version

Create new instance set Request Body Example

{
  "description": "mars-test-description",
  "replicas": 3,
  "flavorId": "3830ebad-ea2f-4822-8a7d-9e301c86a58d",
  "instanceSetName": "mars-repl-test",
  "recoveryEnabled": true,
  "subnets": [
    {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
    {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
  ],
  "subnetAssignments": [
    {
      "primary": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
      "replicas": [
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
      ]
    }
  ],
  "securityGroups": [
    {"id": "abcdxxxx-4870-4c4e-a267-2de13e38c2ea"},
    {"id": "qwergggg-4870-4c4e-a267-2de13e38c2ea"}
  ],
  "backupSchedule": {
    "cron": "* 1 * * *",
    "retentionLimit": 30
  },
  "tlsEnabled": false,
  "parameterGroupId": "bbbbcccc-1234-1234-5678-e705e91db2fb",
  "port": "{port-env}",
  "projectId": "{project-id-env}",
  "version": "{version-env}"
}

Response

Status Code	Description
201	Successful response to a resource creation request
400	The user's request is invalid and cannot be processed
401	The user is not authenticated
422	The request is syntactically valid, but the server is unable to process it
403	The user does not have permission to perform the operation
409	A duplicate request has occurred due to the current server state
500	An internal server error occurred and the operation cannot be completed

Field	Type	Description
objectId	String	Instance set ID

Create Instance Set Response Example

201 Created
content-length: 52
content-type: application/json; charset=UTF-8

{
  "objectId": "xxxxxxxx-7347-4d87-a49f-e705e91db2fb"
}

Create instance set from existing backup name

Restore an instance set using an existing backup name.

Note

You can only restore using the same cluster mode as the selected backup, and only to a Redis engine version that is equal to or higher than the backup version.

caution

If the cache size of the source backup is 60% or more of the memory size of the cluster flavor to restore, the restoration may fail.

Request

Create instance set from existing backup name Request Syntax

curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

Type	Parameter	Data Type	Description
Header	{token-id}*	String	Refer to API Authentication Token
	Content-Type*	String	Default: application/json
Body	description	String	Description of the instance set - Max 100 characters - Emojis not allowed - Line breaks (CR, LF) not allowed
	replicas*	Integer	Number of nodes - Includes both Primary and Replicas
	flavorId*	String	Flavor ID
	instanceSetName*	String	Name of the instance set - 4 to 20 characters - Only lowercase letters, numbers, and - allowed - Cannot start or end with - - Must start with a letter and end with a letter/number - No spaces allowed
	recoveryEnabled*	Boolean	Enable High Availability mode - true: enabled - false: disabled
	subnets[]*	Object Array	List of subnets available for deployment
	subnets[].id*	String	Subnet ID - Check Console > VPC > Subnets
	subnetAssignments[]*	Object Array	Subnet assignment list - Must use subnets listed in subnets field
	subnetAssignments[].primary*	Object	Subnet assigned to Primary
	subnetAssignments[].primary.id*	String	Primary subnet ID
	subnetAssignments[].replicas[]*	Object Array	List of subnets for Replica
	subnetAssignments[].replicas[].id*	String	Replica subnet ID
	securityGroups[]*	Object Array	Security group list to attach
	securityGroups[].id*	String	Security group ID - Check Console > VPC > Security Groups
	restoreSource	Object	Restore source info
	restoreSource.backupName	String	Name of the MemStore backup to restore from
	backupSchedule	Object	Automatic backup policy - If omitted, backup is disabled
	backupSchedule.cron	String	Cron expression for backup schedule - Only time setting allowed - 5-field format (e.g. "* 1 * * *" means 1AM KST daily) - Only numbers 0-23 in hour field - All other fields must be *
	backupSchedule.retentionLimit	Integer	Backup retention period (days) - Min: 1 day, Max: 35 days
	user	Object	Database user info for DB access
	user.name	String	Username
	user.password	String	Encrypted password or hash Refer to How to Encrypt Database Password
	tlsEnabled	Boolean	Enable TLS
	parameterGroupId*	String	Parameter group ID to apply
	port*	Integer	Redis port - Must be between 2000 and 50000
	projectId*	String	Refer to Project ID Guide
	version*	String	Redis version

Create instance set from existing backup name Request Body Example

{
  "description": "mars-test-description",
  "replicas": 3,
  "flavorId": "3830ebad-ea2f-4822-8a7d-9e301c86a58d",
  "instanceSetName": "mars-repl-test",
  "recoveryEnabled": true,
  "subnets": [
    {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
    {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
  ],
  "subnetAssignments": [
    {
      "primary": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
      "replicas": [
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
      ]
    }
  ],
  "securityGroups": [
    {"id": "abcdxxxx-4870-4c4e-a267-2de13e38c2ea"},
    {"id": "qwergggg-4870-4c4e-a267-2de13e38c2ea"}
  ],
  "restoreSource": {
    "backupName": "scheduled.testhen.2024-02-27-16-47.KST"
  },
  "backupSchedule": {
    "cron": "* 1 * * *",
    "retentionLimit": 30
  },
  "tlsEnabled": false,
  "parameterGroupId": "bbbbcccc-1234-1234-5678-e705e91db2fb",
  "port": "{port-env}",
  "projectId": "{project-id-env}",
  "version": "{version-env}"
}

Response

Status Code	Description
201	Successful response to resource creation
400	The user's request is invalid
401	The user is not authenticated
403	The user does not have permission
409	A conflicting request due to current server state
500	An internal server error occurred

Field	Type	Description
objectId	String	Instance set ID

Create instance set from existing backup name Response Example

201 Created
content-length: 52
content-type: application/json; charset=UTF-8

{
  "objectId": "xxxxxxxx-7347
}

Create(restore) Object Storage file-based instance set

Restores an instance set from a file stored in Object Storage.

Warning

If the API authentication token expires while loading the backup file from Object Storage during the restore request, the operation may fail.
Also, if the Redis memory size in the backup file exceeds 60% of the memory size of the cluster flavor to be restored, the instance set may not be created successfully.

Request

Object Storage file-based instance set creation (restore) Request Syntax

curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

Type	Parameter	Data Type	Description
Header	{token-id}*	String	Refer to API Authentication Token
	Content-Type*	String	Default content type: application/json
Body	description	String	Description of the instance set - Max 100 characters - Emojis not allowed - Line breaks (CR, LF) not allowed
	replicas*	Integer	Number of nodes - Total including Primary and Replicas
	flavorId*	String	Flavor ID
	instanceSetName*	String	Name of the instance set - 4 to 20 characters - Only lowercase letters, numbers, and - allowed - No consecutive - - Must start with a letter - Must end with a letter or number - No spaces allowed
	recoveryEnabled*	Boolean	High availability mode - true: Enabled - false: Disabled
	subnets[]*	Object Array	List of available subnets
	subnets[].id*	String	Subnet ID - Check in Console > VPC > Subnets
	subnetAssignments[]*	Object Array	Subnet assignment list - Must use subnets from the subnets field
	subnetAssignments[].primary*	Object	Subnet assigned to Primary
	subnetAssignments[].primary.id*	String	ID of the Primary subnet
	subnetAssignments[].replicas[]*	Object Array	Subnets assigned to Replicas
	subnetAssignments[].replicas[].id*	String	ID of the Replica subnet
	securityGroups[]*	Object Array	List of security groups to attach to the instance set
	securityGroups[].id*	String	Security group ID - Found in Console > VPC > Security Groups
	restoreSource	Object	Restore source info
	restoreSource.files[]	String Array	Path to backup file in Object Storage - Must be within the same region/project with edit permission - Format: bucket/folder/.../file - Must match or exceed the engine version used for backup
	backupSchedule	Object	Automatic backup policy - If omitted, automatic backups are disabled
	backupSchedule.cron	String	Cron expression for backup schedule - Only time supported - 5-field cron (e.g., "* 1 * *" = daily at 1 AM KST) - Hour field: 0–23 only (no special characters) - All other fields must be *
	backupSchedule.retentionLimit	Integer	Backup retention period (in days) - Min: 1, Max: 35
	user	Object	Database user info - Used for DB access
	user.name	String	Database username
	user.password	String	Encrypted password or hash How to encrypt DB user password
	tlsEnabled	Boolean	Enable TLS
	parameterGroupId*	String	ID of the parameter group to apply
	port*	Integer	Redis port number - Must be between 2000 and 50000
	projectId*	String	Project ID
	version*	String	Redis version

Object Storage file-based instance set creation (restore) Request Body Example

{
  "description": "mars-test-description",
  "replicas": 3,
  "flavorId": "3830ebad-ea2f-4822-8a7d-9e301c86a58d",
  "instanceSetName": "mars-repl-test",
  "recoveryEnabled": true,
  "subnets": [
    {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
    {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
  ],
  "subnetAssignments": [
    {
      "primary": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
      "replicas": [
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
        {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
      ]
    }
  ],
  "securityGroups": [
    {"id": "abcdxxxx-4870-4c4e-a267-2de13e38c2ea"},
    {"id": "qwergggg-4870-4c4e-a267-2de13e38c2ea"}
  ],
  "restoreSource": {
    "files": ["bucket/path-to-file"]
  },
  "backupSchedule": {
    "cron": "* 1 * * *",
    "retentionLimit": 30
  },
  "tlsEnabled": false,
  "parameterGroupId": "bbbbcccc-1234-1234-5678-e705e91db2fb",
  "port": "{port-env}",
  "projectId": "{project-id-env}",
  "version": "{version-env}"
}

Response

Status Code	Description
201	Successful response to a resource creation request
400	The request is invalid and cannot be processed
401	The request is made by an unauthenticated user
403	The request is made by a user without proper permissions
409	A duplicate request was made due to the current server state
500	The operation could not be completed due to an internal server error

Field	Type	Description
objectId	String	Instance set ID

Object Storage file-based instance set creation (restore) Response Example

201 Created
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "xxxxxxxx-7347-4d87-a49f-e705e91db2fb"
}

Delete instance set

Deletes an instance set.
If the instance set has generated automatic backups, it may not be deletable from the console.
In such cases, you can delete it via the API by including the keepAutomaticBackups parameter in the request.

Request

Delete instance set Request Syntax

curl -X DELETE "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}?keepAutomaticBackups={keep-auto-backup}" \
-H "X-Auth-Token: {token-id}"

Type	Parameter	Data Type	Description
Header	{token-id}*	String	Refer to API Authentication Token
URL	{instance-set-id}*	String	Instance Set ID
Query	{keep-auto-backup}	Boolean	Whether to retain automatic backups - Required if automatic backups exist - true: Retains automatic backups created by this instance set until their expiration date - false: Deletes automatic backups along with the instance set

Response

Status Code	Description
200	Successfully responded to the resource retrieval/deletion request
400	The request is invalid and cannot be processed
401	The user is unauthenticated
403	The user lacks the required permissions
404	The requested resource does not exist
500	Internal server error occurred

Field	Type	Description
objectId	String	Instance Set ID

Delete instance set Response Example

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "aabbccdd-a1d4-465b-8009-1d272bcc2db7"
}

Update instance set

Update the automatic backup policy, associated parameter group, and security group of the instance set.

Request

Update instance set Request Syntax

curl -X PATCH "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}" \
-H "X-Auth-Token: {token-id}" \
-d '{Body}'

Type	Parameter	Type	Description
Header	{token-id}*	String	See API authentication token
URL	{instance-set-id}*	String	Instance set ID
Body	backupSchedule	Object	Backup schedule settings
	backupSchedule.cron	String	Cron expression for the backup schedule - Only hour can be configured - Use 5-part cron format - If the value is passed as "", backup will be deleted
	backupSchedule.retentionLimit	Integer	Backup retention period (unit: days)
	description	String	Instance set description
	parameterGroupId	String	Parameter group ID to be associated with the instance set - Cannot set "" as the value
	securityGroups[]	Object Array	List of security group IDs to be updated
	securityGroups[].id	String	Security group ID

Update instance set Request Body Example

{
  "backupSchedule": {
    "cron": "* 3 * * *",
    "retentionLimit": 15
  },
  "description": ""
}

Response

Status Code	Description
200	Successful response to resource retrieval/deletion request
400	The request is invalid and cannot be processed
401	Unauthorized request
403	Forbidden request due to lack of permissions
404	The requested resource was not found
500	Internal server error

Field	Type	Description
objectId	String	Instance set ID

Update instance set Response Example

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "aabbccdd-a1d4-465b-8009-1d272bcc2db7"
}

Retrieve instance list of instance set

인스턴스 세트의 인스턴스(노드) 목록을 조회합니다.

Request

Retrieve instance list of instance set Request Syntax

curl -X GET "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}/instances" \
-H "X-Auth-Token: {token-id}"

Type	Parameter	Data Type	Description
URL	{instance-set-id}*	String	Instance set ID
Header	{token-id}*	String	Refer to API authentication token

Response

Status Code	Description
200	Successfully retrieved/deleted the resource
400	The request is invalid and cannot be processed
401	Unauthorized request
403	Forbidden request due to lack of permissions
500	Internal server error

Field	Type	Description
size	Integer	Number of data items
data[]	Object Array	List of instances
data[].instanceName	String	Instance name
data[].description	String	Description of the instance set
data[].projectId	String	Project ID
data[].role	String	Instance role (primary/replica)
data[].flavorId	String	Flavor ID
data[].version	String	Redis version
data[].port	Integer	Redis port number
data[].subnet	Object	Allocated subnet info
data[].subnet.id	String	Subnet ID
data[].creator	String	Creator of the instance set
data[].objectId	String	Instance ID
data[].endpoint	String	Instance endpoint (private IP)
data[].license	String	License
data[].createdAt	String	Creation timestamp (RFC3339)
data[].status	String	Instance status (e.g., PROVISIONING, FAILED)

Retrieve instance list of instance set Response Example

200 OK
content-type: application/json; charset=UTF-8
  
{
  "size": 2,
  "data": [
    {
      "instanceName": "test-instance-set-1",
      "description": "test",
      "projectId": "abcdabcdf4d14b41a36823e2091c3a6d",
      "flavorId": "xxxxxxxx-ea2f-4822-8a7d-9e301c86a58d",
      "version": "6.2.5",
      "port": 6379,
      "subnet": {
          "id": "qqqqwwww-2726-432e-aa37-04b778ef2ba1"
      },
      "creator": "ms@kakaoenterprise.com",
      "objectId": "abcdefg-a97a-59c8-9e6a-e967383c65e2",
      "role": "primary",
      "endpoint": "172.30.1.244",
      "license": "GPL",
      "createdAt": "2024-03-11T01:15:03Z",
      "status": "Running"
    },
    {
      "instanceName": "test-instance-set-2",
      "description": "test",
      "projectId": "abcdabcdf4d14b41a36823e2091c3a6d",
      "flavorId": "xxxxxxxx-ea2f-4822-8a7d-9e301c86a58d",
      "version": "6.2.5",
      "port": 6379,
      "subnet": {
        "id": "qqqqwwww-2726-432e-aa37-04b778ef2ba1"
      },
      "creator": "ms@kakaoenterprise.com",
      "objectId": "abcdefg-39c8-55c2-b4d3-9009c554d102",
      "role": "replica",
      "endpoint": "172.30.0.67",
      "license": "GPL",
      "createdAt": "2024-03-11T01:15:03Z",
      "status": "Running"
    }
  ]
}

Delete instance from instance set

Deletes an instance (node) from an instance set.

• When high availability mode is enabled, Primary instances cannot be deleted.
• When high availability mode is enabled, only instances in the Running state can be deleted.
• When high availability mode is not enabled, the Primary instance can be deleted only if its state is Failed.
• If the total number of nodes in the instance set is 2 and an automatic backup policy is set, node deletion is not allowed.

Request

Delete instance from instance set Request Syntax

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "aaaabbbb-a1d4-465b-8009-1d272bcc2db7"
}

Promote Replica to Primary

Promotes a specific replica to a primary instance. This request is only allowed when high availability mode is disabled.

Request

Promote Replica to Primary Request Syntax

curl -X PATCH "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}/primary" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

Type	Parameter	Type	Description
URL	{instance-set-id}*	String	Instance set ID
Header	{token-id}*	String	Refer to API Authentication Token
	Content-Type*	String	Content type, default: application/json
Body	primaryId*	String	ID of the instance to promote to Primary

Promote Replica to Primary Request Body Example

{
  "primaryId": "instance-idid-xxxx-a49f-e705e91db2fb"
}

Response

Status Code	Description
200	Successful response to the resource update request
400	The request is invalid and cannot be processed
401	Request made by an unauthenticated user
403	Request made by a user without proper permissions
404	The requested resource does not exist
500	Internal server error, unable to process the request

Field	Type	Description
objectId	String	Instance set ID

Promote Replica to Primary Response Example

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "bbccxxzz-7347-4d87-a49f-e705e91db2fb"
}

Add instance

Adds one Replica instance. You can create up to 5 Replica instances.

Request

Add instance Request Syntax

curl -X PATCH "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}/replicas" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

Type	Parameter	Type	Description
URL	{instance-set-id}*	String	Instance set ID
Header	{token-id}*	String	Refer to API Authentication Token
	Content-Type*	String	Default content type: application/json
Body	subnet*	Object	Information about the subnet to assign
	subnet.id*	String	Subnet ID

Add instance Request Body Example

{
  "subnet": { "id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b" }
}

Response

Status code	Description
200	Successful response to resource update request
400	Request is invalid and cannot be processed
401	Request made by unauthenticated user
403	Request made by unauthorized user
404	Requested resource does not exist
500	Operation cannot proceed due to internal error

Field	Type	Description
objectId	String	Instance set ID

Add instance Response Example

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "qqwweerr-7347-4d87-a49f-e705e91db2fb"
}

Set high availability mode

Enable or disable high availability mode. This can only be changed when instance set status is Running.

Request

Set high availability mode request syntax

curl -X PATCH "https://redis.kr-central-2.kakaocloud.com/v1/instance-sets/{instance-set-id}/recovery" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'

종류	파라미터	유형	설명
URL	{instance-set-id}*	String	인스턴스 세트 ID
Header	{token-id}*	String	API 인증 토큰 참고
	Content-Type*	String	콘텐츠 유형 기본값: application/json
Body	enabled*	Boolean	활성화 여부 - true: 고가용성 모드 설정 - false: 고가용성 모드 해제

Set high availability mode Request Body Example

{
  "enabled": true
}

Response

Status code	Description
200	Successful response to resource update request
400	Request is invalid and cannot be processed
401	Request made by unauthenticated user
403	Request made by unauthorized user
404	Requested resource does not exist
500	Operation cannot proceed due to internal error

Field	Type	Description
objectId	String	Instance set ID

Set high availability mode Response Example

200 OK
content-length: 52
content-type: application/json; charset=UTF-8
  
{
  "objectId": "aassddff-7347-4d87-a49f-e705e91db2fb"
}