replica-omnisciente/.aurelio/skills/gcp/SKILL.md

name	description
gcp	Google Cloud platform operations for PF — project setup, Vertex AI models, GKE, Cloud Run, Cloud Functions, Cloud Storage, Pub/Sub, BigQuery, Cloud SQL, Secret Manager, IAM, service accounts, and domain-wide delegation. Use when the user needs GCP-specific architecture, provisioning, or operations; prefer self-hosted or emulated dev paths before touching real GCP projects.

gcp — Google Cloud Platform (enterprise)

Distinct from the gemini provider (AI Studio consumer API) and cli-gcloud (gcloud command snippets). This skill covers Google Cloud Vertex AI / enterprise workloads: project setup, billing, IAM, model serving, compute, data, messaging, and secrets.

When to use

• New client/project onboarding to GCP
• Vertex AI model selection and routing
• Deploying or operating GKE, Cloud Run, Cloud Functions
• Cloud Storage, Pub/Sub, BigQuery, Cloud SQL, Secret Manager design
• Service accounts, workload identity, domain-wide delegation
• Deciding when to use GCP vs self-hosted PF infrastructure

When NOT to use

• Consumer Gemini (AI Studio) → use the gemini provider in .aurelio/providers/registry.yaml
• Simple gcloud CLI one-liners → use cli-gcloud skill
• Firebase/GCP mobile-only features → not covered here

Project setup checklist

1. Create/select project

   gcloud projects create pf-<client>-<env> --name="PF <Client> <Env>"
   gcloud config set project pf-<client>-<env>
   

2. Billing

   • Link billing account in Cloud Console or via gcloud billing projects link
   • Set budget alerts (recommended: 50 %, 90 %, 100 %)
   • For clients, tag resources (cost-center, client, realm)

3. Enable APIs (one-time per project)

   gcloud services enable aiplatform.googleapis.com
   gcloud services enable container.googleapis.com
   gcloud services enable run.googleapis.com
   gcloud services enable cloudfunctions.googleapis.com
   gcloud services enable storage.googleapis.com
   gcloud services enable pubsub.googleapis.com
   gcloud services enable bigquery.googleapis.com
   gcloud services enable sqladmin.googleapis.com
   gcloud services enable secretmanager.googleapis.com
   gcloud services enable cloudbuild.googleapis.com
   gcloud services enable iamcredentials.googleapis.com
   

4. IAM baseline

   • Create admin group gcp-pf-admins@<domain> with roles/owner or roles/editor
   • Assign roles/viewer to auditors
   • Enable essential audit logs (Admin Activity + Data Access for Secret Manager / Cloud SQL)

Service accounts & auth

• Human users: use gcloud auth login + IAM bindings; no service-account keys in laptops.
• Workloads: use Workload Identity Federation where possible; otherwise create dedicated service accounts per workload.
• Keys: store JSON keys in Vaultwarden / Secret Manager; rotate every 90 days.
• Domain-wide delegation: required for Workspace APIs (Directory, Gmail, Calendar, Drive).
  • GCP Console → IAM & Admin → Service Accounts → pf-<workload>@<project>.iam.gserviceaccount.com
  • Add domain-wide delegation; note the Client ID
  • Google Admin Console → Security → API controls → Domain-wide delegation → Authorize the Client ID with OAuth scopes needed
  • Store Client ID and delegated SA email in Secret Manager

Vertex AI

Use Vertex AI for enterprise Gemini, Imagen, Veo, and embeddings. Region choice affects latency and model availability; europe-west1 is PF's default for EU data residency.

Model IDs

Model	ID	Context	Type	Notes
Gemini 2.5 Pro	gemini-2.5-pro-preview-06-05	1M tokens	chat	Reasoning, long context, code
Gemini 2.5 Flash	gemini-2.5-flash-preview-06-05	1M tokens	chat	Fast, cheaper
Gemini 2.0 Flash	gemini-2.0-flash-001	1M tokens	chat	Stable GA
Imagen 3	imagen-3-0-generate-001	N/A	image	Text-to-image
Veo 2	veo-2-0-generate-001	N/A	video	Text/video-to-video
Text Embedding 004	text-embedding-004	2048 dims	embedding	Sentence + document
Multimodal Embedding	multimodalembedding@001	128/256/512/1408 dims	embedding	Image + text

