Create and manage resources with sensuctl

Use the sensuctl command line tool to create and manage resources within Sensu. Sensuctl works by calling Sensu’s underlying API to create, read, update, and delete resources, events, and entities.

Create resources

The sensuctl create command allows you to create or update resources by reading from STDIN or a flag configured file (-f). The create command accepts Sensu resource definitions in wrapped-json and yaml. Both JSON and YAML resource definitions wrap the contents of the resource in spec and identify the resource type. See the wrapped-jsonexample and this table for a list of supported types. See the reference docs for information about creating resource definitions.

wrapped-json format

In this example, the file my-resources.json specifies two resources: a marketing-site check and a slack handler, separated without a comma:

{
  "type": "CheckConfig",
  "api_version": "core/v2",
  "metadata" : {
    "name": "marketing-site",
    "namespace": "default"
    },
  "spec": {
    "command": "check-http.rb -u https://sensu.io",
    "subscriptions": ["demo"],
    "interval": 15,
    "handlers": ["slack"]
  }
}
{
  "type": "Handler",
  "api_version": "core/v2",
  "metadata": {
    "name": "slack",
    "namespace": "default"
  },
  "spec": {
    "command": "sensu-slack-handler --channel '#monitoring'",
    "env_vars": [
      "SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    ],
    "filters": [
      "is_incident",
      "not_silenced"
    ],
    "handlers": [],
    "runtime_assets": [],
    "timeout": 0,
    "type": "pipe"
  }
}

To create all resources from my-resources.json using sensuctl create:

sensuctl create --file my-resources.json

Or:

cat my-resources.json | sensuctl create

yaml format

In this example, the file my-resources.yml specifies two resources: a marketing-site check and a slack handler, separated with three dashes (---).

---
type: CheckConfig
api_version: core/v2
metadata:
  name: marketing-site
  namespace: default
spec:
  command: check-http.rb -u https://sensu.io
  subscriptions:
  - demo
  interval: 15
  handlers:
  - slack
---
type: Handler
api_version: core/v2
metadata:
  name: slack
  namespace: default
spec:
  command: sensu-slack-handler --channel '#monitoring'
  env_vars:
  - SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  filters:
  - is_incident
  - not_silenced
  type: pipe

To create all resources from my-resources.yml using sensuctl create:

sensuctl create --file my-resources.yml

Or:

cat my-resources.yml | sensuctl create

sensuctl create flags

Run sensuctl create -h to view command-specific and global flags. The following table describes the command-specific flags.

sensuctl create resource types

Create resources across namespaces

If you omit the namespace attribute from resource definitions, you can use the senusctl create --namespace flag to specify the namespace for a group of resources at the time of creation. This allows you to replicate resources across namespaces without manual editing. To learn more about namespaces and namespaced resource types, see the RBAC reference.

The sensuctl create command applies namespaces to resources in the following order, from highest precedence to lowest:

1. Namespaces specified within resource definitions: You can specify a resource’s namespace within individual resource definitions using the namespace attribute. Namespaces specified in resource definitions take precedence over all other methods.
2. --namespace flag: If resource definitions do not specify a namespace, Sensu applies the namespace provided by the sensuctl create --namespace flag.
3. Current sensuctl namespace configuration: If you do not specify an embedded namespace attribute or use the --namespace flag, Sensu applies the namespace configured in the current sensuctl session. See Manage sensuctl to view your current session config and set the session namespace.

In this example, the file pagerduty.yml defines a handler without a namespace attribute:

type: Handler
api_version: core/v2
metadata:
  name: pagerduty
spec:
  command: sensu-pagerduty-handler
  env_vars:
  - PAGERDUTY_TOKEN=SECRET
  type: pipe

To create the pagerduty handler in the default namespace:

sensuctl create --file pagerduty.yml --namespace default

To create the pagerduty handler in the production namespace:

sensuctl create --file pagerduty.yml --namespace production

To create the pagerduty handler in the current session namespace:

sensuctl create --file pagerduty.yml

Delete resources

The sensuctl delete command allows you to delete resources by reading from STDIN or a flag configured file (-f). The delete command accepts Sensu resource definitions in wrapped-json and yaml formats and uses the same resource types as sensuctl create. To be deleted successfully, resources provided to the delete command must match the name and namespace of an existing resource.

To delete all resources from my-resources.yml with sensuctl delete:

sensuctl delete --file my-resources.yml

Or:

cat my-resources.yml | sensuctl delete

Delete resources across namespaces

If you omit the namespace attribute from resource definitions, you can use the senusctl delete --namespace flag to specify the namespace for a group of resources at the time of deletion. This allows you to remove resources across namespaces without manual editing. See the Create resources across namespaces section for usage examples.

Update resources

Sensuctl allows you to update resource definitions with a text editor. To use sensuctl edit, specify the resource type and resource name.

For example, to edit a handler named slack with sensuctl edit:

sensuctl edit handler slack

sensuctl edit resource types

Manage resources

Sensuctl provides the following commands to manage Sensu resources.

• sensuctl asset
• sensuctl auth (commercial feature)
• sensuctl check
• sensuctl cluster
• sensuctl cluster-role
• sensuctl cluster-role-binding
• sensuctl entity
• sensuctl event
• sensuctl filter
• sensuctl handler
• sensuctl hook
• sensuctl license (commercial feature)
• sensuctl mutator
• sensuctl namespace
• sensuctl role
• sensuctl role-binding
• sensuctl secrets
• sensuctl silenced
• sensuctl tessen
• sensuctl user

Subcommands

Sensuctl provides a standard set of list, info, and delete operations for most resource types.

list                       list resources
info NAME                  show detailed resource information given resource name
delete NAME                delete resource given resource name

For example, to list all monitoring checks:

sensuctl check list

To list checks from all namespaces:

sensuctl check list --all-namespaces

To write all checks to my-resources.json in wrapped-json format:

sensuctl check list --format wrapped-json > my-resources.json

To see the definition for a check named check-cpu in wrapped-json format:

sensuctl check info check-cpu --format wrapped-json

In addition to the standard operations, commands may support subcommands or flags that allow you to take special action based on the resource type. The sections below describe these resource-specific operations.

For a list of subcommands specific to a resource, run sensuctl TYPE --help.

Handle large datasets

When querying sensuctl for large datasets, use the --chunk-size flag with any list command to avoid timeouts and improve performance.

For example, the following command returns the same output as sensuctl event list but makes multiple API queries (each for the number of objects specified by --chunk-size) instead of one API query for the complete dataset:

sensuctl event list --chunk-size 500

sensuctl check

In addition to the standard subcommands, the sensuctl check execute command executes a check on demand, given the check name:

sensuctl check execute NAME

For example, the following command executes the check-cpu check with an attached message:

sensuctl check execute check-cpu --reason "giving a sensuctl demo"

You can also use the --subscriptions flag to override the subscriptions in the check definition:

sensuctl check execute check-cpu --subscriptions demo,webserver

sensuctl cluster

The sensuctl cluster command lets you manage a Sensu cluster using the following subcommands:

health           get Sensu health status
id               get unique Sensu cluster ID
member-add       add cluster member to an existing cluster, with comma-separated peer addresses
member-list      list cluster members
member-remove    remove cluster member by ID
member-update    update cluster member by ID with comma-separated peer addresses

To view cluster members:

sensuctl cluster member-list

To see the health of your Sensu cluster:

sensuctl cluster health

sensuctl event

In addition to the standard subcommands, you can use sensuctl event resolve to manually resolve events:

sensuctl event resolve ENTITY CHECK

For example, the following command manually resolves an event created by the entity webserver1 and the check check-http:

sensuctl event resolve webserver1 check-http

sensuctl namespace

See the RBAC reference for information about using access control with namespaces.

sensuctl user

See the RBAC reference for information about local user management with sensuctl.

sensuctl prune

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

The sensuctl prune subcommand allows you to delete resources that do not appear in a given set of Sensu objects (called a “configuration”) from a from a file, URL, or STDIN. For example, you can use sensuctl create to to apply a new configuration, then use sensuctl prune to prune unneeded resources, resources that were created by a specific user or that include a specific label selector, and more.

The pruning operation always 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. In addition, pruning requires cluster-level privileges, even when all resources belong to the same namespace.

sensuctl prune usage

sensuctl prune [RESOURCE TYPE],[RESOURCE TYPE]... -f [FILE or URL] [-r] ... ] [--NAMESPACE] [flags]

