Set instance configuration

PUT /platform/configuration/instances/{id}

Creates or updates an instance configuration.

Path parameters

id string Required

ID of the instance configuration

Query parameters

version integer

This is a database-level field, not related to the application-level 'config_version', except as described in the following docs. If specified, checks for conflicts against 'x-cloud-resource-version' from the GET request (where the 'config_version' in the GET should match the the 'configuration_version' in the PUT body if the IC is configuration controlled).
config_control boolean

If true, then an update that changes immutable fields will create a new version of the IC (leaving the previous ones accessible via 'config_version'). Otherwise such updates will fail.
test_config boolean

If true, The IC is added as a test version (set 'instance_config_version': -1 in the deployment request to reference), leaving the existing IC alone. Will error if the IC doesn't already exist.
strict_mode boolean

If true, then allocator_filter and storage_multiplier cannot be changed in an existing IC. Defaults to false unless config_control is true (in which case a new version is created)
create_only boolean

If true, will fail if an instance configuration already exists at the given id

Body Required

the Instance Configuration

id string

Unique identifier for the instance configuration
name string Required

Display name for the instance configuration.
config_version integer(int32)

If the IC is configuration controlled, this field is the version either being read back (reads return the latest IC unless specified by the 'config_version' URL param), or the version to update. Cannot be used in creates. For unversioned IC reads it is left empty.
description string

Optional description for the instance configuration
instance_type string

The type of instance. For instance configurations where the type is specified in the 'id', the default value of 'instance_type' will be automatically inferred.

Values are elasticsearch, kibana, apm, integrations_server, appsearch, or enterprise_search.
node_types array[string]

Node types (master, data) for the instance. For instance configurations where the type (and tier) is specified in the 'id', the default value of 'node_types' will be automatically inferred.
discrete_sizes object Required

Numerics representing possible instance sizes that the instance configuration supports.

Additional properties are allowed.
Hide discrete_sizes attributes Show discrete_sizes attributes object
- sizes array[integer(int32)] Required
  
  List of supported sizes
- default_size integer(int32)
  
  The default size
- resource string
  
  The unit that each size represents. If not specified, it will default to 'memory'.
  
  Values are memory or storage.
allocator_filter object

The container for all of the allowed Elasticsearch queries. Specify only one property each time.

Additional properties are allowed.
Hide allocator_filter attributes Show allocator_filter attributes object
- match object
  Hide match attribute Show match attribute object
  
  * object Additional properties
  
  Consumes and analyzes text, numbers, and dates, then constructs a query.
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  query string Required
  
  The text/numeric/date to query for.
  
  operator string
  
  The operator flag can be set to or or and to control the boolean clauses (defaults to or).
  
  minimum_should_match integer(int32)
  
  The minimum number of optional should clauses to match.
  
  analyzer string
  
  The analyzer that will be used to perform the analysis process on the text. Defaults to the analyzer that was used to index the field.
- match_all object
  
  A query that matches all documents.
  
  Additional properties are allowed.
- match_none object
  
  A query that doesn't match any documents.
  
  Additional properties are allowed.
- term object
  Hide term attribute Show term attribute object
  
  * object Additional properties
  
  A query for documents that contain the specified term in the inverted index.
  
  Additional properties are allowed.
  
  Hide * attribute Show * attribute object
  
  value string Required
  
  The exact value to query for.
- bool object
  
  A query for documents that match boolean combinations of other queries.
  
  Additional properties are allowed.
  Hide bool attributes Show bool attributes object
  
  must array[object]
  
  The container for all of the allowed Elasticsearch queries. Specify only one property each time.
  
  Additional properties are allowed.
  
  should array[object]
  
  The container for all of the allowed Elasticsearch queries. Specify only one property each time.
  
  Additional properties are allowed.
  
  must_not array[object]
  
  The container for all of the allowed Elasticsearch queries. Specify only one property each time.
  
  Additional properties are allowed.
  
  filter array[object]
  
  The container for all of the allowed Elasticsearch queries. Specify only one property each time.
  
  Additional properties are allowed.
  
  minimum_should_match integer(int32)
  
  The minimum number of optional should clauses to match.
