Managed Service for Elasticsearch API, REST: Cluster.Create

Written by

Updated at December 17, 2024

HTTP request
Body parameters
ConfigSpec
ElasticsearchSpec
DataNode
ElasticsearchConfig7
Resources
MasterNode
UserSpec
HostSpec
MaintenanceWindow
WeeklyMaintenanceWindow
ExtensionSpec
Response
CreateClusterMetadata
Status
Cluster
Monitoring
ClusterConfig
Elasticsearch
DataNode
ElasticsearchConfigSet7
ElasticsearchConfig7
Resources
MasterNode
MaintenanceWindow
WeeklyMaintenanceWindow
MaintenanceOperation

Creates a new Elasticsearch cluster in the specified folder.

HTTP request

POST https://mdb.api.cloud.yandex.net/managed-elasticsearch/v1/clusters

Body parameters

{
  "folderId": "string",
  "name": "string",
  "description": "string",
  "labels": "object",
  "environment": "string",
  "configSpec": {
    "version": "string",
    "elasticsearchSpec": {
      "dataNode": {
        // Includes only one of the fields `elasticsearchConfig_7`
        "elasticsearchConfig_7": {
          "maxClauseCount": "string",
          "fielddataCacheSize": "string",
          "reindexRemoteWhitelist": "string",
          "reindexSslCaPath": "string"
        },
        // end of the list of possible fields
        "resources": {
          "resourcePresetId": "string",
          "diskSize": "string",
          "diskTypeId": "string"
        }
      },
      "masterNode": {
        "resources": {
          "resourcePresetId": "string",
          "diskSize": "string",
          "diskTypeId": "string"
        }
      },
      "plugins": [
        "string"
      ]
    },
    "edition": "string",
    "adminPassword": "string"
  },
  "userSpecs": [
    {
      "name": "string",
      "password": "string"
    }
  ],
  "hostSpecs": [
    {
      "zoneId": "string",
      "subnetId": "string",
      "assignPublicIp": "boolean",
      "type": "string",
      "shardName": "string"
    }
  ],
  "networkId": "string",
  "securityGroupIds": [
    "string"
  ],
  "serviceAccountId": "string",
  "deletionProtection": "boolean",
  "maintenanceWindow": {
    // Includes only one of the fields `anytime`, `weeklyMaintenanceWindow`
    "anytime": "object",
    "weeklyMaintenanceWindow": {
      "day": "string",
      "hour": "string"
    }
    // end of the list of possible fields
  },
  "extensionSpecs": [
    {
      "name": "string",
      "uri": "string",
      "disabled": "boolean"
    }
  ]
}

Field	Description
folderId	string Required field. ID of the folder to create the Elasticsearch cluster in.
name	string Required field. Name of the Elasticsearch cluster. The name must be unique within the folder.
description	string Description of the Elasticsearch cluster.
labels	object (map<string, string>) Custom labels for the Elasticsearch cluster as `key:value` pairs. For example, "project": "mvp" or "source": "dictionary".
environment	enum (Environment) Deployment environment of the Elasticsearch cluster. `ENVIRONMENT_UNSPECIFIED` `PRODUCTION`: Stable environment with a conservative update policy when only hotfixes are applied during regular maintenance. `PRESTABLE`: Environment with a more aggressive update policy when new versions are rolled out irrespective of backward compatibility.
configSpec	ConfigSpec Required field. Elasticsearch and hosts configuration for the cluster.
userSpecs[]	UserSpec One or more descriptions of users to be created in Elasticsearch cluster.
hostSpecs[]	HostSpec One or more configurations of hosts to be created in the Elasticsearch cluster.
networkId	string Required field. ID of the network to create the Elasticsearch cluster in.
securityGroupIds[]	string User security groups
serviceAccountId	string ID of the service account used for access to Object Storage.
deletionProtection	boolean Deletion Protection inhibits deletion of the cluster
maintenanceWindow	MaintenanceWindow Window of maintenance operations.
extensionSpecs[]	ExtensionSpec optional

ConfigSpec

Field	Description
version	string Elasticsearch version.
elasticsearchSpec	ElasticsearchSpec Configuration and resource allocation for Elasticsearch nodes.
edition	string ElasticSearch edition.
adminPassword	string Required field. ElasticSearch admin password.

ElasticsearchSpec

Field	Description
dataNode	DataNode Configuration and resource allocation for Elasticsearch data nodes.
masterNode	MasterNode Configuration and resource allocation for Elasticsearch master nodes.
plugins[]	string Cluster wide plugins

DataNode

Field

Description

elasticsearchConfig_7

ElasticsearchConfig7

Includes only one of the fields elasticsearchConfig_7.

Elasticsearch data node configuration.

