GCP Alloydb

AlloyDB Skill

Manage and analyze Google AlloyDB for PostgreSQL using gcloud alloydb commands.

Discovery-First Rule

ALWAYS discover before acting. Never assume cluster names, instance names, regions, or backup names.

# Discover AlloyDB clusters
gcloud alloydb clusters list --format=json \
  | jq '[.[] | {name: .name | split("/") | last, state: .state, databaseVersion: .databaseVersion, network: .network, location: .name | split("/") | .[3], continuousBackupEnabled: .continuousBackupConfig.enabled}]'

Parallel Execution Requirement

ALL independent operations MUST run in parallel using background jobs (&) and wait.

for cluster in $(gcloud alloydb clusters list --format="value(name)" | xargs -I{} basename {}); do
  {
    gcloud alloydb clusters describe "$cluster" --region="$REGION" --format=json
  } &
done
wait

Helper Functions

# Get cluster details
get_cluster_details() {
  local cluster="$1" region="$2"
  gcloud alloydb clusters describe "$cluster" --region="$region" --format=json \
    | jq '{name: .name | split("/") | last, state: .state, databaseVersion: .databaseVersion, network: .network, encryptionConfig: .encryptionConfig, continuousBackup: .continuousBackupConfig, automatedBackup: .automatedBackupPolicy, initialUser: .initialUser.user}'
}

# List instances in a cluster
list_instances() {
  local cluster="$1" region="$2"
  gcloud alloydb instances list --cluster="$cluster" --region="$region" --format=json \
    | jq '[.[] | {name: .name | split("/") | last, instanceType: .instanceType, state: .state, machineConfig: .machineConfig, availabilityType: .availabilityType, ipAddress: .ipAddress, readPoolConfig: .readPoolConfig, queryInsights: .queryInsightsConfig}]'
}

# List backups
list_backups() {
  local region="$1"
  gcloud alloydb backups list --region="$region" --format=json \
    | jq '[.[] | {name: .name | split("/") | last, state: .state, type: .type, cluster: .clusterName | split("/") | last, createTime: .createTime, sizeBytes: .sizeBytes}]'
}

# Get instance metrics
get_instance_metrics() {
  local instance="$1" cluster="$2"
  gcloud monitoring time-series list \
    --filter="metric.type=starts_with(\"alloydb.googleapis.com/\") AND resource.labels.instance_id=\"$instance\"" \
    --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
    --format=json --limit=50
}

Common Operations

1. Cluster and Instance Overview

clusters=$(gcloud alloydb clusters list --format=json \
  | jq -c '[.[] | {name: .name | split("/") | last, region: .name | split("/") | .[3]}]')
for c in $(echo "$clusters" | jq -c '.[]'); do
  {
    name=$(echo "$c" | jq -r '.name')
    region=$(echo "$c" | jq -r '.region')
    echo "=== Cluster: $name ==="
    get_cluster_details "$name" "$region"
    list_instances "$name" "$region"
  } &
done
wait

2. Instance Analysis

# Primary and read pool instances
gcloud alloydb instances list --cluster="$CLUSTER" --region="$REGION" --format=json \
  | jq '[.[] | {name: .name | split("/") | last, type: .instanceType, state: .state, cpu: .machineConfig.cpuCount, availabilityType: .availabilityType, readPoolNodeCount: .readPoolConfig.nodeCount, gceZone: .gceZone}]'

# Check Query Insights configuration
gcloud alloydb instances describe "$INSTANCE" --cluster="$CLUSTER" --region="$REGION" --format=json \
  | jq '{queryInsights: .queryInsightsConfig}'

3. Query Insights

# CPU utilization per instance
gcloud monitoring time-series list \
  --filter="metric.type=\"alloydb.googleapis.com/instance/cpu/utilization\" AND resource.labels.instance_id=\"$INSTANCE\"" \
  --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
  --format=json

# Database connections
gcloud monitoring time-series list \
  --filter="metric.type=\"alloydb.googleapis.com/instance/postgresql/backends\" AND resource.labels.instance_id=\"$INSTANCE\"" \
  --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
  --format=json

# Replication lag (for read pool instances)
gcloud monitoring time-series list \
  --filter="metric.type=\"alloydb.googleapis.com/instance/postgresql/replication/replica_byte_lag\" AND resource.labels.instance_id=\"$INSTANCE\"" \
  --interval-start-time="$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
  --format=json

4. Backup and Recovery

# List all backups
list_backups "$REGION"

# Continuous backup config
gcloud alloydb clusters describe "$CLUSTER" --region="$REGION" --format=json \
  | jq '{continuousBackup: .continuousBackupConfig, automatedBackup: .automatedBackupPolicy}'

# Check point-in-time recovery window
gcloud alloydb clusters describe "$CLUSTER" --region="$REGION" --format=json \
  | jq '{continuousBackupInfo: .continuousBackupInfo}'

5. Maintenance Configuration

# Check maintenance window
gcloud alloydb clusters describe "$CLUSTER" --region="$REGION" --format=json \
  | jq '{maintenanceUpdatePolicy: .maintenanceUpdatePolicy, maintenanceSchedule: .maintenanceSchedule}'

# Recent operations (maintenance, updates)
gcloud alloydb operations list --region="$REGION" --format=json --limit=10 \
  | jq '[.[] | {name: .name | split("/") | last, type: .metadata."@type", done: .done, startTime: .metadata.createTime}]'

Output Format

Present results as a structured report:

Gcp Alloydb Report
══════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

1. Primary vs read pool: AlloyDB has one primary instance and optional read pool instances. Read pools auto-scale nodes but the primary does not.
2. Machine type changes: Changing CPU count requires instance restart. Plan maintenance windows for resize operations.
3. Network requirement: AlloyDB requires a VPC with Private Services Access configured. Instances are not publicly accessible by default.
4. Continuous backup retention: Default continuous backup retention is 14 days. Cannot be extended beyond 35 days. Plan accordingly for compliance.
5. Query Insights: Query Insights must be explicitly enabled per instance. It adds minimal overhead but provides critical performance data. Check queryInsightsConfig.queryInsightsEnabled.