- query_string object
  
  A query that uses the strict query string syntax for parsing. Will return an error for invalid syntax.
  
  Additional properties are allowed.
  Hide query_string attributes Show query_string attributes object
  
  query string Required
  
  The actual query to be parsed.
  
  default_field string
  
  The default field for query terms if no prefix field is specified.
  
  analyzer string
  
  The analyzer used to analyze each term of the query when creating composite queries.
  
  default_operator string
  
  The default operator used if no explicit operator is specified.
  
  allow_leading_wildcard boolean
  
  When set, * or ? are allowed as the first character. Defaults to false.
- nested object
  
  A query that matches nested objects.
  
  Additional properties are allowed.
  Hide nested attributes Show nested attributes object
  
  query object Required
  
  The container for all of the allowed Elasticsearch queries. Specify only one property each time.
  
  Additional properties are allowed.
  
  path string Required
  
  The path to the nested object.
  
  score_mode string
  
  Allows to specify how inner children matching affects score of the parent. Refer to the Elasticsearch documentation for details.
  
  Values are avg, sum, min, max, or none.
- prefix object
  Hide prefix attribute Show prefix attribute object
  
  * object Additional properties
  
  The query that matches documents with fields that contain terms with a specified, not analyzed, prefix.
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  value string Required
  
  The prefix to search for.
  
  boost number(float)
  
  An optional boost value to apply to the query.
- exists object
  
  Matches documents that have at least one non-null value in the original field.
  
  Additional properties are allowed.
  Hide exists attribute Show exists attribute object
  
  field string Required
  
  The field to check for non-null values in.
- range object
  Hide range attribute Show range attribute object
  
  * object Additional properties
  
  The query that matches documents with fields that contain terms within a specified range.
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  gt object
  
  Greater-than
  
  Additional properties are allowed.
  
  gte object
  
  Greater-than or equal to
  
  Additional properties are allowed.
  
  lt object
  
  Less-than
  
  Additional properties are allowed.
  
  lte object
  
  Less-than or equal to.
  
  Additional properties are allowed.
  
  boost number(float)
  
  An optional boost value to apply to the query.
  
  format string
  
  Formatted dates will be parsed using the format specified on the date field by default, but it can be overridden by passing the format parameter.
  
  time_zone string
  
  Dates can be converted from another timezone to UTC either by specifying the time zone in the date value itself (if the format accepts it), or it can be specified as the time_zone parameter.
- simple_query_string object
  
  A query that uses simple query string syntax. Will ignore invalid syntax.
  
  Additional properties are allowed.
  Hide simple_query_string attributes Show simple_query_string attributes object
  
  query string Required
  
  The query expressed in simple query string syntax.
  
  fields array[string]
  
  Array of fields to search
  
  default_operator string
  
  The boolean operator used to combine the terms of the query. Valid values are OR (default) and AND.
  
  analyze_wildcard boolean
  
  If true, the query attempts to analyze wildcard terms. Defaults to false.
  
  analyzer string
  
  The name of the analyzer to use to convert the query text into tokens.
  
  auto_generate_synonyms_phrase_query boolean
  
  If true, the parse creates a match_phrase uery for each multi-position token. Defaults to true.
  
  flags string
  
  List of enabled operators for the simple query string syntax. Defaults to ALL.
  
  fuzzy_max_expansions integer(int32)
  
  Maximum number of terms to which the query expands for fuzzy matching. Defaults to 50.
  
  fuzzy_prefix_length integer(int32)
  
  Number of beginning characters left unchanged for fuzzy matching. Defaults to 0.
  
  fuzzy_transpositions boolean
  
  If true, edits for fuzzy matching include transpositions of two adjacent characters. Defaults to false.
  
  lenient boolean
  
  If true, format-based errors, such as providing a text value for a numeric field are ignored. Defaults to false.
  
  minimum_should_match string
  
  Minimum number of clauses that must match for a document to be returned.
  
  quote_field_suffix string
  
  Suffix appended to quoted text in the query string.
