# CreateCluster


The CreateCluster API allows you to create both single-Region clusters and multi-Region clusters. With the addition of the *multiRegionProperties* parameter, you can create a cluster with witness Region support and establish peer relationships with clusters in other Regions during creation.

**Note**  
Creating multi-Region clusters requires additional IAM permissions beyond those needed for single-Region clusters, as detailed in the **Required permissions** section below.

 **Required permissions** 

dsql:CreateCluster  
Required to create a cluster.  
Resources: `arn:aws:dsql:region:account-id:cluster/*` 

dsql:TagResource  
Permission to add tags to a resource.  
Resources: `arn:aws:dsql:region:account-id:cluster/*` 

dsql:PutMultiRegionProperties  
Permission to configure multi-Region properties for a cluster.  
Resources: `arn:aws:dsql:region:account-id:cluster/*` 

dsql:AddPeerCluster  
When specifying `multiRegionProperties.clusters`, permission to add peer clusters.  
Resources:  
+ Local cluster: `arn:aws:dsql:region:account-id:cluster/*` 
+ Each peer cluster: exact ARN of each specified peer cluster

dsql:PutWitnessRegion  
When specifying `multiRegionProperties.witnessRegion`, permission to set a witness Region. This permission is checked both in the cluster Region and in the witness Region.  
Resources: `arn:aws:dsql:region:account-id:cluster/*`   
Condition Keys: `dsql:WitnessRegion` (matching the specified witness region)

**Important**  
The witness Region specified in `multiRegionProperties.witnessRegion` cannot be the same as the cluster's Region.

## Request Syntax


```
POST /cluster HTTP/1.1
Content-type: application/json

{
   "bypassPolicyLockoutSafetyCheck": boolean,
   "clientToken": "string",
   "deletionProtectionEnabled": boolean,
   "kmsEncryptionKey": "string",
   "multiRegionProperties": { 
      "clusters": [ "string" ],
      "witnessRegion": "string"
   },
   "policy": "string",
   "tags": { 
      "string" : "string" 
   }
}
```

## URI Request Parameters


The request does not use any URI parameters.

## Request Body


