Prune API

IMPORTANT: The prune API is an alpha feature and may include breaking changes.

COMMERCIAL FEATURE: Access the prune API in the packaged Sensu Go distribution. For more information, see Get started with commercial features.

NOTE: Requests to the prune API require you to authenticate with a Sensu access token or API key. The code examples in this document use the environment variable $SENSU_API_KEY to represent a valid API key in API requests.

Create a new pruning command

The /prune/v1alpha API endpoint provides HTTP POST access to create a pruning command to delete resources that are not specified in the request body.

NOTE: The prune API requires cluster-level privileges, even when all resources belong to the same namespace.

Example

In the following example, an HTTP POST request is submitted to the /prune/v1alpha API endpoint to create a pruning command for the checks specified in the request body in the dev namespace created by any user.

The request returns a successful HTTP 201 Created response and a list of the resources that were pruned.

curl -X POST \
http://127.0.0.1:8080/api/enterprise/prune/v1alpha\?types\=core/v2.CheckConfig\&allUsers\=true\&namespaces\=dev \
-H "Authorization: Key $SENSU_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "name": "check-echo",
  "namespace": "dev",
  "labels": {
    "region": "us-west-2",
    "sensu.io/managed_by": "sensuctl"
  },
  "created_by": "admin"
}'


HTTP/1.1 201 Created

[
  {
    "type": "CheckConfig",
    "api_version": "core/v2",
    "name": "check-echo",
    "namespace": "dev",
    "labels": {
      "region": "us-west-2",
      "sensu.io/managed_by": "sensuctl"
    },
    "created_by": "admin"
  }
]

API Specification

/prune/v1alpha (POST)
description Creates a pruning command to delete the specified resources.
example URL http://hostname:8080/api/enterprise/prune/v1alpha
example payload 
{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "name": "check-echo",
  "namespace": "dev",
  "labels": {
    "region": "us-west-2",
    "sensu.io/managed_by": "sensuctl"
  },
  "created_by": "admin"
}
query parameters
  • type: The fully-qualified name of the resource you want to prune. Example: ?type=core/v2.CheckConfig.
  • allUsers: Prune resources created by all users. Mutually exclusive with the users parameter. Defaults to false. Example: ?allUsers=true.
  • clusterWide: Prune any cluster-wide (non-namespaced) resources that are not defined in the configuration. Defaults to false. Example: ?clusterWide=true.
  • dryRun: Print the resources that will be pruned but does not actually delete them. Defaults to false. Example: ?dryRun=true.
  • labelSelector: Prune only resources that match the specified labels (accepts multiple values). Labels are a commercial feature. Example: ?labelSelector=[...].
  • namespaces: The namespace where you want to apply pruning. Example: ?namespaces=dev.
  • users: Prune only resources that were created by the specified users (accepts multiple values). Defaults to the currently configured sensuctl user. Example: ?users=admin.
To use multiple values for the parameters that allow them, you must specify the parameter multiple times (for example, ?users=admin&users=dev) rather than using a comma-separated list.
payload 
[
  {
    "type": "CheckConfig",
    "api_version": "core/v2",
    "name": "check-echo",
    "namespace": "dev",
    "labels": {
      "region": "us-west-2",
      "sensu.io/managed_by": "sensuctl"
    },
    "created_by": "admin"
  }
]
response codes
  • Success: 201 (Created)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)