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-json
example and this table for a list of supported types.
See the reference docs for information about creating resource definitions.
NOTE: You cannot use sensuctl to update agent-managed entities. Requests to update agent-managed entities via sensuctl will fail and return an error.
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.
Flag | Function and important notes |
---|---|
-f or --file |
Files, URLs, or directories to create resources from. Strings. |
-h or --help |
Help for the create command. |
-r or --recursive |
Create command will follow subdirectories. |
sensuctl create resource types
sensuctl create types | |||
---|---|---|---|
AdhocRequest |
adhoc_request |
Asset |
asset |
CheckConfig |
check_config |
ClusterRole |
cluster_role |
ClusterRoleBinding |
cluster_role_binding |
Entity |
Env |
entity |
EtcdReplicators |
Event |
event |
EventFilter |
event_filter |
GlobalConfig |
Handler |
handler |
Hook |
hook |
HookConfig |
hook_config |
Mutator |
mutator |
Namespace |
namespace |
Role |
role |
RoleBinding |
role_binding |
Secret |
Silenced |
silenced |
User |
user |
VaultProvider |
ldap |
ad |
oidc |
TessenConfig |
PostgresConfig |
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:
- 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. --namespace
flag: If resource definitions do not specify a namespace, Sensu applies the namespace provided by thesensuctl create --namespace
flag.- 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
NOTE: You cannot use sensuctl to update agent-managed entities. Requests to update agent-managed entities via sensuctl will fail and return an error.
sensuctl edit resource types
sensuctl edit types | |||
---|---|---|---|
asset |
check |
cluster |
cluster-role |
cluster-role-binding |
entity |
event |
filter |
handler |
hook |
mutator |
namespace |
role |
role-binding |
silenced |
user |
auth |
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
IMPORTANT: sensuctl prune
is an alpha feature in release 5.19.0 and may include breaking changes.
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.
NOTE: sensuctl prune
can only delete resources that have the label sensu.io/managed_by: sensuctl
, which Sensu automatically adds to all resources created with sensuctl.
This means you can only use sensuctl prune
to delete resources that were created with sensuctl.
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.
Flag | Function and important notes |
---|---|
-a or --all-users |
Prunes resources created by all users. Mutually exclusive with the --users flag. Defaults to false. |
-c or --cluster-wide |
Prunes any cluster-wide (non-namespaced) resources that are not defined in the configuration. Defaults to false. |
-d or --dry-run |
Prints the resources that will be pruned but does not actually delete them. Defaults to false. |
-f or --file |
Files, URLs, or directories to prune resources from. Strings. |
-h or --help |
Help for the prune command. |
--label-selector |
Prunes only resources that match the specified labels (comma-separated strings). Labels are a commercial feature. |
-o or --omit |
Resources that should be excluded from being pruned. |
-r or --recursive |
Prune command will follow subdirectories. |
-u or --users |
Prunes only resources that were created by the specified users (comma-separated strings). Defaults to the currently configured sensuctl user. |
Supported resource types
Use sensuctl describe-type all
to retrieve the list of supported sensuctl prune
resource types.
NOTE: Short names are only supported for core/v2
resources.
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
NOTE: In Sensu 6.1.0, sensuctl prune
does not work with hooks.
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.
WARNING: Windows does not support canonical zone IDs (for example, America/Vancouver
).
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
or2018-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