The request accepts the following data in JSON format.

 ** [bypassPolicyLockoutSafetyCheck](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-bypassPolicyLockoutSafetyCheck"></a>
An optional field that controls whether to bypass the lockout prevention check. When set to true, this parameter allows you to apply a policy that might lock you out of the cluster. Use with caution.  
Type: Boolean  
Required: No

 ** [clientToken](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-clientToken"></a>
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully, the subsequent retries with the same client token return the result from the original successful request and they have no additional effect.  
If you don't specify a client token, the AWS SDK automatically generates one.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 128.  
Pattern: `[!-~]+`   
Required: No

 ** [deletionProtectionEnabled](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-deletionProtectionEnabled"></a>
If enabled, you can't delete your cluster. You must first disable this property before you can delete your cluster.  
Type: Boolean  
Required: No

 ** [kmsEncryptionKey](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-kmsEncryptionKey"></a>
The AWS KMS key that encrypts and protects the data on your cluster. You can specify the ARN, ID, or alias of an existing key or have AWS create a default key for you.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 2048.  
Pattern: `[a-zA-Z0-9:/_-]+`   
Required: No

 ** [multiRegionProperties](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-multiRegionProperties"></a>
The configuration settings when creating a multi-Region cluster, including the witness region and linked cluster properties.  
Type: [MultiRegionProperties](API_MultiRegionProperties.md) object  
Required: No

 ** [policy](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-policy"></a>
An optional resource-based policy document in JSON format that defines access permissions for the cluster.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 20480.  
Required: No

 ** [tags](#API_CreateCluster_RequestSyntax) **   <a name="auroradsql-CreateCluster-request-tags"></a>
A map of key and value pairs to use to tag your cluster.  
Type: String to string map  
Map Entries: Minimum number of 0 items. Maximum number of 200 items.  
Key Length Constraints: Minimum length of 1. Maximum length of 128.  
Key Pattern: `[a-zA-Z0-9_.:/=+\-@ ]*`   
Value Length Constraints: Minimum length of 0. Maximum length of 256.  
Value Pattern: `[a-zA-Z0-9_.:/=+\-@ ]*`   
Required: No

## Response Syntax


```
HTTP/1.1 200
Content-type: application/json

{
   "arn": "string",
   "creationTime": number,
   "deletionProtectionEnabled": boolean,
   "encryptionDetails": { 
      "encryptionStatus": "string",
      "encryptionType": "string",
      "kmsKeyArn": "string"
   },
   "endpoint": "string",
   "identifier": "string",
   "multiRegionProperties": { 
      "clusters": [ "string" ],
      "witnessRegion": "string"
   },
   "status": "string"
}
```

## Response Elements


If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

 ** [arn](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-arn"></a>
The ARN of the created cluster.  
Type: String  
Pattern: `arn:aws(-[^:]+)?:dsql:[a-z0-9-]{1,20}:[0-9]{12}:cluster/[a-z0-9]{26}` 

 ** [creationTime](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-creationTime"></a>
The time of when created the cluster.  
Type: Timestamp

 ** [deletionProtectionEnabled](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-deletionProtectionEnabled"></a>
Whether deletion protection is enabled on this cluster.  
Type: Boolean

 ** [encryptionDetails](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-encryptionDetails"></a>
The encryption configuration for the cluster that was specified during the creation process, including the AWS KMS key identifier and encryption state.  
Type: [EncryptionDetails](API_EncryptionDetails.md) object

 ** [endpoint](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-endpoint"></a>
The connection endpoint for the created cluster.  
Type: String  
Pattern: `[a-zA-Z0-9.-]+` 

 ** [identifier](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-identifier"></a>
The ID of the created cluster.  
Type: String  
Pattern: `[a-z0-9]{26}` 

 ** [multiRegionProperties](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-multiRegionProperties"></a>
The multi-Region cluster configuration details that were set during cluster creation  
Type: [MultiRegionProperties](API_MultiRegionProperties.md) object

 ** [status](#API_CreateCluster_ResponseSyntax) **   <a name="auroradsql-CreateCluster-response-status"></a>
The status of the created cluster.  
Type: String  
Valid Values: `CREATING | ACTIVE | IDLE | INACTIVE | UPDATING | DELETING | DELETED | FAILED | PENDING_SETUP | PENDING_DELETE` 

## Errors


For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md).

 ** AccessDeniedException **   
You do not have sufficient access to perform this action.  
HTTP Status Code: 403

 ** ConflictException **   
The submitted action has conflicts.    
 ** resourceId **   
Resource Id  
 ** resourceType **   
Resource Type
HTTP Status Code: 409

 ** InternalServerException **   
The request processing has failed because of an unknown error, exception or failure.    
 ** retryAfterSeconds **   
Retry after seconds.
HTTP Status Code: 500

 ** ServiceQuotaExceededException **   
The service limit was exceeded.    
 ** message **   
The service exception for exceeding a quota.  
 ** quotaCode **   
The service exceeds a quota.  
 ** resourceId **   
The resource ID exceeds a quota.  
 ** resourceType **   
The resource type exceeds a quota.  
 ** serviceCode **   
The request exceeds a service quota.
HTTP Status Code: 402

 ** ThrottlingException **   
The request was denied due to request throttling.    
 ** message **   
The message that the request was denied due to request throttling.  
 ** quotaCode **   
The request exceeds a request rate quota.  
 ** retryAfterSeconds **   
The request exceeds a request rate quota. Retry after seconds.  
 ** serviceCode **   
The request exceeds a service quota.
HTTP Status Code: 429

 ** ValidationException **   
The input failed to satisfy the constraints specified by an AWS service.    
 ** fieldList **   
A list of fields that didn't validate.  
 ** reason **   
The reason for the validation exception.
HTTP Status Code: 400

## See Also


For more information about using this API in one of the language-specific AWS SDKs, see the following:
+  [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/dsql-2018-05-10/CreateCluster) 
+  [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/dsql-2018-05-10/CreateCluster)