Update cloud onboarding deployment | Kibana API documentation

Update cloud onboarding deployment Experimental; added in 9.5.0

PUT /api/fleet/cloud_onboarding_deployments/{id}

Spaces method and path for this operation:

put /s/{space_id}/api/fleet/cloud_onboarding_deployments/{id}

Refer to Spaces for more information.

Update a cloud onboarding deployment by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all OR integrations-all.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The saved object ID of the cloud onboarding deployment.

Maximum length is 255.

application/json

Body

agentPolicyIds array[string]

Agent policy IDs for agent_based deployments. Single-element for new-policy deploys; multiple for existing-policy deploys targeting several policies.

Not more than 1000 elements. Maximum length of each is 255.
apiKeyId string

Maximum length is 255.
attemptCount number

Incremented by callers performing a retry.

Minimum value is 1.
authMethod string | null

Authentication method. Refreshed on each successful deploy so a credential-method change between deploys is reflected on resume.

Values are identity_federation, static_keys, temporary_keys, shared_credentials, assume_role, or null.
connectorId string | null

Maximum length is 255.
deploymentId string

CFN stack ARN (or equivalent); provided by the client after manual deployment.

Maximum length is 2048.
deploymentName string

Maximum length is 255.
description string | null

Integration description from the Service settings step. Send null to clear it.

Maximum length is 2048.
ecfStacks array[object]

ECF CloudFormation stacks to record for this deployment.

Not more than 10 elements.
Hide ecfStacks attributes Show ecfStacks attributes object
- family string Required
  
  ECF template family.
  
  Values are unified, otel, or crowdstrike.
- serviceIds array[string]
  
  Service IDs active when the stack was last launched or updated.
  
  Not more than 1000 elements. Minimum length of each is 1, maximum length of each is 128.
- stackArn string
  
  CloudFormation stack ARN pasted by the user post-launch.
  
  Minimum length is 1, maximum length is 2048.
- stackName string Required
  
  CloudFormation stack name (128-char AWS limit).
  
  Minimum length is 1, maximum length is 128.
- templateVersion string Required
  
  ECF semantic version resolved at launch time, e.g. "1.10.0".
  
  Minimum length is 1, maximum length is 32.
instances array[object] Experimental; added in 9.7.0

Service instances, including duplicates, from the last deployment. Replaces the stored list, so instances removed since the last deployment are dropped.

Not more than 1000 elements.
Hide instances attributes Show instances attributes object
- instanceId string Required
  
  Instance ID: the service ID for an original, <serviceId>__dup-<n> for a duplicate.
  
  Minimum length is 1, maximum length is 255.
- isDuplicate boolean Required
  
  Whether the instance is a duplicate of another service.
- name string Required
  
  Display name of the instance. Duplicates use the custom name entered when the instance was duplicated.
  
  Maximum length is 255.
- serviceId string Required
  
  ID of the service this instance belongs to.
  
  Minimum length is 1, maximum length is 255.
integrationName string

Integration name used by the last deploy, before any per-package suffix. Refreshed on each deploy because an unedited default name follows the service selection.

Maximum length is 160.
mechanisms array[string]

Delivery mechanisms active in this deployment. Replaces the stored mechanisms array.

Not more than 10 elements. Values are managed_integration, ecf, or agent_based.
namespace string | null

Global data stream namespace from the Service settings step. Omit it to keep the stored value, or send null to clear it. When none is set, an agent-based deployment inherits the agent policy namespace, other deployment methods use the default namespace.

Maximum length is 100.
packagePolicyIds array[string]

Package policy IDs created for this deployment (managed_integration and agent_based).

Not more than 1000 elements. Maximum length of each is 255.
policyIdsByInstance object
Hide policyIdsByInstance attribute Show policyIdsByInstance attribute object
- * string Additional properties
  
  Maximum length is 255.
services array[string]

Current service set for this deployment. Refreshed on each successful deploy so resume after an incremental service addition restores all deployed services.

At least 1 but not more than 1000 elements. Minimum length of each is 1, maximum length of each is 256.
serviceVars object

Per-service config keyed by instance ID.
Hide serviceVars attribute Show serviceVars attribute object
- * object Additional properties
status string

Deployment status.

Values are pending, deploying, succeeded, or failed.
statusMessage string

Error context; set when transitioning to failed.

