CreateDomain - Amazon OpenSearch Service

CreateDomain

Creates an Amazon OpenSearch Service domain. For more information, see Creating and managing Amazon OpenSearch Service domains.

Request Syntax

POST /2021-01-01/opensearch/domain HTTP/1.1 Content-type: application/json { "AccessPolicies": "string", "AdvancedOptions": { "string" : "string" }, "AdvancedSecurityOptions": { "AnonymousAuthEnabled": boolean, "Enabled": boolean, "InternalUserDatabaseEnabled": boolean, "MasterUserOptions": { "MasterUserARN": "string", "MasterUserName": "string", "MasterUserPassword": "string" }, "SAMLOptions": { "Enabled": boolean, "Idp": { "EntityId": "string", "MetadataContent": "string" }, "MasterBackendRole": "string", "MasterUserName": "string", "RolesKey": "string", "SessionTimeoutMinutes": number, "SubjectKey": "string" } }, "AutoTuneOptions": { "DesiredState": "string", "MaintenanceSchedules": [ { "CronExpressionForRecurrence": "string", "Duration": { "Unit": "string", "Value": number }, "StartAt": number } ], "UseOffPeakWindow": boolean }, "ClusterConfig": { "ColdStorageOptions": { "Enabled": boolean }, "DedicatedMasterCount": number, "DedicatedMasterEnabled": boolean, "DedicatedMasterType": "string", "InstanceCount": number, "InstanceType": "string", "MultiAZWithStandbyEnabled": boolean, "WarmCount": number, "WarmEnabled": boolean, "WarmType": "string", "ZoneAwarenessConfig": { "AvailabilityZoneCount": number }, "ZoneAwarenessEnabled": boolean }, "CognitoOptions": { "Enabled": boolean, "IdentityPoolId": "string", "RoleArn": "string", "UserPoolId": "string" }, "DomainEndpointOptions": { "CustomEndpoint": "string", "CustomEndpointCertificateArn": "string", "CustomEndpointEnabled": boolean, "EnforceHTTPS": boolean, "TLSSecurityPolicy": "string" }, "DomainName": "string", "EBSOptions": { "EBSEnabled": boolean, "Iops": number, "Throughput": number, "VolumeSize": number, "VolumeType": "string" }, "EncryptionAtRestOptions": { "Enabled": boolean, "KmsKeyId": "string" }, "EngineVersion": "string", "IPAddressType": "string", "LogPublishingOptions": { "string" : { "CloudWatchLogsLogGroupArn": "string", "Enabled": boolean } }, "NodeToNodeEncryptionOptions": { "Enabled": boolean }, "OffPeakWindowOptions": { "Enabled": boolean, "OffPeakWindow": { "WindowStartTime": { "Hours": number, "Minutes": number } } }, "SnapshotOptions": { "AutomatedSnapshotStartHour": number }, "SoftwareUpdateOptions": { "AutoSoftwareUpdateEnabled": boolean }, "TagList": [ { "Key": "string", "Value": "string" } ], "VPCOptions": { "SecurityGroupIds": [ "string" ], "SubnetIds": [ "string" ] } }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

AccessPolicies

Identity and Access Management (IAM) policy document specifying the access policies for the new domain.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 102400.

Pattern: .*

Required: No

AdvancedOptions

Key-value pairs to specify advanced configuration options. The following key-value pairs are supported:

  • "rest.action.multi.allow_explicit_index": "true" | "false" - Note the use of a string rather than a boolean. Specifies whether explicit references to indexes are allowed inside the body of HTTP requests. If you want to configure access policies for domain sub-resources, such as specific indexes and domain APIs, you must disable this property. Default is true.

  • "indices.fielddata.cache.size": "80" - Note the use of a string rather than a boolean. Specifies the percentage of heap space allocated to field data. Default is unbounded.

  • "indices.query.bool.max_clause_count": "1024" - Note the use of a string rather than a boolean. Specifies the maximum number of clauses allowed in a Lucene boolean query. Default is 1,024. Queries with more than the permitted number of clauses result in a TooManyClauses error.

  • "override_main_response_version": "true" | "false" - Note the use of a string rather than a boolean. Specifies whether the domain reports its version as 7.10 to allow Elasticsearch OSS clients and plugins to continue working with it. Default is false when creating a domain and true when upgrading a domain.