storage_multiplier number(double)

Settings for the instance storage multiplier
deleted_on string(date-time)

Date/time that this instance configuration was marked for deletion
system_owned boolean

Indicates if a instance configuration is system owned (restricts the set of operations that can be performed on it)
metadata object

Optional arbitrary metadata to associate with this template.

Additional properties are allowed.
cpu_multiplier number(double)

Settings for the instance CPU multiplier
allowed_zones array[string]

The zones this instance configuration may exist in. Leaving out this parameter or specifying an empty list implies all zones are allowed. Normally not needed, but can be useful for exceptional infrastructure constraints.

Responses

200

The instance configuration was updated successfully.
Hide response attributes Show response attributes object
- id string Required
  
  The ID
- config_version object
  
  The version, if the entity is configuration controlled
  
  Additional properties are allowed.
- config_version_updated object
  
  Returns true if the update resulted in a new version of the configuration controlled entity
  
  Additional properties are allowed.
201

The instance configuration was created successfully.
Hide response attributes Show response attributes object
- id string Required
  
  The ID
- config_version object
  
  The version, if the entity is configuration controlled
  
  Additional properties are allowed.
- config_version_updated object
  
  Returns true if the update resulted in a new version of the configuration controlled entity
  
  Additional properties are allowed.
400

cluster_type in the InstanceConfiguration model is invalid (code: 'configuration.invalid_cluster_type') or the ZooKeeper operation failed due to bad version, etc. (code: 'configuration.instance_configuration_update_failed') or the id in the InstanceConfiguration model is reserved/prohibited (code: 'configuration.configuration_id_reserved') or the discrete_sizes in the InstanceConfiguration model is invalid (code: 'configuration.invalid_discrete_sizes') or the metadata in the InstanceConfiguration model has empty keys or values (code: 'configuration.bad_meta_data')
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields
403

system_owned or deleted_on cannot be set externally (code: 'configuration.system_owned')
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields
404

Instance configuration specified by {id} cannot be found or the operation failed (code: 'configuration.instance_configuration_not_found')
Hide response attribute Show response attribute object
- errors array[object] Required
  
  A list of errors that occurred in the failing request
  
  Hide errors attributes Show errors attributes object
  
  code string Required
  
  A structured code representing the error type that occurred
  
  message string Required
  
  A human readable message describing the error that occurred
  
  fields array[string]
  
  If the error can be tied to a specific field or fields in the user request, this lists those fields

PUT /platform/configuration/instances/{id}

curl \
 -X PUT https://{{hostname}}/api/v1/platform/configuration/instances/{id} \
 -d '{"id":"string","name":"string","config_version":42,"description":"string","instance_type":"elasticsearch","node_types":["string"],"discrete_sizes":{"sizes":[42],"default_size":42,"resource":"memory"},"allocator_filter":{"match":{"additionalProperty1":{"query":"string","operator":"string","minimum_should_match":42,"analyzer":"string"},"additionalProperty2":{"query":"string","operator":"string","minimum_should_match":42,"analyzer":"string"}},"match_all":{},"match_none":{},"term":{"additionalProperty1":{"value":"string"},"additionalProperty2":{"value":"string"}},"bool":{"must":[{}],"should":[{}],"must_not":[{}],"filter":[{}],"minimum_should_match":42},"query_string":{"query":"string","default_field":"string","analyzer":"string","default_operator":"string","allow_leading_wildcard":true},"nested":{"query":{},"path":"string","score_mode":"avg"},"prefix":{"additionalProperty1":{"value":"string","boost":42.0},"additionalProperty2":{"value":"string","boost":42.0}},"exists":{"field":"string"},"range":{"additionalProperty1":{"gt":{},"gte":{},"lt":{},"lte":{},"boost":42.0,"format":"string","time_zone":"string"},"additionalProperty2":{"gt":{},"gte":{},"lt":{},"lte":{},"boost":42.0,"format":"string","time_zone":"string"}},"simple_query_string":{"query":"string","fields":["string"],"default_operator":"string","analyze_wildcard":true,"analyzer":"string","auto_generate_synonyms_phrase_query":true,"flags":"string","fuzzy_max_expansions":42,"fuzzy_prefix_length":42,"fuzzy_transpositions":true,"lenient":true,"minimum_should_match":"string","quote_field_suffix":"string"}},"storage_multiplier":42.0,"deleted_on":"2024-05-04T09:42:00+00:00","system_owned":true,"metadata":{},"cpu_multiplier":42.0,"allowed_zones":["string"]}'

