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
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}'

Type	Parameter	Data type	Description
Header	`{token-id}`*	String	Refer to API authentication token
	Content-Type*	String	Default content type: `application/json`
Body	name*	String	Cluster name
	description	String	Cluster description
	version*	String	Redis 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*	Integer	Redis port number (2000 ~ 50000)
	shardCount*	Integer	Number of shards
	nodeCountPerShard*	Integer	Number of nodes per shard
	flavorId*	String	Flavor ID
	parameterGroupId*	String	ID of the parameter group to attach to the cluster
	subnets[]*	Object Array	List of available subnets for placement
	subnets[].id*	String	Subnet ID - Subnet ID can be found in Console > VPC > Subnets
	subnetAssignments[]*	Object Array	List of subnet assignments
	subnetAssignments[].primary*	Object	Subnet to assign as primary
	subnetAssignments[].primary.id*	String	Subnet ID to assign as primary
	subnetAssignments[].replicas[]*	Object Array	List of subnets to assign as replicas
	subnetAssignments[].replicas[].id*	String	Subnet ID to assign as replica
	securityGroups[]*	Object Array	List of security groups to attach to the cluster
	securityGroups[].id*	String	Security group ID - Can be found in Console > VPC > Security Groups
	user	Object	Database user information - Account information for database access
	user.name	String	Database user name
	user.password	String	Database 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 Code	Description
`201`	Successful response to resource creation request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`409`	Conflict: duplicate request given the current server state
`422`	Valid request syntax but unable to process the operation
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}'

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
Header	`{token-id}`*	String	Refer to API authentication token
Body	description	String	Information to update (cluster description)
	parameterGroupId	String	Parameter 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 Code	Description
`200`	Successful response to resource update request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}'

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
Header	`{token-id}`	String	Refer to API authentication token
Body	nodeCount*	Integer	Number of nodes to be added to the shard
	subnetAssignments[]*	Object	List of subnet assignments
	subnetAssignments[].primary*	Object	Subnet to assign as primary
	subnetAssignments[].primary.id*	String	Subnet ID to assign as primary
	subnetAssignments[].replicas[]*	Array	List of subnets to assign as replicas
	subnetAssignments[].replicas[].id*	String	Subnet 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 Code	Description
`201`	Successful response to resource creation request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
Header	`{token-id}`	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
shards[]	Object Array	List of shards
shards[].id	String	Shard ID
shards[].name	String	Shard name
shards[].slots	String	Assigned slot range
shards[].nodes[]	Object Array	List of nodes
shards[].nodes[].id	String	Node ID
shards[].nodes[].name	String	Node name
shards[].nodes[].subnet	Object	Subnet information for the node
shards[].nodes[].subnet.id	String	Subnet ID where the node is placed
shards[].nodes[].endpoint	String	Node endpoint (private IP)
shards[].nodes[].role	String	Node role (primary/replica)
shards[].nodes[].status	String	Node status
shards[].nodes[].createdAt	String	Node creation time (RFC3339)
shards[].status	String	Shard status
shards[].createdAt	String	Shard 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}`*	String	API 인증 토큰 참고

Response

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
id	String	Shard ID
name	String	Shard name
slots	String	Assigned slot range
nodes[]	Object Array	List of nodes
nodes[].id	String	Node ID
nodes[].name	String	Node name
nodes[].subnet	Object	Subnet information for the node
nodes[].subnet.id	String	Subnet ID where the node is placed
nodes[].endpoint	String	Node endpoint (private IP)
nodes[].role	String	Node role (primary/replica)
nodes[].status	String	Node status
nodes[].createdAt	String	Node creation time (RFC3339)
status	String	Shard status
createdAt	String	Shard 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}'

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
Header	`{token-id}`*	String	Refer to API authentication token
Body	subnet*	Object	Subnet placement information
	subnet.id*	String	Subnet ID to place the replica

Add replica to shard request body example
{
 "subnet": {"id": "yyyyyyyy-0a69-4f8b-b56d-59ce12b4d55b"}
}

Response

Status Code	Description
`201`	Successful response to resource creation request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
nodes[]	Object Array	List of nodes
nodes[].id	String	Node ID
nodes[].name	String	Node name
nodes[].subnet	Object	Subnet information for the node
nodes[].subnet.id	String	Subnet ID where the node is placed
nodes[].endpoint	String	Node endpoint (private IP)
nodes[].role	String	Node role (primary/replica)
nodes[].status	String	Node status
nodes[].createdAt	Integer	Node 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
	`{node-id}`*	String	Node ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
id	String	Node ID
name	String	Node name
subnet	Object	Subnet information for the node
subnet.id	String	Subnet ID where the node is placed
endpoint	String	Node endpoint (private IP)
role	String	Node role (primary/replica)
status	String	Node status
createdAt	String	Node 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}"

Type	Parameter	Data type	Description
URL	`{cluster-id}`*	String	Cluster ID
	`{shard-id}`*	String	Shard ID
	`{node-id}`*	String	Node ID
Header	`{token-id}`*	String	Refer to API authentication token

Response

Status Code	Description
`200`	Successful response to resource retrieval/deletion request
`400`	Invalid request, unable to process
`401`	Unauthorized user request
`403`	User does not have the required permissions
`404`	The requested resource does not exist
`500`	Internal server error, unable to process request

Field	Data type	Description
objectId	String	Cluster 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 */
}

Create cluster​

Request​

Response​

Update cluster information​

Request​

Response​

Delete cluster​

Request​

Response​

Add shard​

Request​

Response​

Retrieve shard list in a cluster​

Request​

Response​

Retrieve shard details​

Request​

Response​

Response​

Delete shard​

Request​

Response​

Add replica to shard​

Request​

Response​

View list instances (nodes) in a shard​

Request​

Response​

View instance (node) details​

Request​

Response​

Delete instance (node)​

Request​

Response​

Create cluster

Request

Response

Update cluster information

Request

Response

Delete cluster

Request

Response

Add shard

Request

Response

Retrieve shard list in a cluster

Request

Response

Retrieve shard details

Request

Response

Response

Delete shard

Request

Response

Add replica to shard

Request

Response

View list instances (nodes) in a shard

Request

Response

View instance (node) details

Request

Response

Delete instance (node)

Request

Response