Platform - Allocators

Get allocators

Retrieves the information for all of the allocators in the platform.

Request

GET /api/v1/platform/infrastructure/allocators

Query parameters

Name Type Required Description

q

string

N

(Optional) The query that filters the allocators. Maps to an Elasticsearch query_string query.

Responses

200
(AllocatorOverview) The allocator information is retrieved.
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators \
-u $CLOUD_USER:$CLOUD_KEY

Search allocators

Retrieves the information for all of the allocators in the platform that match the specified query.

Request

POST /api/v1/platform/infrastructure/allocators/_search

Request body

(SearchRequest) The optional search request to execute. If not supplied then all allocators are matched

Responses

200
(AllocatorOverview) The search request succeeded.
400
(BasicFailedReply) The search request failed.
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/_search \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "from" : 0,
   "query" : {
      "bool" : {
         "filter" : [
            null
         ],
         "minimum_should_match" : 0,
         "must" : [
            null
         ],
         "must_not" : [
            null
         ],
         "should" : [
            null
         ]
      },
      "exists" : {
         "field" : "string"
      },
      "match" : {
         "some_property" : {
            "analyzer" : "string",
            "minimum_should_match" : 0,
            "operator" : "string",
            "query" : "string"
         }
      },
      "match_all" : {},
      "match_none" : {},
      "nested" : {
         "path" : "string",
         "query" : null,
         "score_mode" : "string"
      },
      "prefix" : {
         "some_property" : {
            "boost" : 0.1,
            "value" : "string"
         }
      },
      "query_string" : {
         "allow_leading_wildcard" : true,
         "analyzer" : "string",
         "default_field" : "string",
         "default_operator" : "string",
         "query" : "string"
      },
      "range" : {
         "some_property" : {
            "boost" : 0.1,
            "format" : "string",
            "gt" : {},
            "gte" : {},
            "lt" : {},
            "lte" : {},
            "time_zone" : "string"
         }
      },
      "term" : {
         "some_property" : {
            "value" : {}
         }
      }
   },
   "size" : 0,
   "sort" : [
      "string"
   ]
}
'

Delete allocator

Deletes the allocator.

Request

DELETE /api/v1/platform/infrastructure/allocators/{allocator_id}

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Query parameters

Name Type Required Description

remove_instances

boolean

N

Removes the instances from the deleted allocator.

Responses

200
(EmptyResponse) The allocator is deleted.
400
(BasicFailedReply) The {allocator_id} can't be deleted.
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XDELETE {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id} \
-u $CLOUD_USER:$CLOUD_KEY

Get allocator

Retrieves the allocator by the ID.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Responses

200
(AllocatorInfo) The allocator information is retrieved.
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id} \
-u $CLOUD_USER:$CLOUD_KEY

Resynchronize allocator

Immediately synchronizes the allocator information in the back-end search index and caches.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/_resync

Path parameters

Name Type Required Description

allocator_id

string

Y

Allocator identifier

Responses

200
(EmptyResponse) The resynchronization succeeded.
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
500
(BasicFailedReply) The resynchronization failed. (code: 'allocators.resync_failed')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/_resync \
-u $CLOUD_USER:$CLOUD_KEY

Move clusters

Moves the clusters to a different allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/_move

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Query parameters

Name Type Required Description

allocator_down

boolean

N

When true, considers all instances on the allocator as permanently shut down when deciding how to migrate data to new nodes.When left blank, the system automatically decides. NOTE: The default treats the allocator as up.

force_update

boolean; default: false

N

When true, cancels and overwrites the pending plans, or treats the instance as an error.

move_only

boolean; default: true

N

When true, moves the specified instances and ignores the changes for the cluster state.

validate_only

boolean; default: false

N

When true, validates the plan overrides, then returns the plan without performing the move.

Request body

(MoveClustersRequest) Overrides defaults for the move of each cluster

Responses

