gcloud CLI и консоль

Ставим gcloud, разбираемся с конфигурациями и двумя видами логина и включаем API — тот самый шаг, о котором забывают все и каждый.

gcloud CLI — единая командная утилита Google Cloud. Всё, что можно нажать в веб-консоли, можно сделать командой gcloud: она просто ходит в те же REST API, что и браузер.

Консоль или CLI

Веб-консоль (console.cloud.google.com) хороша, чтобы осмотреться: посмотреть счёт, полистать логи, найти нужный сервис. Но у неё есть фатальный недостаток — её действия невозможно повторить. Через полгода вы не вспомните, какие галочки ставили.

CLI решает ровно это: команда — это текст, который можно сохранить в репозиторий, положить в CI и отправить коллеге. Отсюда практическое правило: смотрим в консоли, делаем в CLI. Приятный бонус — почти на каждой странице консоли есть кнопка, показывающая эквивалентную команду gcloud или REST-запрос.

Установка

Универсальный способ — официальный установщик; на macOS удобнее Homebrew.

# macOS
brew install --cask google-cloud-sdk

# Linux (интерактивный установщик)
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# проверяем
gcloud version

Результат:

Google Cloud SDK 512.0.0
bq 2.1.11
core 2025.02.14
gcloud-crc32c 1.0.0
gsutil 5.33

Если ставить не хочется вообще — откройте Cloud Shell прямо в браузере (иконка терминала в шапке консоли). Это бесплатная Linux-машина с уже настроенным gcloud, домашней папкой в несколько гигабайт, которая переживает перезапуски, и встроенным редактором кода. Идеально для первых шагов и для «мне надо срочно с чужого ноутбука».

gcloud init: первый запуск

gcloud init

Команда проведёт вас через три вопроса и сделает три вещи:

1. Авторизует — откроет браузер, где вы войдёте в Google-аккаунт и дадите CLI доступ.
2. Выберет проект — покажет список доступных и запомнит выбранный как проект по умолчанию.
3. Спросит регион и зону — чтобы не писать --zone в каждой второй команде.

Всё это складывается в ~/.config/gcloud/. Проверить, что получилось, можно так:

gcloud config list
gcloud auth list

Результат:

[compute]
region = europe-west1
zone = europe-west1-b
[core]
account = ernest@example.com
project = codechick-api-dev

   Credentialed Accounts
ACTIVE  ACCOUNT
*       ernest@example.com

Два разных логина, и это правда важно

Здесь спотыкаются почти все. Команд похожих две, а смысл у них разный.

Вторая команда кладёт на диск файл Application Default Credentials (ADC). Клиентские библиотеки ищут учётные данные по цепочке: переменная GOOGLE_APPLICATION_CREDENTIALS → файл ADC → метаданные виртуальной машины (если код уже крутится внутри GCP). Поэтому один и тот же код работает и на ноутбуке, и на сервере — просто на сервере он берёт личность сервисного аккаунта, а на ноутбуке вашу.

from google.cloud import storage

# Клиент нигде не просит логин и пароль: он сам найдёт ADC —
# те самые credentials, что создаёт `gcloud auth application-default login`
client = storage.Client()

for bucket in client.list_buckets():
    print(bucket.name)

Если этот код падает с DefaultCredentialsError: Could not automatically determine credentials — вы сделали gcloud auth login, но забыли gcloud auth application-default login. Ошибка встречается настолько часто, что её стоит запомнить прямо сейчас.

Конфигурации: несколько проектов без боли

Рано или поздно у вас будет учебный проект, рабочий и чужой, куда вас позвали. Переключать их через gcloud config set project каждый раз — путь к аварии на проде. Правильный инструмент — конфигурации: именованные наборы «аккаунт + проект + регион».

# создать и сразу активировать конфигурацию
gcloud config configurations create work
gcloud config set account ernest@company.com
gcloud config set project codechick-api-prod
gcloud config set compute/region europe-west1
gcloud config set compute/zone europe-west1-b

# посмотреть все конфигурации
gcloud config configurations list

# переключиться обратно на учебную
gcloud config configurations activate default

Результат:

NAME     IS_ACTIVE  ACCOUNT              PROJECT              COMPUTE_DEFAULT_ZONE
default  False      ernest@gmail.com     codechick-api-dev    us-central1-a
work     True       ernest@company.com   codechick-api-prod   europe-west1-b

Разовое отступление от активной конфигурации делается флагом: gcloud compute instances list --project=another-project. А в скриптах и CI надёжнее вообще не полагаться на «активный проект» и всегда передавать --project явно.

Включение API — шаг, о котором забывают все

В новом проекте почти все сервисы выключены. Это не баг, а защита: включённый API — это потенциальные расходы и потенциальная дыра, поэтому Google не включает ничего «на всякий случай». Каждый сервис живёт за своим адресом вида compute.googleapis.com, run.googleapis.com, bigquery.googleapis.com.