Endpoint pattern

https://<region>-aiplatform.googleapis.com/v1/projects/<project>/locations/<region>/publishers/google/models/<model-id>

Example: generate content

REGION=europe-west1
PROJECT=$(gcloud config get-value project)
MODEL=gemini-2.5-flash-preview-06-05

curl -X POST \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/${REGION}/publishers/google/models/${MODEL}:generateContent" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Summarize this in one line."}]}]}'

Python (google-cloud-aiplatform)

import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="pf-client-env", location="europe-west1")
model = GenerativeModel("gemini-2.5-flash-preview-06-05")
response = model.generate_content("Hello, GCP world.")
print(response.text)

Compute

GKE

• Use Autopilot for most PF workloads unless node-level tuning is required.
• Default region: europe-west1; multi-region only when HA is justified.
• Enable Workload Identity; disable legacy metadata endpoints.

gcloud container clusters create-auto pf-cluster \
  --region=europe-west1 \
  --release-channel=regular \
  --enable-workload-identity

Cloud Run

• Best for stateless HTTP services and MCP servers
• Use --no-allow-unauthenticated for internal agents; use IAM/service accounts for access
• Connect to Cloud SQL via proxy / native connections

gcloud run deploy pf-agent-service \
  --source . \
  --region=europe-west1 \
  --no-allow-unauthenticated \
  --service-account=pf-run-sa@$PROJECT.iam.gserviceaccount.com

Cloud Functions

• Use 2nd gen for longer timeouts, bigger instances, and Eventarc triggers
• Trigger from Pub/Sub, Cloud Storage, Firestore, HTTP

Data & messaging

Cloud Storage

• Buckets per realm/env; uniform bucket-level access enabled
• Lifecycle rules for logs and artifacts
• gsutil / gcloud storage are interchangeable; prefer gcloud storage

gcloud storage buckets create gs://pf-client-data-euw1 --location=europe-west1
gcloud storage buckets update gs://pf-client-data-euw1 --uniform-bucket-level-access

Pub/Sub

• Default for async agent-to-agent messaging
• Use push subscriptions to Cloud Run for reactive agents
• Enable exactly-once delivery when order/correctness matters

gcloud pubsub topics create agent-events
gcloud pubsub subscriptions create agent-events-run \
  --topic agent-events \
  --push-endpoint=https://pf-agent-service-xxx-uc.a.run.app/events

BigQuery

• Use for analytics, telemetry, and structured agent memory at scale
• Datasets per client/realm; partition large tables by ingestion time
• Prefer service-account access via IAM roles/bigquery.dataViewer

Cloud SQL

• PostgreSQL 16 default; use Cloud SQL Auth Proxy for local/dev access
• Private IP + VPC connector for GKE/Cloud Run
• Backups and point-in-time recovery enabled for production

Secret Manager

• Central store for API keys, service-account JSONs, database passwords
• Name convention: <client>/<realm>/<secret>
• Rotate via Secret Manager versions; latest alias for runtime

gcloud secrets create pf-client-db-password --data-file=-
# then paste value, Ctrl+D

Surfaces

• dirac: Vertex AI models appear as provider google-cloud in provider registry
• mcp: MCP servers running on Cloud Run / GKE; model_router.py can route to Vertex AI
• portal: PF portal can expose Vertex AI models and GCP-hosted agents under the Google Cloud offering

Pitfalls

• gemini (AI Studio) and google-cloud (Vertex AI) are separate providers; never ship a Vertex AI key to an AI Studio endpoint.
• GCP IAM is eventually consistent; wait or retry after policy changes.
• Region matters for model availability and pricing — verify in Vertex AI Model Garden before hard-coding a region.
• Domain-wide delegation is powerful; limit scopes and monitor audit logs.
• Cloud Run cold starts can add latency; use min-instances for latency-sensitive agents.
• Storage egress and BigQuery query costs can surprise; set budgets early.