In this example sensuctl prune command:

• Replace [RESOURCE TYPE] with the fully qualified name or short name of the resource you want to prune. You must specify at least one resource type or the all qualifier (to prune all resource types).
• Replace [FILE or URL] with the name of the file or the URL that contains the set of Sensu objects you want to keep (the configuration).
• Replace [flags] with the flags you want to use, if any.
• Replace [–NAMESPACE] with the namespace where you want to apply pruning. If you omit the namespace qualifier, the command defaults to the current configured namespace.

Use a comma separator to prune more than one resource in a single command.

For example, to prune checks and dynamic runtime assets from the file checks.yaml for the dev namespace and the admin and ops users:

sensuctl prune core/v2.CheckConfig,core/v2.Asset --file checks.yaml --namespace dev --users admin,ops

sensuctl prune checks,assets --file checks.yaml --namespace dev --users admin,ops

sensuctl prune flags

Run sensuctl prune -h to view command-specific and global flags. The following table describes the command-specific flags.

Supported resource types

Use sensuctl describe-type all to retrieve the list of supported sensuctl prune resource types.

sensuctl describe-type all

      Fully Qualified Name           Short Name           API Version             Type          Namespaced  
 ────────────────────────────── ───────────────────── ─────────────────── ──────────────────── ──────────── 
  authentication/v2.Provider                           authentication/v2   Provider             false
  licensing/v2.LicenseFile                             licensing/v2        LicenseFile          false
  store/v1.PostgresConfig                              store/v1            PostgresConfig       false
  federation/v1.EtcdReplicator                         federation/v1       EtcdReplicator       false
  secrets/v1.Secret                                    secrets/v1          Secret               true
  secrets/v1.Provider                                  secrets/v1          Provider             false
  searches/v1.Search                                   searches/v1         Search               true
  web/v1.GlobalConfig                                  web/v1              GlobalConfig         false
  core/v2.Namespace              namespaces            core/v2             Namespace            false
  core/v2.ClusterRole            clusterroles          core/v2             ClusterRole          false
  core/v2.ClusterRoleBinding     clusterrolebindings   core/v2             ClusterRoleBinding   false
  core/v2.User                   users                 core/v2             User                 false
  core/v2.APIKey                 apikeys               core/v2             APIKey               false
  core/v2.TessenConfig           tessen                core/v2             TessenConfig         false
  core/v2.Asset                  assets                core/v2             Asset                true
  core/v2.CheckConfig            checks                core/v2             CheckConfig          true
  core/v2.Entity                 entities              core/v2             Entity               true
  core/v2.Event                  events                core/v2             Event                true
  core/v2.EventFilter            filters               core/v2             EventFilter          true
  core/v2.Handler                handlers              core/v2             Handler              true
  core/v2.HookConfig             hooks                 core/v2             HookConfig           true
  core/v2.Mutator                mutators              core/v2             Mutator              true
  core/v2.Role                   roles                 core/v2             Role                 true
  core/v2.RoleBinding            rolebindings          core/v2             RoleBinding          true
  core/v2.Silenced               silenced              core/v2             Silenced             true  

sensuctl prune examples

sensuctl prune supports pruning resources by their fully qualified names or short names:

sensuctl prune core/v2.CheckConfig,core/v2.Entity

sensuctl prune checks,entities

Use the all qualifier to prune all supported resources:

sensuctl prune all

Use the --omit flag to identify resources you want to exclude from being pruned:

sensuctl prune all --omit core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding

Time formats

Sensuctl supports multiple time formats depending on the manipulated resource. Supported canonical time zone IDs are defined in the tz database.

Dates with time

Use full dates with time to specify an exact point in time. This is useful for setting silences, for example.

Sensuctl supports the following formats:

• RFC3339 with numeric zone offset: 2018-05-10T07:04:00-08:00 or 2018-05-10T15:04:00Z
• RFC3339 with space delimiters and numeric zone offset: 2018-05-10 07:04:00 -08:00
• Sensu alpha legacy format with canonical zone ID: May 10 2018 7:04AM America/Vancouver