Managing SDK Configurations

What is a configuration?

A configuration is a named set of SDK properties. These properties are key-value pairs, organized in sections, that govern the behavior of the gcloud command-line tool and other SDK tools.

Properties that are commonly stored in configurations include default Google Compute Engine zone, verbosity level, usage reporting, project ID, and an active user or service account. Configurations allow you to define and enable these and other settings together as a group.

Configurations are stored in your user config directory (typically ~/.config/gcloud on MacOS and Linux); you can find the location of your config directory by running gcloud info --format='value(config.paths.global_config_dir)'. However, if you are using Cloud Shell, your gcloud command-line tool preferences are stored in a temporary tmp folder, set for your current Cloud Shell tab only, and do not persist across sessions.

If you have multiple configurations, you can choose to switch between them or run commands using a specific configuration (with the help of the --configuration flag). For more about switching configurations, refer to the section below on Activating configurations.

To read about configurations from the command-line (along with a complete list of available properties and the sections they are in), run gcloud topic configurations.

Default configuration

The SDK starts you off with a single configuration named default. You can set properties in your configuration by running the gcloud init command or by running gcloud config set directly.

For example, to disable prompting for scripting, run:

gcloud config set disable_prompts true

Multiple configurations

The single default configuration is suitable for many use cases. However, you can also create additional configurations and switch between them as required using gcloud config configurations activate. There is nothing special about the initial default configuration; it is created as a convenience. You can name this and any additional configurations however you'd like.

Multiple configurations are useful if you want to:

  • Use multiple projects: You can create a separate configuration for each project and switch between them as required.
  • Use multiple authorization accounts
  • Perform generally independent tasks: For example, you can use one configuration to work on a Google App Engine application in one project and manage an unrelated Compute Engine instances in another project.

Creating a configuration

To create a configuration, run gcloud config configurations create:

gcloud config configurations create [NAME]

You must activate the new configuration after creation in order to use it.

Activating a configuration

Only one of your multiple configurations can be active at a given time. The active configuration is the configuration whose properties will govern the behavior of the SDK tools.

To activate a new configuration or switch to a new active configuration, run: gcloud config configurations activate:

gcloud config configurations activate [NAME]

gcloud config list will always show you the properties in your active configuration.

To change the active configuration for a single command invocation, you can use the --configuration flag on any gcloud CLI command:

gcloud auth list --configuration=[CONFIGURATION_NAME]

To change the active configuration for all commands in your current terminal, you can set the environment variable CLOUDSDK_ACTIVE_CONFIG_NAME to the name of the configuration you'd like to use.

Automating configuration switching

To help make changing configurations seamless, you can leverage tools such as direnv and ondir to automatically switch between configurations when you switch working directories. One way of accomplishing this would be to set the necessary environment variables (like CLOUDSDK_ACTIVE_CONFIG_NAME) in the .envrc file in the root directory of your project.

Listing configurations

To list the configurations in your Cloud SDK installation, run gcloud config configurations list:

gcloud config configurations list

The gcloud CLI lists the configurations and shows which configuration is currently active:

NAME         IS_ACTIVE     ACCOUNT            PROJECT               DEFAULT_ZONE  DEFAULT_REGION
default      False         user@gmail.com     example-project-1     us-east1-b    us-east1
project-1    False         user@gmail.com     example-project-2     us-east1-c    us-east1
project-2    True          user@gmail.com     example-project-3     us-east1-b    us-east1

Setting configuration properties

To set and unset the properties in the active configuration, run gcloud config set and gcloud config unset:

gcloud config set project [PROJECT]
gcloud config unset project

Properties can also be set via environment variables named CLOUDSDK_SECTION_NAME_PROPERTY_NAME. For example, you can set the core/project and compute/zone properties as follows:

CLOUDSDK_CORE_PROJECT=[YOUR_PROJECT_NAME]
CLOUDSDK_COMPUTE_ZONE=[YOUR_ZONE_NAME]

Viewing configuration properties

To view the properties in a configuration, run: gcloud config configurations describe:

gcloud config configurations describe [NAME]

Or, to view properties in the active configuration:

gcloud config list

The gcloud CLI prints the configuration properties:

is_active: false
name: default
properties:
  compute:
    region: us-east1
    zone: us-east1-b
  core:
    account: user@google.com
    project: example-project

Deleting a configuration

To delete a configuration, run: gcloud config configurations delete:

gcloud config configurations delete [NAME]

You cannot delete the active configuration. Use gcloud config configurations activate if required to switch to another configuration before deleting.

What's next