Clusters - Apm - CRUD - Configuration

Reset token

Resets the secret token for a given APM cluster.

Request

POST /api/v1/clusters/apm/{cluster_id}/_reset-token

Path parameters

Name Type Required Description

cluster_id

string

Y

APM instance identifier

Responses

200
(ApmCrudResponse) The token was successfully reset
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_not_found')
412
(BasicFailedReply) There is not currently applied plan - eg the cluster has not finished provisioning, or the provisioning failed (code: 'clusters.cluster_plan_state_error')
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/clusters/apm/{cluster_id}/_reset-token \
-u $CLOUD_USER:$CLOUD_KEY

Set cluster name

Assigns a name to the APM instance.

Request

PUT /api/v1/clusters/apm/{cluster_id}/metadata/name/{new_name}

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

new_name

string

Y

The new name for the cluster.

Responses

200
(EmptyResponse) The cluster name was successfully changed
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/metadata/name/{new_name} \
-u $CLOUD_USER:$CLOUD_KEY

Get cluster metadata

Advanced use only. Retrieves the internal metadata, in free-form JSON, for the APM instance.

Request

GET /api/v1/clusters/apm/{cluster_id}/metadata/raw

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Responses

200
(object) The cluster metadata was successfully returned
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/metadata/raw \
-u $CLOUD_USER:$CLOUD_KEY

Set cluster metadata

Advanced use only. Sets the internal metadata, in free-form JSON, for the APM instance. Only use the parameters to set the modified JSON that is returned from the get version of the metadata.

Request

POST /api/v1/clusters/apm/{cluster_id}/metadata/raw

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment 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

(string) (required) The freeform JSON for the cluster (should always be based on the current version retrieved from the GET)

Responses

200

(object) The cluster metadata was successfully changed (the updated JSON 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 cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/metadata/raw \
-u $CLOUD_USER:$CLOUD_KEY

Get cluster metadata settings

Retrieves a structured version of the cluster metadata as a collection of top-level settings. If a particular setting isn't returned, then the free-form JSON endpoint (/metadata/raw) must be used.

Request

GET /api/v1/clusters/apm/{cluster_id}/metadata/settings

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Responses

200

(ClusterMetadataSettings) The cluster metadata was successfully 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 cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/metadata/settings \
-u $CLOUD_USER:$CLOUD_KEY

Update cluster metadata settings

All changes in the specified object are applied to the metadata object. Omitting existing fields causes the same values to be reapplied.Specifying a null value reverts the field to the default value, or removes the field when no default value exists.

Request

PATCH /api/v1/clusters/apm/{cluster_id}/metadata/settings

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment 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

(ClusterMetadataSettings) (required) The cluster settings including updated values

Responses

200

(ClusterMetadataSettings) The cluster metadata was successfully updated

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
403
(BasicFailedReply) The provided action was prohibited for the given cluster.
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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 -XPATCH {{hostname}}/api/v1/clusters/apm/{cluster_id}/metadata/settings \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "contact_email" : "string",
   "hidden" : true,
   "name" : "string",
   "owner_id" : "string",
   "resources" : {
      "cpu" : {
         "boost" : true,
         "hard_limit" : true
      }
   },
   "subscription_level" : "string",
   "system_owned" : true
}
'

Get plan

Retrieves the active plan of an APM cluster. Transient settings are not show by this endpoint. To view the transient settings that have been applied with a specific plan, use the activity endpoint.

Request

GET /api/v1/clusters/apm/{cluster_id}/plan

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Query parameters

Name Type Required Description

show_plan_defaults

boolean; default: false

N

When plans are shown, includes the default values in the response. NOTE: This option results in large responses.

Responses

200

(ApmPlan) The cluster has a current applied plan

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 cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_not_found')
412
(BasicFailedReply) There is not currently applied plan - eg the cluster has not finished provisioning, or the provisioning failed (code: 'clusters.cluster_plan_state_error')
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/clusters/apm/{cluster_id}/plan \
-u $CLOUD_USER:$CLOUD_KEY

