Managing Workspaces

A Steampipe workspace is a "profile" that allows you to define a unified environment that the Steampipe client can interact with. Each workspace is composed of:

a single Steampipe database instance
context-specific settings and options (snapshot location, query timeout, etc)

Steampipe workspaces allow you to define multiple named configurations:

and easily switch between them using the --workspace argument or STEAMPIPE_WORKSPACE environment variable:

Turbot Pipes workspaces are automatically supported:

Defining Workspaces

Workspace configurations can be defined in any .spc file in the ~/.steampipe/config directory, but by convention they are defined in ~/.steampipe/config/workspaces.spc file. This file may contain multiple workspace definitions that can then be referenced by name.

Any unset arguments will assume the default values - you don't need to set them all:

You can use base= to inherit settings form another profile:

The workspace_database may be local (which is the default):

or a Turbot Pipes workspace, in the form of {identity_handle}/{workspace_handle}:

The snapshot_location can also be a Turbot Pipes workspace, in the form of {identity_handle}/{workspace_handle}:

If it doesn't match the {identity_handle}/{workspace_handle} pattern it will be interpreted to be a path to a directory in the local filesystem where snapshots should be written to:

You can specify options blocks to set options for steampipe query:

You can even set the install_dir for a workspace if you want to use the data layer from another Steampipe installation directory.

This allows you to define workspaces that use a database from another installation directory:

and easily switch between them with the --workspace flag:

Using Workspaces

Workspaces may be defined in any .spc file in the ~/.steampipe/config directory, but by convention they should be placed in the ~/.steampipe/config/workspaces.spc file.

The workspace named default is special; if a workspace named default exists, --workspace is not specified in the command, and STEAMPIPE_WORKSPACE is not set, then Steampipe uses the default workspace:

You can pass any workspace to --workspace to use its values:

Or do the same with the STEAMPIPE_WORKSPACE environment variable:

If you specify the --workspace argument and the STEAMPIPE_WORKSPACE environment variable, the --workspace argument wins:

If you specify the --workspace argument and more specific arguments (workspace_database, etc), any more specific arguments will override the workspace values:

Environment variable values override default workspace settings when the default workspace is implicitly used:

If the default workspace is explicitly passed to the --workspace argument, its values will override any individual environment variables:

The same is true of any named workspace:

Implicit Workspaces

Named workspaces follow normal standards for HCL identifiers, thus they cannot contain the slash (/) character. If you pass a value to --workspace or STEAMPIPE_WORKSPACE in the form of {identity_handle}/{workspace_handle}, it will be interpreted as an implicit workspace. Implicit workspaces, as the name suggests, do not need to be specified in the workspaces.spc file. Instead they will be assumed to refer to a Turbot Pipes workspace, which will be used as both the database (workspace_database) and snapshot location (snapshot_location).

Essentially, --workspace acme/dev is equivalent to: