---
title: "POST /cluster"
method: POST
path: "/cluster"
---

# POST /cluster

`POST /cluster`

Creates a new Amazon DocumentDB elastic cluster and returns its cluster structure.

## Request body

- object
  - `adminUserName` string, required — <p>The name of the Amazon DocumentDB elastic clusters administrator.</p> <p> <i>Constraints</i>:</p> <ul> <li> <p>Must be from 1 to 63 letters or numbers.</p> </li> <li> <p>The first character must be a letter.</p> </li> <li> <p>Cannot be a reserved word.</p> </li> </ul>
  - `adminUserPassword` string, password, required — <p>The password for the Amazon DocumentDB elastic clusters administrator. The password can contain any printable ASCII characters.</p> <p> <i>Constraints</i>:</p> <ul> <li> <p>Must contain from 8 to 100 characters.</p> </li> <li> <p>Cannot contain a forward slash (/), double quote ("), or the "at" symbol (@).</p> </li> </ul>
  - `authType` 'PLAIN_TEXT' | 'SECRET_ARN', required — The authentication type used to determine where to fetch the password used for accessing the elastic cluster. Valid types are <code>PLAIN_TEXT</code> or <code>SECRET_ARN</code>.
  - `backupRetentionPeriod` integer — The number of days for which automatic snapshots are retained.
  - `clientToken` string — The client token for the elastic cluster.
  - `clusterName` string, required — <p>The name of the new elastic cluster. This parameter is stored as a lowercase string.</p> <p> <i>Constraints</i>:</p> <ul> <li> <p>Must contain from 1 to 63 letters, numbers, or hyphens.</p> </li> <li> <p>The first character must be a letter.</p> </li> <li> <p>Cannot end with a hyphen or contain two consecutive hyphens.</p> </li> </ul> <p> <i>Example</i>: <code>my-cluster</code> </p>
  - `kmsKeyId` string — <p>The KMS key identifier to use to encrypt the new elastic cluster.</p> <p>The KMS key identifier is the Amazon Resource Name (ARN) for the KMS encryption key. If you are creating a cluster using the same Amazon account that owns this KMS encryption key, you can use the KMS key alias instead of the ARN as the KMS encryption key.</p> <p>If an encryption key is not specified, Amazon DocumentDB uses the default encryption key that KMS creates for your account. Your account has a different default encryption key for each Amazon Region.</p>
  - `preferredBackupWindow` string — The daily time range during which automated backups are created if automated backups are enabled, as determined by the <code>backupRetentionPeriod</code>.
  - `preferredMaintenanceWindow` string — <p>The weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).</p> <p> <i>Format</i>: <code>ddd:hh24:mi-ddd:hh24:mi</code> </p> <p> <i>Default</i>: a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region, occurring on a random day of the week.</p> <p> <i>Valid days</i>: Mon, Tue, Wed, Thu, Fri, Sat, Sun</p> <p> <i>Constraints</i>: Minimum 30-minute window.</p>
  - `shardCapacity` integer, required — The number of vCPUs assigned to each elastic cluster shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.
  - `shardCount` integer, required — The number of shards assigned to the elastic cluster. Maximum is 32.
  - `shardInstanceCount` integer — The number of replica instances applying to all shards in the elastic cluster. A <code>shardInstanceCount</code> value of 1 means there is one writer instance, and any additional instances are replicas that can be used for reads and to improve availability.
  - `subnetIds` String[] — The Amazon EC2 subnet IDs for the new elastic cluster.
  - `tags` object — The tags to be assigned to the new elastic cluster.
  - `vpcSecurityGroupIds` String[] — A list of EC2 VPC security groups to associate with the new elastic cluster.

## Response `200`

Success

- CreateClusterOutput
  - `cluster` object, required — The new elastic cluster that has been created.
    - `adminUserName` string, required — The name of the elastic cluster administrator.
    - `authType` 'PLAIN_TEXT' | 'SECRET_ARN', required — The authentication type for the elastic cluster.
    - `backupRetentionPeriod` integer — The number of days for which automatic snapshots are retained.
    - `clusterArn` string, required — The ARN identifier of the elastic cluster.
    - `clusterEndpoint` string, required — The URL used to connect to the elastic cluster.
    - `clusterName` string, required — The name of the elastic cluster.
    - `createTime` string, required — The time when the elastic cluster was created in Universal Coordinated Time (UTC).
    - `kmsKeyId` string, required — The KMS key identifier to use to encrypt the elastic cluster.
    - `preferredBackupWindow` string — The daily time range during which automated backups are created if automated backups are enabled, as determined by <code>backupRetentionPeriod</code>.
    - `preferredMaintenanceWindow` string, required — <p>The weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).</p> <p> <i>Format</i>: <code>ddd:hh24:mi-ddd:hh24:mi</code> </p>
    - `shardCapacity` integer, required — The number of vCPUs assigned to each elastic cluster shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.
    - `shardCount` integer, required — The number of shards assigned to the elastic cluster. Maximum is 32.
    - `shardInstanceCount` integer — The number of replica instances applying to all shards in the cluster. A <code>shardInstanceCount</code> value of 1 means there is one writer instance, and any additional instances are replicas that can be used for reads and to improve availability.
    - `shards` Shard[] — The total number of shards in the cluster.
      - `createTime` string, required — The time when the shard was created in Universal Coordinated Time (UTC).
      - `shardId` string, required — The ID of the shard.
      - `status` 'CREATING' | 'ACTIVE' | 'DELETING' | 'UPDATING' | 'VPC_ENDPOINT_LIMIT_EXCEEDED' | 'IP_ADDRESS_LIMIT_EXCEEDED' | 'INVALID_SECURITY_GROUP_ID' | 'INVALID_SUBNET_ID' | 'INACCESSIBLE_ENCRYPTION_CREDS' | 'INACCESSIBLE_SECRET_ARN' | 'INACCESSIBLE_VPC_ENDPOINT' | 'INCOMPATIBLE_NETWORK' | 'MERGING' | 'MODIFYING' | 'SPLITTING' | 'COPYING' | 'STARTING' | 'STOPPING' | 'STOPPED' | 'MAINTENANCE' | 'INACCESSIBLE_ENCRYPTION_CREDENTIALS_RECOVERABLE', required — The current status of the shard.
    - `status` 'CREATING' | 'ACTIVE' | 'DELETING' | 'UPDATING' | 'VPC_ENDPOINT_LIMIT_EXCEEDED' | 'IP_ADDRESS_LIMIT_EXCEEDED' | 'INVALID_SECURITY_GROUP_ID' | 'INVALID_SUBNET_ID' | 'INACCESSIBLE_ENCRYPTION_CREDS' | 'INACCESSIBLE_SECRET_ARN' | 'INACCESSIBLE_VPC_ENDPOINT' | 'INCOMPATIBLE_NETWORK' | 'MERGING' | 'MODIFYING' | 'SPLITTING' | 'COPYING' | 'STARTING' | 'STOPPING' | 'STOPPED' | 'MAINTENANCE' | 'INACCESSIBLE_ENCRYPTION_CREDENTIALS_RECOVERABLE', required — The status of the elastic cluster.
    - `subnetIds` String[], required — The Amazon EC2 subnet IDs for the elastic cluster.
    - `vpcSecurityGroupIds` String[], required — A list of EC2 VPC security groups associated with thie elastic cluster.

## Other responses

- `480` — ThrottlingException
- `481` — ValidationException
- `482` — ServiceQuotaExceededException
- `483` — ConflictException
- `484` — InternalServerException
- `485` — AccessDeniedException

---

[API](https://skmtc.net/aws/apis/docdb-elastic.md) · [All operations](https://skmtc.net/aws/apis/docdb-elastic/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/docdb-elastic/versions/71417e1f0c94/schema)