Request examples

{
  "id": "string",
  "name": "string",
  "config_version": 42,
  "description": "string",
  "instance_type": "elasticsearch",
  "node_types": [
    "string"
  ],
  "discrete_sizes": {
    "sizes": [
      42
    ],
    "default_size": 42,
    "resource": "memory"
  },
  "allocator_filter": {
    "match": {
      "additionalProperty1": {
        "query": "string",
        "operator": "string",
        "minimum_should_match": 42,
        "analyzer": "string"
      },
      "additionalProperty2": {
        "query": "string",
        "operator": "string",
        "minimum_should_match": 42,
        "analyzer": "string"
      }
    },
    "match_all": {},
    "match_none": {},
    "term": {
      "additionalProperty1": {
        "value": "string"
      },
      "additionalProperty2": {
        "value": "string"
      }
    },
    "bool": {
      "must": [
        {}
      ],
      "should": [
        {}
      ],
      "must_not": [
        {}
      ],
      "filter": [
        {}
      ],
      "minimum_should_match": 42
    },
    "query_string": {
      "query": "string",
      "default_field": "string",
      "analyzer": "string",
      "default_operator": "string",
      "allow_leading_wildcard": true
    },
    "nested": {
      "query": {},
      "path": "string",
      "score_mode": "avg"
    },
    "prefix": {
      "additionalProperty1": {
        "value": "string",
        "boost": 42.0
      },
      "additionalProperty2": {
        "value": "string",
        "boost": 42.0
      }
    },
    "exists": {
      "field": "string"
    },
    "range": {
      "additionalProperty1": {
        "gt": {},
        "gte": {},
        "lt": {},
        "lte": {},
        "boost": 42.0,
        "format": "string",
        "time_zone": "string"
      },
      "additionalProperty2": {
        "gt": {},
        "gte": {},
        "lt": {},
        "lte": {},
        "boost": 42.0,
        "format": "string",
        "time_zone": "string"
      }
    },
    "simple_query_string": {
      "query": "string",
      "fields": [
        "string"
      ],
      "default_operator": "string",
      "analyze_wildcard": true,
      "analyzer": "string",
      "auto_generate_synonyms_phrase_query": true,
      "flags": "string",
      "fuzzy_max_expansions": 42,
      "fuzzy_prefix_length": 42,
      "fuzzy_transpositions": true,
      "lenient": true,
      "minimum_should_match": "string",
      "quote_field_suffix": "string"
    }
  },
  "storage_multiplier": 42.0,
  "deleted_on": "2024-05-04T09:42:00+00:00",
  "system_owned": true,
  "metadata": {},
  "cpu_multiplier": 42.0,
  "allowed_zones": [
    "string"
  ]
}

Response examples (200)

{
  "id": "string",
  "config_version": {},
  "config_version_updated": {}
}

Response examples (201)

{
  "id": "string",
  "config_version": {},
  "config_version_updated": {}
}

Response examples (400)

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Response examples (403)

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Response examples (404)

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}