Если API не включён, вы получите примерно такое:

ERROR: (gcloud.compute.instances.list) Could not fetch resource:
 - Compute Engine API has not been used in project 759214883012 before or
   it is disabled. Enable it by visiting
   https://console.developers.google.com/apis/api/compute.googleapis.com/overview?project=759214883012
   then retry.

В интерактивном терминале gcloud обычно сам предлагает включить API и повторить команду. А вот в CI, в Terraform и в клиентских библиотеках такого предложения не будет — там вы просто увидите SERVICE_DISABLED и потеряете время. Поэтому включение API делают явным первым шагом:

# что уже включено
gcloud services list --enabled

# найти нужный API среди доступных
gcloud services list --available --filter='name:run.googleapis.com'

# включить сразу несколько (можно в одной команде)
gcloud services enable \
  compute.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com

# выключить, если сервис больше не нужен
gcloud services disable run.googleapis.com

Небольшая, но злая деталь: включение API не мгновенно. Обычно это секунды, иногда — пара минут. Скрипт, который включает API и в следующей строке дёргает этот сервис, иногда падает на ровном месте. В автоматизации это лечат ретраями или коротким ожиданием.

Первая настоящая команда

Соберём всё вместе: проект, биллинг, API, машина. И сразу же уберём за собой — это самая важная строчка во всём уроке.

gcloud config set project codechick-api-dev
gcloud services enable compute.googleapis.com

# поднимаем микро-машину в регионе, где действует Always Free
gcloud compute instances create hello-vm \
  --machine-type=e2-micro \
  --zone=us-central1-a \
  --image-family=debian-12 \
  --image-project=debian-cloud

# смотрим, что получилось
gcloud compute instances list --format='table(name,zone,status,EXTERNAL_IP)'

# заходим внутрь по SSH (ключи gcloud создаст сам)
gcloud compute ssh hello-vm --zone=us-central1-a

# УБИРАЕМ ЗА СОБОЙ — вместе с загрузочным диском
gcloud compute instances delete hello-vm --zone=us-central1-a --quiet

Результат:

NAME      ZONE           STATUS   EXTERNAL_IP
hello-vm  us-central1-a  RUNNING  34.121.44.7

Как это работает

Внутри gcloud — обычная программа на Python, которая превращает вашу команду в HTTP-запрос к REST API Google и печатает ответ. Убедиться легко: добавьте --log-http, и вы увидите все запросы и заголовки. Отсюда несколько полезных следствий.

• Любой вывод можно распарсить. Флаг --format=json отдаёт машиночитаемый ответ, а --format='value(name)' — голые значения для bash-скриптов.
• Фильтровать лучше на сервере. --filter='status=RUNNING' отработает быстрее, чем grep по огромному списку.
• Обновления. gcloud components update обновляет CLI и ставит дополнительные компоненты (например, kubectl). Но если вы установили SDK через apt или yum, эта команда откажется работать: пакет обновляется пакетным менеджером. Это регулярно ставит людей в тупик.
• Чужая личность. Флаг --impersonate-service-account позволяет выполнить команду от имени сервисного аккаунта, не скачивая его ключ. Скачанный JSON-ключ — главный источник утечек в GCP, и хорошая практика — не создавать их вовсе.

Частые ошибки

• Забыли включить API. Самая частая ошибка новичка в GCP. Проверяйте gcloud services list --enabled первым делом.
• Перепутали auth login и application-default login. CLI работает, а код падает с DefaultCredentialsError — нужен второй логин.
• Работа не в том проекте. Активная конфигурация «залипла» на проде, а вы думали, что вы в dev. Держите отдельные конфигурации и не ленитесь смотреть gcloud config list перед опасными командами.
• Оставили ресурсы после туториала. Классика, стоящая денег: машина, диск, внешний IP, кластер. Правило — на каждый create сразу писать в блокнот соответствующий delete.
• Забыли --zone в скрипте. Локально всё работало (зона была в конфигурации), а в CI команда падает или просит зону интерактивно. В автоматизации указывайте зону, регион и проект явно.
• Скачали JSON-ключ сервисного аккаунта «чтобы быстрее». Он бессрочный и не отзывается сам. Для локальной разработки хватает ADC, для CI — Workload Identity Federation.

Итоги

• Консоль — чтобы смотреть, gcloud — чтобы делать: команды повторяемы и версионируются.
• gcloud init настраивает три вещи: аккаунт, проект по умолчанию, регион и зону.
• gcloud auth login авторизует утилиту, gcloud auth application-default login — ваш код через ADC. Это разные вещи.
• Конфигурации (gcloud config configurations) избавляют от смертельно опасного переключения между dev и prod вручную.
• В новом проекте API выключены: gcloud services enable — обязательный первый шаг, а включение занимает не ноль времени.
• Каждая созданная машина стоит денег, пока не удалена. За собой убираем всегда.