# gcloud (Google Cloud CLI)

## What it is

Google Cloud's CLI: `gcloud` (projects, compute, IAM, GKE), bundled with
`gsutil` (Cloud Storage) and `bq` (BigQuery).

## Install

Official apt repo (Debian/Ubuntu):

```bash
sudo apt install apt-transport-https ca-certificates gnupg curl
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
  | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt update && sudo apt install google-cloud-cli
```

Alternative: the versioned tarballs from the
[install docs](https://cloud.google.com/sdk/docs/install) (`linux-x86_64` or
`linux-arm`); extract and run `./google-cloud-sdk/install.sh`.

## Authenticate

```bash
gcloud auth login            # browser OAuth, user account
gcloud config set project <project-id>
gcloud auth application-default login   # for SDKs/tools using ADC
```

Credentials land in `~/.config/gcloud/`. For service accounts, store the JSON
key in Vaultwarden (https://vault.portugalfuturista.org) and activate with:

```bash
gcloud auth activate-service-account --key-file=<path> --project=<project-id>
```

## Configure for this environment

Named configurations keep personal/lab projects apart:

```bash
gcloud config configurations create lab
gcloud config set project <lab-project-id>
gcloud config configurations list
gcloud config configurations activate lab
```

## Self-hosted equivalent

There is no real self-hosted GCP. Dev stand-ins we use instead:

- **Firebase Emulator Suite** (`firebase emulators:start`, via
  `npm i -g firebase-tools`) for Firestore/Auth/Functions.
- **fake-gcs-server** for Cloud Storage:
  `docker run -p 4443:4443 fsouza/fake-gcs-server -scheme http`, then
  `STORAGE_EMULATOR_HOST=http://localhost:4443` for client libraries.
- For plain object storage, prefer **MinIO** (`http://192.168.0.40:9000`) —
  S3-compatible and already on the LAN.

## Aurélio integration

The **cli-gcloud** skill wraps `gcloud`/`gsutil` for project and storage ops.
Connector registry id: `google-cloud`.

## Verify

```bash
gcloud --version
# Google Cloud SDK x.y.z
gcloud auth list
#        Credentialed Accounts
# ACTIVE  ACCOUNT
# *       you@example.com
gcloud config list project
# [core]
# project = <project-id>
```

## Troubleshooting

- **Old SDK from distro packages** — only use the Google apt repo above;
  distro `google-cloud-sdk` packages are frequently broken/stale.
- **`gcloud auth login` opens no browser** — run `gcloud auth login
  --no-browser` and paste the code back.
- **ADC errors in scripts** — you authenticated `gcloud` but not
  application-default credentials; run `gcloud auth application-default login`.
- **Wrong project billed** — check `gcloud config get-value project` before
  provisioning; use named configurations.