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 to a file named my-resources.yaml in yaml format:

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

To export only checks to STDOUT in yaml format:

sensuctl dump core/v2.CheckConfig --format yaml

To export only handlers and filters to a file named my-handlers-and-filters.yaml in yaml format:

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

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

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

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

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 namespaced backup of the entire cluster, except entities, events, and role-based access control (RBAC) resources.

   sensuctl dump all \
   --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.yaml

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

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

4. Export your API keys and users resources.

   sensuctl dump core/v2.APIKey,core/v2.User
   --format yaml > backup/cannotrestore.yaml

   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 (if desired).

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

   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, stripping namespaces so that your resources are portable for reuse in any namespace.

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

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.yaml

Supported resource types

Use sensuctl describe-type all to retrieve the list of supported sensuctl dump 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.Hook                   hooks                 core/v2             Hook                 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