enterprise/prune/v1alpha

COMMERCIAL FEATURE: Access pruning via enterprise/prune/v1alpha API endpoints in the packaged Sensu Go distribution. For more information, read Get started with commercial features.

NOTE: The enterprise/prune/v1alpha API endpoints are an alpha feature and may include breaking changes.

The pruning operation follows the role-based access control (RBAC) permissions of the current user. For example, to prune resources in the dev namespace, the current user who sends the prune command must have delete access to the dev namespace.

Requests to enterprise/prune/v1alpha API endpoints require you to authenticate with a Sensu API key or access token. 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.

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:

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"
}'

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

[
  {
    "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?types=core/v2.CheckConfig&allUsers=true&namespaces=dev?types=core/v2.CheckConfig&allUsers=true&namespaces=dev
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.
output 
[
  {
    "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)