Maximum length is 1000.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  agentPolicyIds array[string]
  
  Agent policy IDs for agent_based deployments. Single-element for new-policy deploys; multiple for existing-policy deploys targeting several policies.
  
  Not more than 1000 elements.
  
  apiKeyId string
  
  Elasticsearch API key ID for push mechanisms (ecf). Set by the backend; used for key rotation/revocation.
  
  attemptCount number Required
  
  Number of deployment attempts, including the current one.
  
  Minimum value is 1.
  
  authMethod string
  
  Authentication method. Allowed values depend on the delivery mechanism:
  
  managed_integration: identity_federation | static_keys
  
  agent_based: static_keys (direct_access_keys) | temporary_keys | shared_credentials | assume_role
  
  Values are identity_federation, static_keys, temporary_keys, shared_credentials, or assume_role.
  
  connectorId string
  
  ID of the fleet-cloud-connector this deployment belongs to. Absent for static-keys deployments.
  
  dataFormat string
  
  Data format: ecs or otel.
  
  Values are ecs or otel.
  
  deploymentId string
  
  Opaque deployment identifier; for AWS, the CFN stack ARN.
  
  deploymentName string
  
  Opaque deployment name; for AWS, the CFN stack name.
  
  description string
  
  Integration description from the Service settings step.
  
  ecfStacks array[object]
  
  ECF CloudFormation stacks launched as part of this deployment. Written by the wizard after the user clicks Launch.
  
  Not more than 10 elements.
  
  Hide ecfStacks attributes Show ecfStacks attributes object
  
  family string Required
  
  ECF template family.
  
  Values are unified, otel, or crowdstrike.
  
  serviceIds array[string]
  
  Service IDs active when the stack was last launched or updated.
  
  Not more than 1000 elements. Minimum length of each is 1, maximum length of each is 128.
  
  stackArn string
  
  CloudFormation stack ARN pasted by the user post-launch.
  
  Minimum length is 1, maximum length is 2048.
  
  stackName string Required
  
  CloudFormation stack name (128-char AWS limit).
  
  Minimum length is 1, maximum length is 128.
  
  templateVersion string Required
  
  ECF semantic version resolved at launch time, e.g. "1.10.0".
  
  Minimum length is 1, maximum length is 32.
  
  globalRegion string
  
  Global AWS region from the Service Settings step.
  
  id string Required
  
  instances array[object] Experimental; added in 9.7.0
  
  Service instances, including duplicates, from the last deployment. Used to restore the service list when an onboarding is resumed.
  
  Not more than 1000 elements.
  
  Hide instances attributes Show instances attributes object
  
  instanceId string Required
  
  Instance ID: the service ID for an original, <serviceId>__dup-<n> for a duplicate.
  
  Minimum length is 1, maximum length is 255.
  
  isDuplicate boolean Required
  
  Whether the instance is a duplicate of another service.
  
  name string Required
  
  Display name of the instance. Duplicates use the custom name entered when the instance was duplicated.
  
  Maximum length is 255.
  
  serviceId string Required
  
  ID of the service this instance belongs to.
  
  Minimum length is 1, maximum length is 255.
  
  integrationName string
  
  Integration name as entered in the Service settings step, before any per-package suffix is applied.
  
  mechanisms array[string] Required
  
  Delivery mechanism: managed_integration, ecf, or agent_based.
  
  Not more than 10 elements. Values are managed_integration, ecf, or agent_based.
  
  namespace string
  
  Global data stream namespace from the Service settings step. When omitted, an agent-based deployment inherits the agent policy namespace, other deployment methods use the default namespace.
  
  packagePolicyIds array[string]
  
  Package policy IDs created for this deployment (managed_integration and agent_based).
  
  Not more than 1000 elements.
  
  policyIdsByInstance object
  
  instanceId → policyId mapping persisted after deploy. Hydrated into the wizard on resume to enable cleanup of stale policies when services are removed.
  
  Hide policyIdsByInstance attribute Show policyIdsByInstance attribute object
  
  * string Additional properties
  
  Maximum length is 255.
  
  provider string Required
  
  Cloud provider.
  
  Values are aws, azure, or gcp.
  
  services array[string] Required
  
  Service IDs covered by this deployment.
  
  Not more than 1000 elements.
  
  serviceVars object
  
  Per-service config keyed by instance ID. Each value is the ServiceVars object from the Service Settings step.
  
  Hide serviceVars attribute Show serviceVars attribute object
  
  * object Additional properties
  
  status string Required
  
  Deployment status.
  
  Values are pending, deploying, succeeded, or failed.
  
  statusMessage string
  
  Error context when status is failed.
400 application/json

Bad Request
Hide response attributes Show response attributes object
- attributes Required
- error string
- errorType string
- message string Required
- statusCode number
404 application/json

Not Found
Hide response attribute Show response attribute object
- message string Required

PUT /api/fleet/cloud_onboarding_deployments/{id}

curl \
 --request PUT 'https://localhost:5601/api/fleet/cloud_onboarding_deployments/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "deploymentId": "arn:aws:cloudformation:us-east-1:123456789012:stack/elastic-aws-onboarding/aaa-bbb-ccc",
  "deploymentName": "elastic-aws-onboarding",
  "status": "deploying"
}'

Request example

Update a cloud onboarding deployment after the CFN stack has been submitted

{
  "deploymentId": "arn:aws:cloudformation:us-east-1:123456789012:stack/elastic-aws-onboarding/aaa-bbb-ccc",
  "deploymentName": "elastic-aws-onboarding",
  "status": "deploying"
}

Response examples (200)

The updated cloud onboarding deployment

{
  "item": {
    "agentPolicyIds": [
      "agent-policy-id-1"
    ],
    "attemptCount": 1,
    "connectorId": "cloud-connector-id-1",
    "deploymentId": "arn:aws:cloudformation:us-east-1:123456789012:stack/elastic-aws-onboarding/aaa-bbb-ccc",
    "deploymentName": "elastic-aws-onboarding",
    "id": "onboarding-deployment-id-1",
    "mechanisms": [
      "managed_integration"
    ],
    "packagePolicyIds": [
      "package-policy-id-1"
    ],
    "provider": "aws",
    "services": [
      "cloudwatch_metrics",
      "cloudtrail"
    ],
    "status": "deploying"
  }
}

Response examples (400)

Example of a generic error response

{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}

Response examples (404)

The requested cloud onboarding deployment does not exist

{
  "error": "Not Found",
  "message": "Saved object [fleet-cloud-onboarding-deployment/unknown-id] not found",
  "statusCode": 404
}