Back up and recover resources with sensuctl

The sensuctl dump command allows you to export your resources to standard out (STDOUT) or to a file. You can export all of your resources or a subset of them based on a list of resource types. The dump command supports exporting in wrapped-json and yaml.

For example, to export all resources for the current namespace to a file named my-resources.yml or my-resources.json in yaml or wrapped-json format for use with sensuctl or json format for use with the Sensu API:

sensuctl dump all --format yaml --file my-resources.yml

sensuctl dump all --format wrapped-json --file my-resources.json

sensuctl dump all --format json --file my-resources.json

To export only checks for only the current namespace to STDOUT in YAML or JSON format:

sensuctl dump core/v2.CheckConfig --format yaml

sensuctl dump core/v2.CheckConfig --format wrapped-json

sensuctl dump core/v2.CheckConfig --format json

To export only handlers and filters for only the current namespace to a file named my-handlers-and-filters in YAML or JSON format:

sensuctl dump core/v2.Handler,core/v2.EventFilter --format yaml --file my-handlers-and-filters.yml

sensuctl dump core/v2.Handler,core/v2.EventFilter --format wrapped-json --file my-handlers-and-filters.json

sensuctl dump core/v2.Handler,core/v2.EventFilter --format json --file my-handlers-and-filters.json

To export resources for all namespaces, add the --all-namespaces flag to any sensuctl dump command. For example:

sensuctl dump all --all-namespaces --format yaml --file my-resources.yml

sensuctl dump all --all-namespaces --format wrapped-json --file my-resources.json

sensuctl dump all --all-namespaces --format json --file my-resources.json

sensuctl dump core/v2.CheckConfig --all-namespaces --format yaml

sensuctl dump core/v2.CheckConfig --all-namespaces --format wrapped-json

sensuctl dump core/v2.CheckConfig --all-namespaces --format json

sensuctl dump core/v2.Handler,core/v2.EventFilter --all-namespaces --format yaml --file my-handlers-and-filters.yml

sensuctl dump core/v2.Handler,core/v2.EventFilter --all-namespaces --format wrapped-json --file my-handlers-and-filters.json

sensuctl dump core/v2.Handler,core/v2.EventFilter --all-namespaces --format json --file my-handlers-and-filters.json

You can use fully qualified names or short names to specify resources in sensuctl dump commands.

Here’s an example that uses fully qualified names:

sensuctl dump core/v2.Handler,core/v2.EventFilter --format yaml --file my-handlers-and-filters.yml

sensuctl dump core/v2.Handler,core/v2.EventFilter --format wrapped-json --file my-handlers-and-filters.json

sensuctl dump core/v2.Handler,core/v2.EventFilter --format json --file my-handlers-and-filters.json

Here’s an example that uses short names:

sensuctl dump handlers,filters --format yaml --file my-handlers-and-filters.yml

sensuctl dump handlers,filters --format wrapped-json --file my-handlers-and-filters.json

sensuctl dump handlers,filters --format json --file my-handlers-and-filters.json

After you use sensuctl dump to back up your Sensu resources, you can restore them later with sensuctl create. This page explains how to back up your resources for two common use cases: before a Sensu version upgrade and to populate new namespaces with existing resources.

Back up before a Sensu version upgrade

You should create a backup before you upgrade to a new version of Sensu. Here’s the step-by-step process:

1. Create a backup folder.

   mkdir backup

2. Create a backup of the entire cluster, except entities, events, and role-based access control (RBAC) resources, for all namespaces.

   sensuctl dump all \
   --all-namespaces \
   --omit core/v2.Entity,core/v2.Event,core/v2.APIKey,core/v2.User,core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --format yaml > backup/config.yml

   sensuctl dump all \
   --all-namespaces \
   --omit core/v2.Entity,core/v2.Event,core/v2.APIKey,core/v2.User,core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --format wrapped-json > backup/config.json

   sensuctl dump all \
   --all-namespaces \
   --omit core/v2.Entity,core/v2.Event,core/v2.APIKey,core/v2.User,core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --format json > backup/config.json