For more information, see Advanced cluster parameters.

Type: String to string map

Required: No

AdvancedSecurityOptions

Options for fine-grained access control.

Type: AdvancedSecurityOptionsInput object

Required: No

AutoTuneOptions

Options for Auto-Tune.

Type: AutoTuneOptionsInput object

Required: No

ClusterConfig

Container for the cluster configuration of a domain.

Type: ClusterConfig object

Required: No

CognitoOptions

Key-value pairs to configure Amazon Cognito authentication. For more information, see Configuring Amazon Cognito authentication for OpenSearch Dashboards.

Type: CognitoOptions object

Required: No

DomainEndpointOptions

Additional options for the domain endpoint, such as whether to require HTTPS for all traffic.

Type: DomainEndpointOptions object

Required: No

DomainName

Name of the OpenSearch Service domain to create. Domain names are unique across the domains owned by an account within an AWS Region.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 28.

Pattern: [a-z][a-z0-9\-]+

Required: Yes

EBSOptions

Container for the parameters required to enable EBS-based storage for an OpenSearch Service domain.

Type: EBSOptions object

Required: No

EncryptionAtRestOptions

Key-value pairs to enable encryption at rest.

Type: EncryptionAtRestOptions object

Required: No

EngineVersion

String of format Elasticsearch_X.Y or OpenSearch_X.Y to specify the engine version for the OpenSearch Service domain. For example, OpenSearch_1.0 or Elasticsearch_7.9. For more information, see Creating and managing Amazon OpenSearch Service domains.

Type: String

Length Constraints: Minimum length of 14. Maximum length of 18.

Pattern: ^Elasticsearch_[0-9]{1}\.[0-9]{1,2}$|^OpenSearch_[0-9]{1,2}\.[0-9]{1,2}$

Required: No

IPAddressType

Specify either dual stack or IPv4 as your IP address type. Dual stack allows you to share domain resources across IPv4 and IPv6 address types, and is the recommended option. If you set your IP address type to dual stack, you can't change your address type later.

Type: String

Valid Values: ipv4 | dualstack

Required: No

LogPublishingOptions

Key-value pairs to configure log publishing.

Type: String to LogPublishingOption object map

Valid Keys: INDEX_SLOW_LOGS | SEARCH_SLOW_LOGS | ES_APPLICATION_LOGS | AUDIT_LOGS

Required: No

NodeToNodeEncryptionOptions

Enables node-to-node encryption.

Type: NodeToNodeEncryptionOptions object

Required: No

OffPeakWindowOptions

Specifies a daily 10-hour time block during which OpenSearch Service can perform configuration changes on the domain, including service software updates and Auto-Tune enhancements that require a blue/green deployment. If no options are specified, the default start time of 10:00 P.M. local time (for the Region that the domain is created in) is used.

Type: OffPeakWindowOptions object

Required: No

SnapshotOptions

DEPRECATED. Container for the parameters required to configure automated snapshots of domain indexes.

Type: SnapshotOptions object

Required: No

SoftwareUpdateOptions

Software update options for the domain.

Type: SoftwareUpdateOptions object

Required: No

TagList

List of tags to add to the domain upon creation.

Type: Array of Tag objects

Required: No

VPCOptions

Container for the values required to configure VPC access domains. If you don't specify these values, OpenSearch Service creates the domain with a public endpoint. For more information, see Launching your Amazon OpenSearch Service domains using a VPC.

Type: VPCOptions object

Required: No

Response Syntax

