Skip to main content

When cluster mode enabled

The following APIs can be used with clusters that have cluster mode set to enabled.

caution
  • The user.password field must contain an encrypted value for successful creation.

Create cluster

Create a new cluster. When creating a cluster, the minimum number of shards is 1, and the maximum is 12.

Request
Create cluster request syntax
curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/clusters" \
-H "X-Auth-Token: {token-id}" \
-H "Content-Type: application/json" \
-d '{Body}'
TypeParameterData typeDescription
Header{token-id}*StringRefer to API authentication token
Content-Type*StringDefault content type: application/json
Bodyname*StringCluster name
descriptionStringCluster description
version*StringRedis version
- Supports versions 7.2.6, 7.0.15, 6.2.16, 6.2.5, and 5.0.6 when the cluster is not in use.
port*IntegerRedis port number (2000 ~ 50000)
shardCount*IntegerNumber of shards
nodeCountPerShard*IntegerNumber of nodes per shard
flavorId*StringFlavor ID
parameterGroupId*StringID of the parameter group to attach to the cluster
subnets[]*Object ArrayList of available subnets for placement
subnets[].id*StringSubnet ID
- Subnet ID can be found in Console > VPC > Subnets
subnetAssignments[]*Object ArrayList of subnet assignments
subnetAssignments[].primary*ObjectSubnet to assign as primary
subnetAssignments[].primary.id*StringSubnet ID to assign as primary
subnetAssignments[].replicas[]*Object ArrayList of subnets to assign as replicas
subnetAssignments[].replicas[].id*StringSubnet ID to assign as replica
securityGroups[]*Object ArrayList of security groups to attach to the cluster
securityGroups[].id*StringSecurity group ID
- Can be found in Console > VPC > Security Groups
userObjectDatabase user information
- Account information for database access
user.nameStringDatabase user name
user.passwordStringDatabase user password (encrypted or password hash)
How to encrypt the database user password
Create cluster request body example
{
"name": "test-cluster",
"description": "test-cluster",
"version": "6.2.5",
"port": 6379,
"shardCount": 2,
"nodeCountPerShard": 3,
"flavorId": "3830ebad-ea2f-4822-8a7d-9e301c86a58d",
"parameterGroupId": "bbbbcccc-1234-1234-5678-e705e91db2fb",
"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"}
]
},
{
"primary": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"replicas": [
{"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
{"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
]
}
],
"user": {
"name": "testuser",
"password": "if2iOwJYiklliJIT8tvqoY~~~~",
},
"securityGroups": [
{"id": "abcdxxxx-4870-4c4e-a267-2de13e38c2ea"},
{"id": "qwergggg-4870-4c4e-a267-2de13e38c2ea"}
]
}
Response
Status CodeDescription
201Successful response to resource creation request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
409Conflict: duplicate request given the current server state
422Valid request syntax but unable to process the operation
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Create cluster response example
201 Created
content-length: 52
content-type: application/json; charset=UTF-8

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

Update cluster information

Update specific information for an existing cluster.

Request
Update cluster information request syntax
curl -X PATCH "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}" \
-H "accept: application/json" \
-H "X-Auth-Token: {token-id}" \
-d '{Body}'
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
Header{token-id}*StringRefer to API authentication token
BodydescriptionStringInformation to update (cluster description)
parameterGroupIdStringParameter group ID to attach to the cluster
- Cannot update parameterGroupId to an empty string
Update cluster information request body example
{
"description": "modify description"
"parameterGroupId": "bbbbcccc-1234-1234-5678-e705e91db2fb"
}
Response
Status CodeDescription
200Successful response to resource update request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Update cluster information response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

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

Delete cluster

Delete a specific cluster.

Request
Delete cluster request syntax
curl -X DELETE "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Delete cluster response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

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

Add shard

Add a shard to a specific cluster.