202
(MoveClustersCommandResponse) The move is in progress. To monitor progress, use the GET command on the /{cluster_id} resource.
400
(BasicFailedReply) The Elasticsearch cluster plan contains errors. (code: 'clusters.cluster_invalid_plan' and 'clusters.plan_feature_not_implemented')
403
(BasicFailedReply) The move command is prohibited for the allocator.
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/_move \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "apm_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  {
                     "allocator_down" : true,
                     "from" : "string",
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "move_instances" : [
                  {
                     "from" : "string",
                     "instance_down" : true,
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : {
               "grow_and_shrink" : {},
               "rolling" : {
                  "allow_inline_resize" : true,
                  "group_by" : "string",
                  "shard_init_wait_time" : 0,
                  "skip_synced_flush" : true
               },
               "rolling_grow_and_shrink" : {}
            }
         }
      }
   ],
   "elasticsearch_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "cluster_settings_json" : {},
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "max_snapshot_age" : 0,
               "max_snapshot_attempts" : 0,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "move_only" : true,
               "override_failsafe" : true,
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "skip_data_migration" : true,
               "skip_post_upgrade_steps" : true,
               "skip_snapshot" : true,
               "skip_upgrade_checker" : true,
               "timeout" : 0
            },
            "restore_snapshot" : {
               "repository_config" : {
                  "raw_settings" : {}
               },
               "repository_name" : "string",
               "restore_payload" : {
                  "indices" : [
                     "string"
                  ],
                  "raw_settings" : {}
               },
               "snapshot_name" : "string",
               "source_cluster_id" : "string",
               "strategy" : "string"
            },
            "strategy" : null
         }
      }
   ],
   "kibana_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : null
         }
      }
   ]
}
'

Move clusters by type

Moves the clusters, by type, to a different allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/{cluster_type}/_move

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

cluster_type

string; allowed values: [elasticsearch, kibana]

Y

The cluster types to move off of the allocator. NOTE: When unspecified, all clusters are moved.

Query parameters

Name Type Required Description

allocator_down

boolean; default: false

N

When true, considers all instances on the allocator as permanently shut down when deciding how to migrate data to new nodes.When left blank, the system automatically decides. NOTE: The default treats the allocator as up.

force_update

boolean; default: false

N

When true, cancels and overwrites pending plans, or treats instance as an error

move_only

boolean; default: true

N

When true, bypasses the cluster state changes, but continues to move the specified instances

validate_only

boolean; default: false

N

When true, validates the plan overrides, then returns the plan without performing the move.

Request body

(MoveClustersRequest) Overrides defaults for the move of each cluster

Responses

202
(MoveClustersCommandResponse) The move is in progress. To monitor progress, use the GET command on the /{cluster_id} resource.
400
(BasicFailedReply) The Elasticsearch cluster plan contains errors. (code: 'clusters.cluster_invalid_plan' and 'clusters.plan_feature_not_implemented')
403
(BasicFailedReply) The move command is prohibited for the allocator.
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/clusters/{cluster_type}/_move \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "apm_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  {
                     "allocator_down" : true,
                     "from" : "string",
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "move_instances" : [
                  {
                     "from" : "string",
                     "instance_down" : true,
                     "to" : [
                        "string"
                     ]
                  }
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : {
               "grow_and_shrink" : {},
               "rolling" : {
                  "allow_inline_resize" : true,
                  "group_by" : "string",
                  "shard_init_wait_time" : 0,
                  "skip_synced_flush" : true
               },
               "rolling_grow_and_shrink" : {}
            }
         }
      }
   ],
   "elasticsearch_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "cluster_settings_json" : {},
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "max_snapshot_age" : 0,
               "max_snapshot_attempts" : 0,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "move_only" : true,
               "override_failsafe" : true,
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "skip_data_migration" : true,
               "skip_post_upgrade_steps" : true,
               "skip_snapshot" : true,
               "skip_upgrade_checker" : true,
               "timeout" : 0
            },
            "restore_snapshot" : {
               "repository_config" : {
                  "raw_settings" : {}
               },
               "repository_name" : "string",
               "restore_payload" : {
                  "indices" : [
                     "string"
                  ],
                  "raw_settings" : {}
               },
               "snapshot_name" : "string",
               "source_cluster_id" : "string",
               "strategy" : "string"
            },
            "strategy" : null
         }
      }
   ],
   "kibana_clusters" : [
      {
         "cluster_ids" : [
            "string"
         ],
         "plan_override" : {
            "plan_configuration" : {
               "calm_wait_time" : 0,
               "cluster_reboot" : "string",
               "extended_maintenance" : true,
               "move_allocators" : [
                  null
               ],
               "move_instances" : [
                  null
               ],
               "preferred_allocators" : [
                  "string"
               ],
               "reallocate_instances" : true,
               "timeout" : 0
            },
            "strategy" : null
         }
      }
   ]
}
'

Start maintenance mode

Starts maintenance mode on the allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_start

Path parameters

Name Type Required Description

allocator_id

string

Y

Allocator identifier

Responses