resources

Resources

Resources allocated to Elasticsearch data nodes.

ElasticsearchConfig7

Elasticsearch 7.x supported configuration options are listed here.

Detailed description for each set of options is available in Elasticsearch documentation.

Any options that are not listed here are not supported.

Field	Description
maxClauseCount	string (int64) The maximum number of clauses a boolean query can contain. The limit is in place to prevent searches from becoming too large and taking up too much CPU and memory. It affects not only Elasticsearch's `bool` query, but many other queries that are implicitly converted to `bool` query by Elastcsearch. Default value: `1024`. See in-depth description in Elasticsearch documentation.
fielddataCacheSize	string The maximum percentage or absolute value (10%, 512mb) of heap space that is allocated to field data cache. All the field values that are placed in this cache, get loaded to memory in order to provide fast document based access to those values. Building the field data cache for a field can be an expensive operations, so its recommended to have enough memory for this cache, and to keep it loaded. Default value: unbounded. See in-depth description in Elasticsearch documentation.
reindexRemoteWhitelist	string Remote hosts for reindex have to be explicitly allowed in elasticsearch.yml using the reindex.remote.whitelist property. It can be set to a comma delimited list of allowed remote host and port combinations. Scheme is ignored, only the host and port are used.
reindexSslCaPath	string List of paths to PEM encoded certificate files that should be trusted. See in-depth description in Elasticsearch documentation

Resources

Computational resources.

Field	Description
resourcePresetId	string ID of the preset for computational resources available to a host (CPU, memory etc.). All available presets are listed in the documentation.
diskSize	string (int64) Volume of the storage available to a host, in bytes.
diskTypeId	string Type of the storage environment for the host. All available types are listed in the documentation.

MasterNode

Field

Description

resources

Resources

Resources allocated to Elasticsearch master nodes.

UserSpec

Field

Description

name

string

Required field. Name of the Elasticsearch user.

password

string

Required field. Password of the Elasticsearch user.

HostSpec

Field	Description
zoneId	string ID of the availability zone where the host resides.
subnetId	string ID of the subnet the host resides in.
assignPublicIp	boolean The flag that defines whether a public IP address is assigned to the host. If the value is `true`, then this host is available on the Internet via it's public IP address.
type	enum (Type) Required field. Host type. `TYPE_UNSPECIFIED`: Host type is unspecified. Default value. `DATA_NODE`: The host is an Elasticsearch data node. `MASTER_NODE`: The host is an Elasticsearch master node.
shardName	string The shard name to create on the host.

MaintenanceWindow

Field

Description

anytime

object

Includes only one of the fields anytime, weeklyMaintenanceWindow.

weeklyMaintenanceWindow

WeeklyMaintenanceWindow

Includes only one of the fields anytime, weeklyMaintenanceWindow.

WeeklyMaintenanceWindow

Field

Description

day

enum (WeekDay)

WEEK_DAY_UNSPECIFIED
MON
TUE
WED
THU
FRI
SAT
SUN

hour

string (int64)

Hour of the day in UTC.

ExtensionSpec

Field	Description
name	string Required field. Name of the extension.
uri	string URI of the zip archive to create the new extension from. Currently only supports links that are stored in Object Storage.
disabled	boolean The flag shows whether to create the extension in disabled state.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": "boolean",
  "metadata": {
    "clusterId": "string"
  },
  // Includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": {
    "id": "string",
    "folderId": "string",
    "createdAt": "string",
    "name": "string",
    "description": "string",
    "labels": "object",
    "environment": "string",
    "monitoring": [
      {
        "name": "string",
        "description": "string",
        "link": "string"
      }
    ],
    "config": {
      "version": "string",
      "elasticsearch": {
        "dataNode": {
          // Includes only one of the fields `elasticsearchConfigSet_7`
          "elasticsearchConfigSet_7": {
            "effectiveConfig": {
              "maxClauseCount": "string",
              "fielddataCacheSize": "string",
              "reindexRemoteWhitelist": "string",
              "reindexSslCaPath": "string"
            },
            "userConfig": {
              "maxClauseCount": "string",
              "fielddataCacheSize": "string",
              "reindexRemoteWhitelist": "string",
              "reindexSslCaPath": "string"
            },
            "defaultConfig": {
              "maxClauseCount": "string",
              "fielddataCacheSize": "string",
              "reindexRemoteWhitelist": "string",
              "reindexSslCaPath": "string"
            }
          },
          // end of the list of possible fields
          "resources": {
            "resourcePresetId": "string",
            "diskSize": "string",
            "diskTypeId": "string"
          }
        },
        "masterNode": {
          "resources": {
            "resourcePresetId": "string",
            "diskSize": "string",
            "diskTypeId": "string"
          }
        },
        "plugins": [
          "string"
        ]
      },
      "edition": "string"
    },
    "networkId": "string",
    "health": "string",
    "status": "string",
    "securityGroupIds": [
      "string"
    ],
    "serviceAccountId": "string",
    "deletionProtection": "boolean",
    "maintenanceWindow": {
      // Includes only one of the fields `anytime`, `weeklyMaintenanceWindow`
      "anytime": "object",
      "weeklyMaintenanceWindow": {
        "day": "string",
        "hour": "string"
      }
      // end of the list of possible fields
    },
    "plannedOperation": {
      "info": "string",
      "delayedUntil": "string"
    }
  }
  // end of the list of possible fields
}