Request
Add shard request syntax
curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards" \
-H "X-Auth-Token: {token-id}" \
-d '{Body}'
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
Header{token-id}StringRefer to API authentication token
BodynodeCount*IntegerNumber of nodes to be added to the shard
subnetAssignments[]*ObjectList of subnet assignments
subnetAssignments[].primary*ObjectSubnet to assign as primary
subnetAssignments[].primary.id*StringSubnet ID to assign as primary
subnetAssignments[].replicas[]*ArrayList of subnets to assign as replicas
subnetAssignments[].replicas[].id*StringSubnet ID to assign as replica
Add shard request body example
{
"nodeCount": 3,
"subnetAssignments": {
"primary": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"replicas": [
{"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
{"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
]
}
}
Response
Status CodeDescription
201Successful response to resource creation request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Add shard response example
201 Created
content-length: 52
content-type: application/json; charset=UTF-8

{
"objectId": "875bb16f-7347-4d87-a49f-e705e91db2fb"
}

Retrieve shard list in a cluster

Retrieve the list of shards for a specific cluster.

Request
List shards request syntax
curl -X GET "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
Header{token-id}StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
shards[]Object ArrayList of shards
shards[].idStringShard ID
shards[].nameStringShard name
shards[].slotsStringAssigned slot range
shards[].nodes[]Object ArrayList of nodes
shards[].nodes[].idStringNode ID
shards[].nodes[].nameStringNode name
shards[].nodes[].subnetObjectSubnet information for the node
shards[].nodes[].subnet.idStringSubnet ID where the node is placed
shards[].nodes[].endpointStringNode endpoint (private IP)
shards[].nodes[].roleStringNode role (primary/replica)
shards[].nodes[].statusStringNode status
shards[].nodes[].createdAtStringNode creation time (RFC3339)
shards[].statusStringShard status
shards[].createdAtStringShard creation time (RFC3339)
List shards response example
200 OK
content-type: application/json; charset=UTF-8

{
"shards": [
{
"id": "001",
"name": "test-cluster-001",
"slots": "0-8191",
"nodes": [
{
"id": "aaaaaaaa-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-001",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "primary",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "bbbbbbbb-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-002",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "cccccccc-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-003",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}
],
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "002",
"name": "test-cluster-002",
"slots": "8192-16383",
"nodes": [
{
"id": "dddddddd-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-002-001",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "primary",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "eeeeeeee-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-002-002",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "ffffffff-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-002-003",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}
],
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}
]
}

Retrieve shard details

Retrieve detailed information for a specific shard in a specific cluster.

Request
Retrieve shard details request syntax
curl -X GET "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}" \
-H "X-Auth-Token: {token-id}"
종류파라미터유형설명
URL{cluster-id}*String클러스터 ID
{shard-id}*String샤드 ID
Header{token-id}*StringAPI 인증 토큰 참고
Response
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
idStringShard ID
nameStringShard name
slotsStringAssigned slot range
nodes[]Object ArrayList of nodes
nodes[].idStringNode ID
nodes[].nameStringNode name
nodes[].subnetObjectSubnet information for the node
nodes[].subnet.idStringSubnet ID where the node is placed
nodes[].endpointStringNode endpoint (private IP)
nodes[].roleStringNode role (primary/replica)
nodes[].statusStringNode status
nodes[].createdAtStringNode creation time (RFC3339)
statusStringShard status
createdAtStringShard creation time (RFC3339)
Retrieve shard details response example
200 OK
content-type: application/json; charset=UTF-8

{
"id": "001",
"name": "test-cluster-001",
"slots": "0-8191",
"nodes": [
{
"id": "aaaaaaaa-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-001",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "primary",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "bbbbbbbb-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-002",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "cccccccc-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-003",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}
],
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}

Delete shard

Delete a specific shard from a specific cluster.

Request
Delete shard request syntax
curl -X DELETE "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Delete shard response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

{
"objectId": "qwerqwer-7347-4d87-a49f-e705e91db2fb",
}

Add replica to shard

Add a replica to a specific shard in a specific cluster.

Request
Add replica to shard request syntax
curl -X POST "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}/nodes" \
-H "X-Auth-Token: {token-id}" \
-d '{Body}'
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
Header{token-id}*StringRefer to API authentication token
Bodysubnet*ObjectSubnet placement information
subnet.id*StringSubnet ID to place the replica
Add replica to shard request body example
{
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
}
Response
Status CodeDescription
201Successful response to resource creation request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Add replica to shard response example
201 Created
content-length: 52
content-type: application/json; charset=UTF-8

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

View list instances (nodes) in a shard

Retrieve the list of instances (nodes) for a specific shard in a specific cluster.

Request
List instances (nodes) in a shard request syntax
curl -X GET "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}/nodes" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
nodes[]Object ArrayList of nodes
nodes[].idStringNode ID
nodes[].nameStringNode name
nodes[].subnetObjectSubnet information for the node
nodes[].subnet.idStringSubnet ID where the node is placed
nodes[].endpointStringNode endpoint (private IP)
nodes[].roleStringNode role (primary/replica)
nodes[].statusStringNode status
nodes[].createdAtIntegerNode creation time (RFC3339)
List instances (nodes) in a shard response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

{
"nodes": [
{
"id": "aaaaaaaa-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-001",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "primary",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "bbbbbbbb-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-002",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
},
{
"id": "cccccccc-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-003",
"subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "replica",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}
]
}

View instance (node) details

Retrieve detailed information for a specific instance (node) in a specific shard of a specific cluster.

Request
Retrieve instance (node) details request syntax
curl -X GET "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}/nodes/{node-id}" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
{node-id}*StringNode ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
idStringNode ID
nameStringNode name
subnetObjectSubnet information for the node
subnet.idStringSubnet ID where the node is placed
endpointStringNode endpoint (private IP)
roleStringNode role (primary/replica)
statusStringNode status
createdAtStringNode creation time (RFC3339)
Retrieve instance (node) details response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

{
"id": "aaaaaaaa-c12e-46f9-81a0-60ab1950a480",
"name": "test-cluster-001-001",
"subnet": {"id": "xxxxxxxx-0a69-4f8b-b56d-59ce12b4d55b"},
"endpoint": "10.184.x.x",
"role": "primary",
"status": "Modifying",
"createdAt": "2024-03-06T02:35:13Z"
}

Delete instance (node)

Delete a specific instance (node) in a specific shard of a specific cluster. Note: Primary nodes cannot be deleted.

Request
Delete instance (node) request syntax
curl -X DELETE "https://redis.kr-central-2.kakaocloud.com/v1/clusters/{cluster-id}/shards/{shard-id}/nodes/{node-id}" \
-H "X-Auth-Token: {token-id}"
TypeParameterData typeDescription
URL{cluster-id}*StringCluster ID
{shard-id}*StringShard ID
{node-id}*StringNode ID
Header{token-id}*StringRefer to API authentication token
Response
Status CodeDescription
200Successful response to resource retrieval/deletion request
400Invalid request, unable to process
401Unauthorized user request
403User does not have the required permissions
404The requested resource does not exist
500Internal server error, unable to process request
FieldData typeDescription
objectIdStringCluster ID
Delete instance (node) response example
200 OK
content-length: 52
content-type: application/json; charset=UTF-8

{
"objectId": "qwerqwer-7347-4d87-a49f-e705e91db2fb" /* cluster id */
}