HTTP/1.1 200 Content-type: application/json { "DomainStatus": { "AccessPolicies": "string", "AdvancedOptions": { "string" : "string" }, "AdvancedSecurityOptions": { "AnonymousAuthDisableDate": number, "AnonymousAuthEnabled": boolean, "Enabled": boolean, "InternalUserDatabaseEnabled": boolean, "SAMLOptions": { "Enabled": boolean, "Idp": { "EntityId": "string", "MetadataContent": "string" }, "RolesKey": "string", "SessionTimeoutMinutes": number, "SubjectKey": "string" } }, "ARN": "string", "AutoTuneOptions": { "ErrorMessage": "string", "State": "string", "UseOffPeakWindow": boolean }, "ChangeProgressDetails": { "ChangeId": "string", "ConfigChangeStatus": "string", "InitiatedBy": "string", "LastUpdatedTime": number, "Message": "string", "StartTime": number }, "ClusterConfig": { "ColdStorageOptions": { "Enabled": boolean }, "DedicatedMasterCount": number, "DedicatedMasterEnabled": boolean, "DedicatedMasterType": "string", "InstanceCount": number, "InstanceType": "string", "MultiAZWithStandbyEnabled": boolean, "WarmCount": number, "WarmEnabled": boolean, "WarmType": "string", "ZoneAwarenessConfig": { "AvailabilityZoneCount": number }, "ZoneAwarenessEnabled": boolean }, "CognitoOptions": { "Enabled": boolean, "IdentityPoolId": "string", "RoleArn": "string", "UserPoolId": "string" }, "Created": boolean, "Deleted": boolean, "DomainEndpointOptions": { "CustomEndpoint": "string", "CustomEndpointCertificateArn": "string", "CustomEndpointEnabled": boolean, "EnforceHTTPS": boolean, "TLSSecurityPolicy": "string" }, "DomainEndpointV2HostedZoneId": "string", "DomainId": "string", "DomainName": "string", "DomainProcessingStatus": "string", "EBSOptions": { "EBSEnabled": boolean, "Iops": number, "Throughput": number, "VolumeSize": number, "VolumeType": "string" }, "EncryptionAtRestOptions": { "Enabled": boolean, "KmsKeyId": "string" }, "Endpoint": "string", "Endpoints": { "string" : "string" }, "EndpointV2": "string", "EngineVersion": "string", "IPAddressType": "string", "LogPublishingOptions": { "string" : { "CloudWatchLogsLogGroupArn": "string", "Enabled": boolean } }, "ModifyingProperties": [ { "ActiveValue": "string", "Name": "string", "PendingValue": "string", "ValueType": "string" } ], "NodeToNodeEncryptionOptions": { "Enabled": boolean }, "OffPeakWindowOptions": { "Enabled": boolean, "OffPeakWindow": { "WindowStartTime": { "Hours": number, "Minutes": number } } }, "Processing": boolean, "ServiceSoftwareOptions": { "AutomatedUpdateDate": number, "Cancellable": boolean, "CurrentVersion": "string", "Description": "string", "NewVersion": "string", "OptionalDeployment": boolean, "UpdateAvailable": boolean, "UpdateStatus": "string" }, "SnapshotOptions": { "AutomatedSnapshotStartHour": number }, "SoftwareUpdateOptions": { "AutoSoftwareUpdateEnabled": boolean }, "UpgradeProcessing": boolean, "VPCOptions": { "AvailabilityZones": [ "string" ], "SecurityGroupIds": [ "string" ], "SubnetIds": [ "string" ], "VPCId": "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.

DomainStatus

The status of the newly created domain.

Type: DomainStatus object

Errors

For information about the errors that are common to all actions, see Common Errors.

BaseException

An error occurred while processing the request.

HTTP Status Code: 400

DisabledOperationException

An error occured because the client wanted to access an unsupported operation.

HTTP Status Code: 409

InternalException

Request processing failed because of an unknown error, exception, or internal failure.

HTTP Status Code: 500

InvalidTypeException

An exception for trying to create or access a sub-resource that's either invalid or not supported.

HTTP Status Code: 409

LimitExceededException

An exception for trying to create more than the allowed number of resources or sub-resources.

HTTP Status Code: 409

ResourceAlreadyExistsException

An exception for creating a resource that already exists.

HTTP Status Code: 409

ValidationException

An exception for accessing or deleting a resource that doesn't exist.

HTTP Status Code: 400

Examples

Example

This example illustrates one usage of CreateDomain.

Sample Request

POST /2021-01-01/opensearch/domain HTTP/1.1 Host: es.us-east-1.amazonaws.com Accept-Encoding: identity Content-Type: application/json User-Agent: aws-cli/2.15.0 Python/3.11.6 Darwin/23.3.0 exe/x86_64 prompt/off command/opensearch.create-domain X-Amz-Date: 20240212T202032Z X-Amz-Security-Token: IQoJb3JpZ2luX2VjEI3wEaCXVz== Authorization: AWS4-HMAC-SHA256 Credential=ASIAU/20240212/us-east-1/es/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-security-token, Signature=dfbf9b8975a263d23a24fead9c4a409a6c7ef1c42e67c96252bf9bb794d1ea52 Content-Length: 645 {"DomainName": "my-domain", "EngineVersion": "OpenSearch_2.11", "ClusterConfig": {"InstanceType": "r6g.xlarge.search", "InstanceCount": 10, "DedicatedMasterEnabled": true, "DedicatedMasterType": "r6g.large.search", "DedicatedMasterCount": 3}, "EBSOptions": {"EBSEnabled": true, "VolumeType": "io1", "VolumeSize": 100, "Iops": 1000}, "AccessPolicies": "{\"Version\": \"2012-10-17\", \"Statement\": [ { \"Effect\": \"Allow\", \"Principal\": { \"AWS\": \"arn:aws:iam::123456789012:root\" }, \"Action\": \"es:*\", \"Resource\": \"arn:aws:es:us-east-1:123456789012:domain/my-domain/*\" } ] }", "AutoTuneOptions": {"DesiredState": "ENABLED"}}

Sample Response

{ "DomainStatus": { "ARN": "arn:aws:es:us-east-1:123456789012:domain/my-domain", "AccessPolicies": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::478253424788:root\"},\"Action\":\"es:*\",\"Resource\":\"arn:aws:es:us-east-1:123456789012:domain/my-domain/*\"}]}", "AdvancedOptions": { "override_main_response_version": "false", "rest.action.multi.allow_explicit_index": "true" }, "AdvancedSecurityOptions": { "AnonymousAuthDisableDate": null, "AnonymousAuthEnabled": false, "Enabled": false, "InternalUserDatabaseEnabled": false, "SAMLOptions": null }, "AutoTuneOptions": { "ErrorMessage": null, "State": "ENABLE_IN_PROGRESS", "UseOffPeakWindow": false }, "ChangeProgressDetails": { "ChangeId": "388f35e8-5d0c-44ae-bcd1-ffd468df9908", "ConfigChangeStatus": "Pending", "InitiatedBy": "CUSTOMER", "LastUpdatedTime": 1.707769234762E9, "Message": null, "StartTime": 1.707769234762E9 }, "ClusterConfig": { "ColdStorageOptions": { "Enabled": false }, "DedicatedMasterCount": 3, "DedicatedMasterEnabled": true, "DedicatedMasterType": "r6g.large.search", "InstanceCount": 10, "InstanceType": "r6g.xlarge.search", "MultiAZWithStandbyEnabled": false, "WarmCount": null, "WarmEnabled": false, "WarmStorage": null, "WarmType": null, "ZoneAwarenessConfig": null, "ZoneAwarenessEnabled": false }, "CognitoOptions": { "Enabled": false, "IdentityPoolId": null, "RoleArn": null, "UserPoolId": null }, "Created": true, "Deleted": false, "DomainEndpointOptions": { "CustomEndpoint": null, "CustomEndpointCertificateArn": null, "CustomEndpointEnabled": false, "EnforceHTTPS": false, "TLSSecurityPolicy": "Policy-Min-TLS-1-0-2019-07" }, "DomainId": "123456789012/my-domain", "DomainName": "my-domain", "DomainProcessingStatus": "Creating", "EBSOptions": { "EBSEnabled": true, "Iops": 1000, "Throughput": null, "VolumeSize": 100, "VolumeType": "io1" }, "EncryptionAtRestOptions": { "Enabled": false, "KmsKeyId": null }, "Endpoint": null, "Endpoints": null, "EngineVersion": "OpenSearch_2.11", "IPAddressType": "ipv4", "LogPublishingOptions": null, "ModifyingProperties": [{ "ActiveValue": "", "Name": "AccessPolicies", "PendingValue": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"123456789012\"},\"Action\":\"es:*\",\"Resource\":\"arn:aws:es:us-east-1:123456789012:domain/my-domain/*\"}]}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "AdvancedOptions", "PendingValue": "{\"override_main_response_version\":\"false\",\"rest.action.multi.allow_explicit_index\":\"true\"}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "AdvancedSecurityOptions.AnonymousAuthDisableDate", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "AdvancedSecurityOptions.AnonymousAuthEnabled", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "AdvancedSecurityOptions.InternalUserDatabaseEnabled", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "AdvancedSecurityOptions.MasterUserOptions", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "AdvancedSecurityOptions.SAMLOptions", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.ColdStorageOptions", "PendingValue": "{\"Enabled\":false}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "ClusterConfig.DedicatedMasterCount", "PendingValue": "3", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.DedicatedMasterEnabled", "PendingValue": "true", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.DedicatedMasterType", "PendingValue": "r6g.large.search", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.InstanceCount", "PendingValue": "10", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.InstanceType", "PendingValue": "r6g.xlarge.search", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.MultiAZWithStandbyEnabled", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.WarmCount", "PendingValue": "", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "ClusterConfig.WarmEnabled", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "ClusterConfig.WarmStorage", "PendingValue": "", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "ClusterConfig.WarmType", "PendingValue": "", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "ClusterConfig.ZoneAwarenessEnabled", "PendingValue": "false", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "EngineVersion", "PendingValue": "OpenSearch_2.11", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "IPAddressType", "PendingValue": "ipv4", "ValueType": "PLAIN_TEXT" }, { "ActiveValue": "", "Name": "TAGS", "PendingValue": "", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "DomainEndpointOptions", "PendingValue": "{\"CustomEndpointEnabled\":false,\"EnforceHTTPS\":false,\"TLSSecurityPolicy\":\"Policy-Min-TLS-1-0-2019-07\"}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "EBSOptions", "PendingValue": "{\"EBSEnabled\":true,\"Iops\":1000,\"VolumeSize\":100,\"VolumeType\":\"io1\"}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "EncryptionAtRestOptions", "PendingValue": "{\"Enabled\":false}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "NodeToNodeEncryptionOptions", "PendingValue": "{\"Enabled\":false}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "OffPeakWindowOptions", "PendingValue": "{\"Enabled\":true,\"OffPeakWindow\":{\"WindowStartTime\":{\"Hours\":3,\"Minutes\":0}}}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "SnapshotOptions", "PendingValue": "{\"AutomatedSnapshotStartHour\":0}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "SoftwareUpdateOptions", "PendingValue": "{\"AutoSoftwareUpdateEnabled\":false}", "ValueType": "STRINGIFIED_JSON" }, { "ActiveValue": "", "Name": "AutoTuneOptions", "PendingValue": "{\"desiredState\":\"ENABLED\",\"rollbackOnDisable\":\"NO_ROLLBACK\",\"state\":\"ENABLE_IN_PROGRESS\",\"rollbackState\":\"ROLLBACK_OFF\",\"maintenanceSchedules\":[],\"useOffPeakWindow\":false}", "ValueType": "STRINGIFIED_JSON" }], "NodeToNodeEncryptionOptions": { "Enabled": false }, "OffPeakWindowOptions": { "Enabled": true, "OffPeakWindow": { "WindowStartTime": { "Hours": 3, "Minutes": 0 } } }, "Processing": true, "ServiceSoftwareOptions": { "AutomatedUpdateDate": 0.0, "Cancellable": false, "CurrentVersion": "", "Description": "There is no software update available for this domain.", "NewVersion": "", "OptionalDeployment": true, "UpdateAvailable": false, "UpdateStatus": "COMPLETED" }, "SnapshotOptions": { "AutomatedSnapshotStartHour": 0 }, "SoftwareUpdateOptions": { "AutoSoftwareUpdateEnabled": false }, "UpgradeProcessing": false, "VPCOptions": null } }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: