Skip to content

Instantly share code, notes, and snippets.

@nicolasdao

nicolasdao/gcloud_cli_guide.md

Last active May 2, 2024 02:15
Show Gist options
  • Save nicolasdao/e15ec2a372422fdfe0990a976e563e4d to your computer and use it in GitHub Desktop.
Save nicolasdao/e15ec2a372422fdfe0990a976e563e4d to your computer and use it in GitHub Desktop.
Download ZIP
GCloud CLI Guide. Keywords: gcloud cli googlecloud gcp
Raw
gcloud_cli_guide.md

GCLOUD CLI GUIDE

Table of contents

Installing/updating the GCloud CLI on MacOS

Updating GCloud CLI

gcloud components update

Installing GCloud CLI

  1. Make sure you have a version of Python higher than 2.7.9.:
    • Run python -v to check the current version.
    • If you need to install a more recent version of Python:
      • Install pyenv if it is not installed yet: brew install pyenv
      • Install the more recent version of Python: pyenv install 3.7.3
      • Configure your terminal to use the python version defined by pyenv: echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc

      If you're not using Z shell, and using the default bash, replace .zshrc with .bash_profile.

      • Restart your terminal.
  2. Download the GCloud CLI here.
  3. Untar the downloaded package.
  4. Open the terminal and make sure Python 2 is uninstalled: brew uninstall --ignore-dependencies python@2 (since Python 2 End of Life Announced as January 1st 2020 as well as brew no longer support python 2).
  5. Browse to the untarred folder and run ./install.sh

Must know concepts

GCloud is statefull and not transparent about its state

One of the biggest pain is that most of GCloud's commands are relative to the project that has been set as the default or as the active one. Let's take the command that deploys a Docker image to Google Cloud Build for example:

gcloud builds submit --tag gcr.io/PROJECT-ID/helloworld

One might think that this command is targetting the PROJECT-ID, but that actually not the case. This command targets whatever project ID has been setup in the active configuration (to know what's that project is, run gcloud config list). gcr.io/PROJECT-ID/helloworld is just a unique identifier to locate where the images should be stored in the Google Cloud Container Registry. The convention is to use the project ID as the second element in the path.

GCloud can store multiple configurations

Because some deployments can require a lot of configurations, and because you may want to deploy multiple projects separately, GCloud supports the concept of configurations. It is somewhat similar to AWS profiles. Once a configuration has been set up, it can be used via --configuration my-config option. All GCloud operations support that option.

All the configs are stored under /Users/<YOUR USER>/.config/gcloud/configurations/config_default. To learn more about the GCloud credentials, please refer to the Where does GCloud store the user's credentials? section.

The rest of this section covers:

Creating a new config

gcloud config configurations create <CONFIG NAME>
gcloud auth login

This first command also activates the new config, making it the default for all the other commands. The second command associate an account to that config.

Configuring a config

gcloud config set <PROPERTY NAME> <PROPERTY VALUE>

The most common property to set on a config is the project ID: gcloud config set project <PROJECT ID>

For a list of all the available config properties, please refer to the official web page.

Making a config the default

gcloud config configurations activate <CONFIG NAME>

To reset to the default config:

gcloud config configurations activate default

Billing is not enabled by default

Unfortunately, this cannot be enabled via the GCloud CLI. The only way to perform this operation is to log to the Google Cloud console for that specific project.

Most APIs are not enabled by default

  • To list the enabled APIs for a specific project:
    1. gcloud config set project <PROJECT ID>
    2. gcloud services list
  • To list all the avalaible services: gcloud services list --available
  • To enable one or many services: gcloud services enable <SERVICE ID 1> <SERVICE ID 2>
  • To disable one or many services: gcloud services disable <SERVICE ID 1> <SERVICE ID 2>

Getting started

The usual steps when starting a new project

  1. Check that your GCloud current state is using the right Google Account: 
    gcloud config list
    If not, use one of the following options:
  2. Choose an existing project or create a new one:
  3. Set the new project on the current activated config: 
    gcloud config set project <PROJECT ID>
  4. Make sure that:

Creating a new project

gcloud projects create <PROJECT ID>

The PROJECT ID must be globally unique, contain lowercases and dashes only and be between 6 and 30 characters.

Then, make sure that:

Common commands

Accounts

Command Description
gcloud auth login Switches account.
gcloud auth application-default login Sets up the ~/.config/gcloud/application_default_credentials.json file so the google-auth-library library (or any app using that library for authentication) can fall back on those creds to access GCP resources.
gcloud auth print-identity-token Gets a short-lived id_token for the current logged in user.
gcloud auth print-identity-token --impersonate-service-account=SA@PROJECT_ID.iam.gserviceaccount.com Impersonate a service account using your current logged in user and get an id_token for that service account.

Services

Command Description
gcloud services list Lists all enabled services for the current account.
gcloud services list --available Lists all the services.
gcloud services enable <SERVICE ID 1> <SERVICE ID 2> Enables <SERVICE ID 1> and <SERVICE ID 2>.
gcloud services disable <SERVICE ID 1> <SERVICE ID 2> Enables <SERVICE ID 1> and <SERVICE ID 2>.

Projects

Command Description
gcloud config list Checks the current active project.
gcloud projects list Lists all the projects for the current account.
gcloud config set project <PROJECT ID> Sets the current active project.
gcloud projects remove-iam-policy-binding <PROJECT ID> --member=user:some-user@example.com --role=roles/owner Removes a member from a project.

Roles and members

Command Description
gcloud projects get-iam-policy <PROJECT ID> Lists all project's members with their roles.
gcloud iam roles list --filter="name:(your-keyword)" Searches for roles.
gcloud projects add-iam-policy-binding <PROJECT ID> --member='<MEMBER ID>' --role='<ROLE ID>' Adds a role on a project's member. <MEMBER ID> is formatted like this: serviceAccount:123456@cloudbuild.gserviceaccount.com or user:nic@neap.co, while <ROLE ID> is formatted like this: roles/secretmanager.secretAccessor.

Secrets

Command Description
gcloud secrets list Lists all the secret's names with metadata.
gcloud secrets create <SECRET-NAME> --data-file=<LOCAL PATH TO SECRET FILE> Converts a secret file's content located on the local machine under <LOCAL PATH TO SECRET FILE> to a string and stores it under <SECRET-NAME>.
echo "my super secret" | gcloud secrets create <SECRET-NAME> --data-file=- Stores "my super secret" under <SECRET-NAME>.
gcloud secrets versions access latest --secret=<SECRET-NAME> Gets the string content stored in <SECRET-NAME>.
gcloud secrets versions add <SECRET-NAME> --data-file=<LOCAL PATH TO SECRET FILE> Updates a secret.
gcloud secrets versions list <SECRET-NAME> Lists all the secret's versions.
gcloud secrets versions access <VERSION ID> --secret=<SECRET-NAME> Gets the string content stored in <SECRET-NAME> for a specific version.
gcloud secrets delete <SECRET-NAME> Deletes a secret.

FAQ

How to check the current config?

The following command shows the current active config:

gcloud config list

If you need to list all the config details:

gcloud config configurations list

How to configure a project in the current active GCloud config?

Check what's the current active config:

gcloud config list

If that config does not show the correct project ID, change it as follow:

gcloud config set project <PROJECT ID>

If you don't know the exact ID of the project, list all your projects as follow:

 gcloud projects list

How to switch the current config to another account?

gcloud auth login

How to create a new config?

Please refer to the GCloud can store multiple configurations section.

How to manage project services?

To list the enabled APIs for a specific project:

gcloud config set project <PROJECT ID>
gcloud services list

To list all the enabled services:

gcloud services list

To list all the avalaible services:

gcloud services list --available

To enable one or many services:

gcloud services enable <SERVICE ID 1> <SERVICE ID 2>

To disable one or many services:

gcloud services disable <SERVICE ID 1> <SERVICE ID 2>

How to list all project's members?

gcloud projects get-iam-policy <PROJECT ID>

To check the current active project, use gcloud config list

How to list and add roles to members?

Find the member you wish to add a role for:

gcloud projects get-iam-policy <PROJECT ID>

To check the current active project, use gcloud config list

Search for the role you want to add:

gcloud iam roles list --filter="name:(your-keyword)"

Once you've found the role you need, then add it as follow:

gcloud projects add-iam-policy-binding <PROJECT ID> --member='<MEMBER ID>' --role='<ROLE ID>'

Where:

  • <MEMBER ID> is formatted like this: serviceAccount:123456@cloudbuild.gserviceaccount.com or user:nic@neap.co
  • <ROLE ID> is formatted like this: roles/secretmanager.secretAccessor

How can I print a short-lived OAuth2 access token for my current account?

Please refer to the Accounts section under Common commands.

Where does GCloud store the user's credentials?

The user's credentials are stored using SQLLite under the following two paths:

  • ~/.config/gcloud/access_tokens.db: Stores the OAuth tokens associated with each account.
  • ~/.config/gcloud/credentials.db: Stores the accounts. account_id is an email address and value is a binary value representing a JSON object with the account credentials.

Those two files are the equivalent to the AWS profile files (located under the the~/.aws folder). Put together with the config file located under ~/.config/gcloud/configurations/config_default, GCloud can associate credentials with specific project configuration.

Annex

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment