Vertex AI Setup Skill

Vertex AI Setup Skill

Set up Google Cloud and Vertex AI for using Imagen and other Google AI models.

When to Use

Use this skill when the user wants to:

• Configure Google Cloud for Vertex AI access
• Set up authentication for Imagen model
• Enable required APIs for Vertex AI
• Test Vertex AI connection
• Troubleshoot Vertex AI authentication issues

Prerequisites

• macOS or Linux environment
• Terminal access
• Google Cloud account with billing enabled
• A Google Cloud project (or ability to create one)

Workflow Overview

This workflow has three phases executed sequentially. Each step has explicit success criteria - do not proceed until verified.

Phase 1: gcloud CLI Setup (10 min)
    ↓
Phase 2: Project and API Configuration (5 min)
    ↓
Phase 3: Verification and Testing (5 min)

---

Phase 1: gcloud CLI Setup

Goal: Install and authenticate the Google Cloud CLI.

Step 1.1: Install gcloud CLI

Action: Install the gcloud command-line tool.

# macOS (via Homebrew)
brew install --cask google-cloud-sdk

# Linux (via install script)
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Verify installation
gcloud --version

Success Criteria: gcloud --version shows version information (e.g., Google Cloud SDK 450.0.0).

Failure Handling:

• Command not found: Restart terminal or run source ~/.bashrc (Linux) or source ~/.zshrc (macOS)
• Homebrew not installed: Install Homebrew first: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 1.2: Authenticate with Google Cloud

Action: Log in to your Google Cloud account.

# Authenticate with Google Cloud
gcloud auth login

# This opens a browser window for authentication
# Select your Google account and grant permissions

Success Criteria: Browser shows "You are now authenticated with the gcloud CLI!" message.

Failure Handling:

• Browser doesn't open: Use gcloud auth login --no-browser and follow the instructions
• Wrong account: Use gcloud auth login --force to re-authenticate
• Permission denied: Ensure your Google account has access to Google Cloud

Step 1.3: Set Default Project

Action: Select or create a Google Cloud project.

# List existing projects
gcloud projects list

# Set default project (replace PROJECT_ID)
gcloud config set project PROJECT_ID

# Verify configuration
gcloud config get-value project

Success Criteria: gcloud config get-value project shows your selected project ID.

Failure Handling:

• No projects exist: Create one at https://console.cloud.google.com/projectcreate
• Project not found: Check project ID spelling (use exact ID from gcloud projects list)
• Permission denied: Ensure you have Editor or Owner role on the project

---

Phase 2: Project and API Configuration

Goal: Enable required APIs and configure authentication for Vertex AI.

Step 2.1: Enable Vertex AI API

Action: Enable the Vertex AI API for your project.

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

# Verify API is enabled
gcloud services list --enabled | grep aiplatform

Success Criteria: Output shows aiplatform.googleapis.com in the enabled services list.

Failure Handling:

• Billing not enabled: Visit https://console.cloud.google.com/billing and enable billing for your project
• Permission denied: Ensure you have the Service Usage Admin role or higher
• API enablement stuck: Wait 2-3 minutes, then retry verification command

Step 2.2: Configure Application Default Credentials

Action: Set up authentication for local development.

IMPORTANT: Choose ONE approach based on your use case.

Option A: Application Default Credentials (ADC) - Development

Best for local testing and development.

# Set up ADC
gcloud auth application-default login

# This opens browser for additional authentication
# Grant permissions for Application Default Credentials

Success Criteria: Browser shows "Application Default Credentials are now set up!" message.

Trade-offs:

• ✅ Simplest for local development
• ✅ No credential file management
• ❌ Uses your personal credentials
• ❌ Not suitable for production

Option B: Service Account - Production

Best for production deployments or shared environments.

# Create service account
gcloud iam service-accounts create vertex-ai-user \
    --display-name="Vertex AI User"

# Grant Vertex AI User role
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:vertex-ai-user@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

# Create and download key
gcloud iam service-accounts keys create ~/vertex-ai-key.json \
    --iam-account=vertex-ai-user@PROJECT_ID.iam.gserviceaccount.com

# Set environment variable (add to ~/.bashrc or ~/.zshrc)
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/vertex-ai-key.json"

Success Criteria: JSON key file exists at ~/vertex-ai-key.json.

Trade-offs:

• ✅ Proper for production use
• ✅ Fine-grained permissions
• ✅ Can be rotated/revoked
• ❌ More setup complexity
• ❌ Credential file must be secured

Failure Handling:

• Service account creation fails: Ensure you have Service Account Admin role
• Permission denied on binding: Ensure you have Project IAM Admin role
• Key file not created: Check write permissions in home directory

Step 2.3: Set Default Region (Optional but Recommended)

Action: Configure default region for Vertex AI operations.

# Set region (us-central1 has broadest model availability)
gcloud config set ai/region us-central1

# Verify
gcloud config get-value ai/region

Success Criteria: Command shows us-central1 (or your chosen region).

Available Regions for Vertex AI:

• us-central1 - Broadest availability, lowest latency (US)
• us-east4 - East coast US
• europe-west4 - Europe
• asia-southeast1 - Singapore

---

Phase 3: Verification and Testing

Goal: Confirm setup works end-to-end.

Step 3.1: Test Authentication

Action: Verify credentials are working.

# Test authentication
gcloud auth application-default print-access-token

# Should output a long token string (starts with "ya29.")

Success Criteria: Command outputs an access token without errors.

Failure Handling:

• No credentials: Run gcloud auth application-default login again
• Token expired: Re-run the login command
• Service account error: Check GOOGLE_APPLICATION_CREDENTIALS path is correct

Step 3.2: Verify Vertex AI Access

Action: Test that you can access Vertex AI API.

# List available models in Vertex AI (requires API to be enabled)
gcloud ai models list --region=us-central1 2>&1

# If no models exist, this is fine - just shouldn't error

Success Criteria: Command completes without "permission denied" or "API not enabled" errors.

Failure Handling:

• API not enabled: Return to Step 2.1
• Permission denied: Check IAM roles (need roles/aiplatform.user minimum)
• Region not supported: Try us-central1 as the default region

Step 3.3: Test with Python SDK (Optional)

Action: Verify Python library can authenticate.

# Install Vertex AI SDK
pip install google-cloud-aiplatform

# Test connection
python3 << 'EOF'
from google.cloud import aiplatform

# Initialize SDK
aiplatform.init(project="PROJECT_ID", location="us-central1")

print("✓ Vertex AI SDK initialized successfully!")
print(f"  Project: {aiplatform.initializer.global_config.project}")
print(f"  Location: {aiplatform.initializer.global_config.location}")
EOF

Success Criteria: Script prints success message with project and location.

Failure Handling:

• Import error: Install SDK with pip install google-cloud-aiplatform
• Authentication error: Return to Step 2.2
• Project ID error: Use exact project ID from gcloud config get-value project

---

Troubleshooting

Common Issues and Solutions

"ERROR: (gcloud.auth.application-default.login) The project property is set to the empty string"

# Fix: Set project first
gcloud config set project PROJECT_ID
gcloud auth application-default login

"API [aiplatform.googleapis.com] not enabled on project"

# Fix: Enable the API
gcloud services enable aiplatform.googleapis.com

# Verify
gcloud services list --enabled | grep aiplatform

"Permission denied" when calling Vertex AI

# Check your current authenticated account
gcloud auth list

# Check IAM roles
gcloud projects get-iam-policy PROJECT_ID \
    --flatten="bindings[].members" \
    --format="table(bindings.role)" \
    --filter="bindings.members:$(gcloud config get-value account)"

# Required role: roles/aiplatform.user (minimum)

Fix: Add required role

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:[email protected]" \
    --role="roles/aiplatform.user"

"Quota exceeded" errors

Vertex AI has quota limits. Check and request increases:

# View quota usage
gcloud compute project-info describe --project=PROJECT_ID

# Request quota increase at:
# https://console.cloud.google.com/iam-admin/quotas

"Invalid authentication credentials"

# Clear and re-authenticate
gcloud auth application-default revoke
gcloud auth application-default login

# Or for service accounts, verify environment variable
echo $GOOGLE_APPLICATION_CREDENTIALS
# Should point to valid JSON key file

Service account key file lost or corrupted

# Create new key (old keys remain valid until deleted)
gcloud iam service-accounts keys create ~/vertex-ai-key-new.json \
    --iam-account=vertex-ai-user@PROJECT_ID.iam.gserviceaccount.com

# Update environment variable
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/vertex-ai-key-new.json"

# Delete old key (find key ID first)
gcloud iam service-accounts keys list \
    --iam-account=vertex-ai-user@PROJECT_ID.iam.gserviceaccount.com

gcloud iam service-accounts keys delete KEY_ID \
    --iam-account=vertex-ai-user@PROJECT_ID.iam.gserviceaccount.com

---

Quick Reference Card

Essential Commands

# Install gcloud
brew install --cask google-cloud-sdk

# Authenticate
gcloud auth login
gcloud auth application-default login

# Configure project
gcloud config set project PROJECT_ID
gcloud config set ai/region us-central1

# Enable Vertex AI
gcloud services enable aiplatform.googleapis.com

# Test connection
gcloud auth application-default print-access-token

# Verify setup
gcloud ai models list --region=us-central1

Authentication Approaches

Method	Command	Use Case
ADC (Development)	gcloud auth application-default login	Local testing
Service Account	export GOOGLE_APPLICATION_CREDENTIALS=path/to/key.json	Production

Required IAM Roles

Role	Purpose
roles/aiplatform.user	Call Vertex AI APIs (minimum)
roles/aiplatform.admin	Manage models and endpoints
roles/serviceusage.serviceUsageAdmin	Enable APIs

Environment Variables

# For service account authentication
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/vertex-ai-key.json"

# For custom endpoints (advanced)
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="us-central1"

---

Self-Verification Checklist

Before marking setup complete, verify:

• gcloud CLI installed (gcloud --version works)
• Authenticated with Google Cloud (gcloud auth list shows account)
• Project selected (gcloud config get-value project shows project ID)
• Billing enabled on project (check console.cloud.google.com/billing)
• Vertex AI API enabled (gcloud services list --enabled | grep aiplatform)
• Application Default Credentials configured (gcloud auth application-default print-access-token works)
• Default region set (gcloud config get-value ai/region shows region)
• No permission errors when listing models (gcloud ai models list --region=us-central1)

---

Next Steps

Once setup is complete:

1. For Imagen: Use the imagen-prompt skill to generate images
2. For other models: Explore available models with gcloud ai models list --region=us-central1
3. Production deployment: Switch to service account authentication (see Step 2.2 Option B)
4. Cost management: Set up budget alerts at https://console.cloud.google.com/billing/budgets

---

You are now ready to use Vertex AI and Imagen. The setup provides secure, authenticated access to Google's AI models with proper project configuration and API enablement.