3. Export your RBAC resources, except API keys and users, for all namespaces.

   sensuctl dump core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --all-namespaces \
   --format yaml > backup/rbac.yml

   sensuctl dump core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --all-namespaces \
   --format wrapped-json > backup/rbac.json

   sensuctl dump core/v2.Role,core/v2.RoleBinding,core/v2.ClusterRole,core/v2.ClusterRoleBinding \
   --all-namespaces \
   --format json > backup/rbac.json

4. Export your API keys and users resources for all namespaces.

   sensuctl dump core/v2.APIKey,core/v2.User \
   --all-namespaces \
   --format yaml > backup/cannotrestore.yml

   sensuctl dump core/v2.APIKey,core/v2.User \
   --all-namespaces \
   --format wrapped-json > backup/cannotrestore.json

   sensuctl dump core/v2.APIKey,core/v2.User \
   --all-namespaces \
   --format json > backup/cannotrestore.json

   NOTE: Passwords are not included when you export users. You must add the password_hash or password attribute to any exported users resources before you can use them with sensuctl create.
   
   Because users require this additional configuration and API keys cannot be restored from a sensuctl dump backup, you might prefer to export your API keys and users to a different folder than backup.

5. Export your entity resources for all namespaces (if desired).

   sensuctl dump core/v2.Entity \
   --all-namespaces \
   --format yaml > backup/inventory.yml

   sensuctl dump core/v2.Entity \
   --all-namespaces \
   --format wrapped-json > backup/inventory.json

   sensuctl dump core/v2.Entity \
   --all-namespaces \
   --format json > backup/inventory.json

   NOTE: If you do not export your entities, proxy check requests will not be scheduled for the excluded proxy entities.

Back up to populate new namespaces

You can create a backup copy of your existing resources with their namespaces stripped from the record. This backup allows you to replicate resources across namespaces without manual editing.

To create a backup of your resources that you can replicate in new namespaces:

1. Create a backup folder.

   mkdir backup

2. Back up your pipeline resources for all namespaces, stripping namespaces so that your resources are portable for reuse in any namespace.

   sensuctl dump core/v2.Asset,core/v2.CheckConfig,core/v2.HookConfig,core/v2.EventFilter,core/v2.Mutator,core/v2.Handler,core/v2.Silenced,secrets/v1.Secret,secrets/v1.Provider \
   --all-namespaces \
   --format yaml | grep -v "^\s*namespace:" > backup/pipelines.yml

   sensuctl dump core/v2.Asset,core/v2.CheckConfig,core/v2.HookConfig,core/v2.EventFilter,core/v2.Mutator,core/v2.Handler,core/v2.Silenced,secrets/v1.Secret,secrets/v1.Provider \
   --all-namespaces \
   --format wrapped-json | grep -v "^\s*namespace:" > backup/pipelines.json

   sensuctl dump core/v2.Asset,core/v2.CheckConfig,core/v2.HookConfig,core/v2.EventFilter,core/v2.Mutator,core/v2.Handler,core/v2.Silenced,secrets/v1.Secret,secrets/v1.Provider \
   --all-namespaces \
   --format json | grep -v "^\s*namespace:" > backup/pipelines.json

Restore resources from backup

When you are ready to restore your exported resources, use sensuctl create.

To restore everything you exported all at once, run:

sensuctl create -r -f backup/

To restore a subset of your exported resources (in this example, your RBAC resources), run:

sensuctl create -f backup/rbac.yml

sensuctl create -f backup/rbac.json

Supported resource types

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

sensuctl describe-type all

The response will list the names and other details for the supported resource types:

      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.Cluster                                federation/v1       Cluster              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  

You can also list specific resource types by fully qualified name or short name:

sensuctl describe-type core/v2.CheckConfig

sensuctl describe-type checks

To list more than one type, use a comma-separated list:

sensuctl describe-type core/v2.CheckConfig,core/v2.EventFilter,core/v2.Handler

sensuctl describe-type checks,filters,handlers

Format the sensuctl describe-type response

Add the --format flag to specify how the resources should be formatted in the sensuctl describe-type response. The default is unformatted, but you can specify either wrapped-json or yaml:

sensuctl describe-type core/v2.CheckConfig --format yaml

sensuctl describe-type core/v2.CheckConfig --format wrapped-json