Get Deployment APM Resource Info
- Base URL
-
https://api.elastic-cloud.com/api/v1
- GET /deployments/{deployment_id}/apm/{ref_id}
Get info about an APM Resource belonging to a given Deployment.
Query parameters
-
show_metadataboolean · default: false -
Whether to include the full cluster metadata in the response - can be large per cluster and also include credentials.
-
show_plansboolean · default: true -
Whether to include the full current and pending plan information in the response - can be large per cluster.
-
show_plan_logsboolean · default: false -
Whether to include with the current and pending plan information the attempt log - can be very large per cluster.
-
show_plan_historyboolean · default: false -
Whether to include with the current and pending plan information the plan history- can be very large per cluster.
Responses
Standard response.
-
elasticsearch_cluster_ref_idstringrequired -
The Elasticsearch cluster that this resource depends on.
-
infoobjectrequired -
The overview information for the APM Server.
-
healthybooleanrequired -
Whether the APM is healthy or not (one or more of the info subsections will have healthy: false)
-
statusrequired -
APM status
-
Values:
initializingstoppingstoppedrebootingrestartingreconfiguringstarted -
plan_infoobjectrequired -
Information about current, pending, and past APM Server plans.
-
healthybooleanrequired -
Whether the plan situation is healthy (if unhealthy, means the last plan attempt failed)
-
currentobject -
Information about the APM Server plan.
-
plan_attempt_namestring -
A human readable name for each plan attempt, only populated when retrieving plan histories
-
healthybooleanrequired -
Either the plan ended successfully, or is not yet completed (and no errors have occurred)
-
attempt_start_timestring · format: date-time -
When this plan attempt (ie to apply the plan to the APM) started (ISO format in UTC)
-
attempt_end_timestring · format: date-time -
If this plan completed or failed (ie is not pending), when the attempt ended (ISO format in UTC)
-
plan_end_timestring · format: date-time -
If this plan is not current or pending, when the plan was no longer active (ISO format in UTC)
-
planobject -
The plan for the APM Server.
-
cluster_topologyobject -
instance_configuration_idstring -
Controls the allocation of this topology element as well as allowed sizes and node_types. It needs to match the id of an existing instance configuration.
-
instance_configuration_versioninteger · format: int32 -
The version of the Instance Configuration Id. If it is unset, the meaning depends on read vs writes. For deployment reads, it is equivalent to version 0 (or the IC is unversioned); for deployment creates and deployment template use, it is equivalent to 'the latest version'; and for deployment updates, it is equivalent to 'retain the current version'.
-
sizeobject -
Measured by the amount of a resource. The final cluster size is calculated using multipliers from the topology instance configuration.
-
apmobject -
The configuration options for the APM Server.
-
versionstring -
The version of the Apm cluster (must be one of the ECE supported versions, and won't work unless it matches the APM version. Leave blank to auto-detect version.)
-
docker_imagestring -
A docker URI that allows overriding of the default docker image specified for this version
-
system_settingsobject -
A structure that defines a curated subset of the APM Server settings. TIP: To define the complete set of APM Server setting, use
ApmSystemSettingswithuser_settings_override_anduser_settings_. -
elasticsearch_usernamestring -
Optionally override the account within APM - defaults to a system account that always exists (if specified, the password must also be specified). Note that this field is never returned from the API, it is write only.
-
elasticsearch_passwordstring -
Optionally override the account within APM - defaults to a system account that always exists (if specified, the username must also be specified). Note that this field is never returned from the API, it is write only.
-
user_settings_jsonobject -
An arbitrary JSON object allowing (non-admin) cluster owners to set their parameters (only one of this and 'user_settings_yaml' is allowed), provided the parameters are on the allowlist and not on the denylist. (This field together with 'user_settings_override*' and 'system_settings' defines the total set of Apm settings)
-
user_settings_yamlstring -
An arbitrary YAML object allowing (non-admin) cluster owners to set their parameters (only one of this and 'user_settings_json' is allowed), provided the parameters are on the allowlist and not on the denylist. (These field together with 'user_settings_override*' and 'system_settings' defines the total set of Apm settings)
-
user_settings_override_jsonobject -
An arbitrary JSON object allowing ECE admins owners to set clusters' parameters (only one of this and 'user_settings_override_yaml' is allowed), ie in addition to the documented 'system_settings'. (This field together with 'system_settings' and 'user_settings*' defines the total set of Apm settings)
-
user_settings_override_yamlstring -
An arbitrary YAML object allowing ECE admins owners to set clusters' parameters (only one of this and 'user_settings_override_json' is allowed), ie in addition to the documented 'system_settings'. (This field together with 'system_settings' and 'user_settings*' defines the total set of Apm settings)
-
transientobject -
Defines the configuration parameters that control how the plan is applied. For example, the Elasticsearch cluster topology and APM Server settings.
-
strategyobject -
The options for performing a plan change. Specify only one property each time. The default is
grow_and_shrink. -
rollingobject -
Performs inline, rolling configuration changes that mutate existing containers. TIP: This is the fastest way to update a plan, but can fail for complex plan changes, such as topology changes. Also, this is less safe for configuration changes that leave a cluster in a non running state. NOTE: When you perform a major version upgrade, and 'group_by' is set to 'pass:macros[all]';, rolling is required.
-
group_bystring -
Specifies the grouping attribute to use when rolling several instances. Instances that share the same value for the provided attribute key are rolled together as a unit. Examples that make sense to use are '__all__' (roll all instances as a single unit), 'logical_zone_name' (roll instances by zone), '__name__' (roll one instance at a time, the default if not specified). Note that '__all__' is required when performing a major version upgrade
-
allow_inline_resizeboolean -
Whether we allow changing the capacity of instances (default false). This is currently implemented by stopping, re-creating then starting the affected instance on its associated allocator when performing the changes. NOTES: This requires a round-trip through the allocation infrastructure of the active constructor, as it has to reserve the target capacity without over-committing
-
grow_and_shrinkobject -
A strategy that creates instances with the new plan, migrates data from the old instances, then shuts down the old instances.
GrowShrinkStrategyConfigis safer than 'rolling' and ensures single node availability during a plan change, but can be a lot slower on larger clusters. -
plan_configurationobject -
The plan control configuration options for the APM Server.
-
timeoutinteger · format: int64 -
The total timeout in seconds after which the plan is cancelled even if it is not complete. Defaults to 4x the max memory capacity per node (in MB)
-
calm_wait_timeinteger · format: int64 -
This timeout determines how long to give a cluster after it responds to API calls before performing actual operations on it. It defaults to 5s
-
extended_maintenanceboolean -
If true (default false), does not clear the maintenance flag (which prevents its API from being accessed except by the constructor) on new instances added until after a snapshot has been restored, otherwise, the maintenance flag is cleared once the new instances successfully join the new cluster
-
plan_attempt_logobjectrequired -
metadataobject -
Information about the public and internal state, and the configuration settings of an Elasticsearch cluster.
-
last_modifiedstring · format: date-timerequired -
The most recent time the cluster metadata was changed (ISO format in UTC)
-
aliased_endpointstring -
The DNS name of the cluster endpoint derived from the deployment alias, if available
-
cloud_idstring -
The cloud ID, an encoded string that provides other Elastic services with the necessary information to connect to this Elasticsearch and Kibana (only present if both exist)
-
rawobject -
An unstructured JSON representation of the public and internal state (can be filtered out via URL parameter). The contents and structure of the
rawfield can change at any time. -
portsobject -
Information about the ports that allow communication between the Elasticsearch cluster and various protocols.
-
topologyobjectrequired -
The topology for Elasticsearch clusters, multiple Kibana instances, or multiple APM Servers. The
ClusterTopologyInfoalso includes the instances and containers, and where they are located. -
healthybooleanrequired -
Whether the cluster topology is healthy (ie all instances are started and the services they run - ie elasticsearch - are available
-
instancesobjectrequired -
instance_configurationobject -
Information about a configuration that creates a Kibana instance or APM Server.
-
config_versioninteger · format: 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.
-
service_versionstring -
The version of the service that the instance is running (eg Elasticsearch or Kibana), if available
-
container_startedbooleanrequired -
Whether the container has started (does not tell you anything about the service -ie Elasticsearch- running inside the container)
-
service_runningbooleanrequired -
Whether the service launched inside the container -ie Elasticsearch- is actually running
-
maintenance_modebooleanrequired -
Whether the service is is maintenance mode (meaning that the proxy is not routing external traffic to it)
-
allocator_idstring -
The id of the allocator on which this instance is running (if the container is started or starting)
-
memoryobject -
Information about the specific instances memory capacity and its usage
-
service_rolesstring -
List of roles assigned to the service running in the instance. Currently only populated for Elasticsearch, with possible values: master,data,ingest,ml
-
linksmap string to object -
A map of application-specific operations (which map to 'operationId's in the Swagger API) to metadata about that operation
The Deployment specified by {deployment_id} cannot be found. (code: deployments.deployment_not_found)
We have failed you. (code: deployments.deployment_resource_no_longer_exists)