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

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
	port*	Integer	Redis port number
	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	Integer	Node creation time (RFC3339)
shards[].status	String	Shard status
shards[].createdAt	Integer	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": 1637915937
        },
        {
          "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": 1637915937
        },
        {
          "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": 1637915937
        }
      ],
      "status": "Modifying",
      "createdAt": 1637915937
    },
    {
      "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": 1637915937
        },
        {
          "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": 1637915937
        },
        {
          "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": 1637915937
        }
      ],
      "status": "Modifying",
      "createdAt": 1637915937
    }
  ]
}

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	Integer	Node creation time (RFC3339)
status	String	Shard status
createdAt	Integer	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	Integer	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 */
}