Update plan

Updates the configuration of an existing Apm cluster.

Request

POST /api/v1/clusters/apm/{cluster_id}/plan

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Query parameters

Name Type Required Description

validate_only

boolean; default: false

N

When true, validates the cluster definition without performing the update.

Request body

(ApmPlan) (required) The update plan definition

Responses

200
(ApmCrudResponse) The cluster definition was valid - no further action was requested. The return object contains an internal representation of the plan, for use in debugging
202
(ApmCrudResponse) The plan definition was valid and the updated plan is in progress.
400
(BasicFailedReply) The cluster definition contained errors (code: 'clusters.cluster_invalid_plan' and 'clusters.plan_feature_not_implemented')
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/plan \
-u $CLOUD_USER:$CLOUD_KEY \
-H 'Content-Type: application/json' \
-d '
{
   "apm" : {
      "docker_image" : "string",
      "system_settings" : {
         "debug_enabled" : "string",
         "elasticsearch_password" : "string",
         "elasticsearch_url" : "string",
         "elasticsearch_username" : "string",
         "kibana_url" : "string",
         "secret_token" : "string"
      },
      "user_settings_json" : {},
      "user_settings_override_json" : {},
      "user_settings_override_yaml" : "string",
      "user_settings_yaml" : "string",
      "version" : "string"
   },
   "cluster_topology" : [
      {
         "apm" : null,
         "instance_configuration_id" : "string",
         "size" : {
            "resource" : "string",
            "value" : 0
         },
         "zone_count" : 0
      }
   ],
   "transient" : {
      "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" : {}
      }
   }
}
'

Get plan activity

Retrieves the current and historical plan information for a APM cluster.

Request

GET /api/v1/clusters/apm/{cluster_id}/plan/activity

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Query parameters

Name Type Required Description

show_plan_defaults

boolean; default: false

N

When plans are shown, includes the default values in the response. NOTE: This option results in large responses.

show_plan_logs

boolean; default: true

N

Includes the active, pending, and historical plan information in the attempt log. NOTE: This option can result in large responses.

Responses

200
(ApmPlansInfo) Returning the plan activity for the specified APM cluster
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_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/clusters/apm/{cluster_id}/plan/activity \
-u $CLOUD_USER:$CLOUD_KEY

Cancel pending plan

Cancels the pending plan of an APM cluster.

Request

DELETE /api/v1/clusters/apm/{cluster_id}/plan/pending

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Query parameters

Name Type Required Description

ignore_missing

boolean; default: false

N

When true, returns successfully, even when plans are pending. The default is false.

Responses

200
(ApmCrudResponse) The plan was successfully deleted
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_not_found')
412
(BasicFailedReply) There is not currently applied plan - eg the cluster has not finished provisioning, or the provisioning failed (code: 'clusters.cluster_plan_state_error')
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 -XDELETE {{hostname}}/api/v1/clusters/apm/{cluster_id}/plan/pending \
-u $CLOUD_USER:$CLOUD_KEY

Get pending plan

Retrieves the pending plan of an APM cluster.

Request

GET /api/v1/clusters/apm/{cluster_id}/plan/pending

Path parameters

Name Type Required Description

cluster_id

string

Y

The APM deployment identifier.

Query parameters

Name Type Required Description

show_plan_defaults

boolean; default: false

N

When plans are shown, includes the default values in the response. NOTE: This option results in large responses.

Responses

200

(ApmPlan) The cluster has a pending plan currently being applied to the cluster

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 cluster specified by {cluster_id} cannot be found (code: 'clusters.cluster_not_found')
412
(BasicFailedReply) There is not currently applied plan - eg the cluster has not finished provisioning, or the provisioning failed (code: 'clusters.cluster_plan_state_error')
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/clusters/apm/{cluster_id}/plan/pending \
-u $CLOUD_USER:$CLOUD_KEY