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
--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.
For example, to disable prompting for scripting, run:
gcloud config set disable_prompts true
default configuration is suitable for many use cases. However, you
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
--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
CLOUDSDK_ACTIVE_CONFIG_NAME) in the .envrc file in the
root directory of your project.
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 email@example.com example-project-1 us-east1-b us-east1 project-1 False firstname.lastname@example.org example-project-2 us-east1-c us-east1 project-2 True email@example.com example-project-3 us-east1-b us-east1
Setting configuration properties
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
compute/zone properties as follows:
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: firstname.lastname@example.org 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.
- Read SDK Properties to learn more about properties.