An Operation resource. For more information, see Operation.

Field	Description
id	string ID of the operation.
description	string Description of the operation. 0-256 characters long.
createdAt	string (date-time) Creation timestamp. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
createdBy	string ID of the user or service account who initiated the operation.
modifiedAt	string (date-time) The time when the Operation resource was last modified. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
done	boolean If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.
metadata	CreateClusterMetadata Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any.
error	Status The error result of the operation in case of failure or cancellation. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.
response	Cluster The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.

CreateClusterMetadata

Field

Description

clusterId

string

ID of the Elasticsearch cluster that is being created.

Status

The error result of the operation in case of failure or cancellation.

Field	Description
code	integer (int32) Error code. An enum value of google.rpc.Code.
message	string An error message.
details[]	object A list of messages that carry the error details.

Cluster

An Elasticsearch cluster resource.
For more information, see the Concepts section of the documentation.

Field	Description
id	string ID of the Elasticsearch cluster. This ID is assigned at creation time.
folderId	string ID of the folder that the Elasticsearch cluster belongs to.
createdAt	string (date-time) Creation timestamp. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
name	string Name of the Elasticsearch cluster. The name must be unique within the folder. 1-63 characters long.
description	string Description of the Elasticsearch cluster. 0-256 characters long.
labels	object (map<string, string>) Custom labels for the Elasticsearch cluster as `key:value` pairs. A maximum of 64 labels per resource is allowed.
environment	enum (Environment) Deployment environment of the Elasticsearch cluster. `ENVIRONMENT_UNSPECIFIED` `PRODUCTION`: Stable environment with a conservative update policy when only hotfixes are applied during regular maintenance. `PRESTABLE`: Environment with a more aggressive update policy when new versions are rolled out irrespective of backward compatibility.
monitoring[]	Monitoring Description of monitoring systems relevant to the Elasticsearch cluster.
config	ClusterConfig Configuration of the Elasticsearch cluster.
networkId	string ID of the network that the cluster belongs to.
health	enum (Health) Aggregated cluster health. `HEALTH_UNKNOWN`: State of the cluster is unknown (Host.health of all hosts in the cluster is `UNKNOWN`). `ALIVE`: Cluster is alive and well (Host.health of all hosts in the cluster is `ALIVE`). `DEAD`: Cluster is inoperable (Host.health of all hosts in the cluster is `DEAD`). `DEGRADED`: Cluster is in degraded state (Host.health of at least one of the hosts in the cluster is not `ALIVE`).
status	enum (Status) Current state of the cluster. `STATUS_UNKNOWN`: Cluster state is unknown. `CREATING`: Cluster is being created. `RUNNING`: Cluster is running normally. `ERROR`: Cluster encountered a problem and cannot operate. `UPDATING`: Cluster is being updated. `STOPPING`: Cluster is stopping. `STOPPED`: Cluster stopped. `STARTING`: Cluster is starting.
securityGroupIds[]	string User security groups
serviceAccountId	string ID of the service account used for access to Object Storage.
deletionProtection	boolean Deletion Protection inhibits deletion of the cluster
maintenanceWindow	MaintenanceWindow Window of maintenance operations.
plannedOperation	MaintenanceOperation Maintenance operation planned at nearest maintenance_window.

Monitoring

Metadata of monitoring system.

Field	Description
name	string Name of the monitoring system.
description	string Description of the monitoring system.
link	string Link to the monitoring system charts for the Elasticsearch cluster.

ClusterConfig

Field	Description
version	string Elasticsearch version.
elasticsearch	Elasticsearch Configuration and resource allocation for Elasticsearch nodes.
edition	string ElasticSearch edition.

Elasticsearch

Field	Description
dataNode	DataNode Configuration and resource allocation for Elasticsearch data nodes.
masterNode	MasterNode Configuration and resource allocation for Elasticsearch master nodes.
plugins[]	string Cluster wide plugins

DataNode

Field

Description

elasticsearchConfigSet_7

ElasticsearchConfigSet7

Elasticsearch 7.x data node configuration.

Includes only one of the fields elasticsearchConfigSet_7.

resources

Resources

Resources allocated to Elasticsearch data nodes.

ElasticsearchConfigSet7

Elasticsearch 7.x data node configuration.

Field	Description
effectiveConfig	ElasticsearchConfig7 Required field. Effective settings for an Elasticsearch cluster (a combination of settings defined in `userConfig` and `defaultConfig`).
userConfig	ElasticsearchConfig7 User-defined settings for an Elasticsearch cluster.
defaultConfig	ElasticsearchConfig7 Default settings for an Elasticsearch cluster.

ElasticsearchConfig7

Elasticsearch 7.x supported configuration options are listed here.

Detailed description for each set of options is available in Elasticsearch documentation.

Any options that are not listed here are not supported.

Field	Description
maxClauseCount	string (int64) The maximum number of clauses a boolean query can contain. The limit is in place to prevent searches from becoming too large and taking up too much CPU and memory. It affects not only Elasticsearch's `bool` query, but many other queries that are implicitly converted to `bool` query by Elastcsearch. Default value: `1024`. See in-depth description in Elasticsearch documentation.
fielddataCacheSize	string The maximum percentage or absolute value (10%, 512mb) of heap space that is allocated to field data cache. All the field values that are placed in this cache, get loaded to memory in order to provide fast document based access to those values. Building the field data cache for a field can be an expensive operations, so its recommended to have enough memory for this cache, and to keep it loaded. Default value: unbounded. See in-depth description in Elasticsearch documentation.
reindexRemoteWhitelist	string Remote hosts for reindex have to be explicitly allowed in elasticsearch.yml using the reindex.remote.whitelist property. It can be set to a comma delimited list of allowed remote host and port combinations. Scheme is ignored, only the host and port are used.
reindexSslCaPath	string List of paths to PEM encoded certificate files that should be trusted. See in-depth description in Elasticsearch documentation

Resources

Computational resources.

Field	Description
resourcePresetId	string ID of the preset for computational resources available to a host (CPU, memory etc.). All available presets are listed in the documentation.
diskSize	string (int64) Volume of the storage available to a host, in bytes.
diskTypeId	string Type of the storage environment for the host. All available types are listed in the documentation.

MasterNode

Field

Description

resources

Resources

Resources allocated to Elasticsearch master nodes.

MaintenanceWindow

Field

Description

anytime

object

Includes only one of the fields anytime, weeklyMaintenanceWindow.

weeklyMaintenanceWindow

WeeklyMaintenanceWindow

Includes only one of the fields anytime, weeklyMaintenanceWindow.

WeeklyMaintenanceWindow

Field

Description

day

enum (WeekDay)

WEEK_DAY_UNSPECIFIED
MON
TUE
WED
THU
FRI
SAT
SUN

hour

string (int64)

Hour of the day in UTC.

MaintenanceOperation

Field

Description

info

string

delayedUntil

string (date-time)

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

Managed Service for Elasticsearch API, REST: Cluster.Create

HTTP requestHTTP request

Body parametersBody parameters

ConfigSpecConfigSpec

ElasticsearchSpecElasticsearchSpec

DataNodeDataNode

ElasticsearchConfig7ElasticsearchConfig7

ResourcesResources

MasterNodeMasterNode

UserSpecUserSpec

HostSpecHostSpec

MaintenanceWindowMaintenanceWindow

WeeklyMaintenanceWindowWeeklyMaintenanceWindow

ExtensionSpecExtensionSpec

ResponseResponse

CreateClusterMetadataCreateClusterMetadata

StatusStatus

ClusterCluster

MonitoringMonitoring

ClusterConfigClusterConfig

ElasticsearchElasticsearch

DataNodeDataNode

ElasticsearchConfigSet7ElasticsearchConfigSet7

ElasticsearchConfig7ElasticsearchConfig7

ResourcesResources

MasterNodeMasterNode

MaintenanceWindowMaintenanceWindow

WeeklyMaintenanceWindowWeeklyMaintenanceWindow

MaintenanceOperationMaintenanceOperation

Was the article helpful?

HTTP request

Body parameters

ConfigSpec

ElasticsearchSpec

DataNode

ElasticsearchConfig7

Resources

MasterNode

UserSpec

HostSpec

MaintenanceWindow

WeeklyMaintenanceWindow

ExtensionSpec

Response

CreateClusterMetadata

Status

Cluster

Monitoring

ClusterConfig

Elasticsearch

DataNode

ElasticsearchConfigSet7

ElasticsearchConfig7

Resources

MasterNode

MaintenanceWindow

WeeklyMaintenanceWindow

MaintenanceOperation