202
(EmptyResponse) The start maintenance mode command was issued successfully
403
(BasicFailedReply) The start maintenance mode command was prohibited for the given cluster.
404
(BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_start \
-u $CLOUD_USER:$CLOUD_KEY

Stop maintenance mode

Stops maintenance mode on the allocator.

Request

POST /api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_stop

Path parameters

Name Type Required Description

allocator_id

string

Y

Allocator identifier

Responses

202
(EmptyResponse) The stop maintenance mode command was issued successfully
403
(BasicFailedReply) The stop maintenance mode command was prohibited for the given cluster.
404
(BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPOST {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/maintenance-mode/_stop \
-u $CLOUD_USER:$CLOUD_KEY

Get allocator metadata

Retrieves the allocator metadata.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Responses

200

(array[MetadataItem]) The allocator metadata is returned.

Headers

x-cloud-resource-created (string)
The date-time when the resource was created (ISO format relative to UTC)
x-cloud-resource-last-modified (string)
The date-time when the resource was last modified (ISO format relative to UTC)
x-cloud-resource-version (string)
The resource version, which is used to avoid update conflicts with concurrent operations
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata \
-u $CLOUD_USER:$CLOUD_KEY

Set allocator metadata

Sets the allocator metadata.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Query parameters

Name Type Required Description

version

integer

N

Checks for conflicts against the metadata version, then returns the value in the x-cloud-resource-version header.

Request body

(MetadataItems) (required) The metadata to update the allocator with

Responses

200
(array[MetadataItem]) The allocator metadata successfully changed.
400
(BasicFailedReply) The metadata tag is missing. Specify the metadata tag value, then try again. (code: 'allocators.invalid_empty_metadata_items')
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "items" : [
      {
         "key" : "string",
         "value" : "string"
      }
   ]
}
'

Delete allocator metadata item

Removes a single item from the allocator metadata.

Request

DELETE /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key}

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

key

string

Y

The metadata item key to remove.

Query parameters

Name Type Required Description

version

integer

N

Checks for conflicts against the metadata version, then returns the value in the x-cloud-resource-version header.

Responses

200
(array[MetadataItem]) The allocator metadata item is deleted.
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XDELETE {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key} \
-u $CLOUD_USER:$CLOUD_KEY

Set allocator metadata item

Adds or updates a single item in the allocator metadata.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key}

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

key

string

Y

The metadata item key.

Query parameters

Name Type Required Description

version

integer

N

Checks for conflicts against the metadata version, then returns the value in the x-cloud-resource-version header.

Request body

(MetadataItemValue) (required) The value of the metadata item to add or update

Responses

200
(array[MetadataItem]) The allocator metadata was successfully changed (the updated JSON is returned)
400
(BasicFailedReply) The value specified for the metadata tag is empty (code: 'allocators.invalid_empty_metadata_item')
404
(BasicFailedReply) The allocator specified by {allocator_id} cannot be found (code: 'allocators.allocator_not_found') or the metadata item specified by {key} cannot be found (code: 'allocators.metadata_item_not_found')
449
(BasicFailedReply) elevated permissions are required. (code: '"root.unauthorized.rbac.elevated_permissions_required"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/metadata/{key} \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "value" : "string"
}
'

Get allocator settings

Retrieves the allocator override settings.

Request

GET /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Responses

200

(AllocatorSettings) The allocator settings are retrieved.

Headers

x-cloud-resource-created (string)
The date-time when the resource was created (ISO format relative to UTC)
x-cloud-resource-last-modified (string)
The date-time when the resource was last modified (ISO format relative to UTC)
x-cloud-resource-version (string)
The resource version, which is used to avoid update conflicts with concurrent operations
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XGET {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY

Update allocator settings

Applies the settings as a patch. Only the fields that are referenced in the update are altered.

Request

PATCH /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Query parameters

Name Type Required Description

version

integer

N

Checks for conflicts against the metadata version, then returns the value in the x-cloud-resource-version header.

Request body

(AllocatorSettings) (required) The allocator settings to update

Responses

200
(AllocatorSettings) The allocator settings successfully updated.
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPATCH {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "capacity" : 0
}
'

Set allocator settings

Overwrites the allocator settings with the specified settings. WARNING: Any unspecified fields are deleted.

Request

PUT /api/v1/platform/infrastructure/allocators/{allocator_id}/settings

Path parameters

Name Type Required Description

allocator_id

string

Y

The allocator identifier.

Query parameters

Name Type Required Description

version

integer

N

Checks for conflicts against the metadata version, then returns the value in the x-cloud-resource-version header.

Request body

(AllocatorSettings) (required) The allocator settings to apply

Responses

200
(AllocatorSettings) The allocator settings successfully changed.
404
(BasicFailedReply) The {allocator_id} can't be found. (code: 'allocators.allocator_not_found')
449
(BasicFailedReply) Elevated permissions are required. (code: '"root.needs_elevated_permissions"')
Warning

To perform this operation, you must be authenticated by means of one of the following methods: apiKey, basicAuth.

Request example

curl -XPUT {{hostname}}/api/v1/platform/infrastructure/allocators/{allocator_id}/settings \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "capacity" : 0
}
'