gcp-migration_skill

Overview

This skill guides a full migration between Google Cloud projects, covering databases, Cloud Storage, container images, Terraform state changes, and CI/CD secrets. It provides step-by-step commands, troubleshooting tips for common Cloud Run and VPC issues, and an automation script to run the data migration end-to-end. Use it to move production workloads safely while preserving runtime configuration and access controls.

How this skill works

The skill walks you through enabling required APIs in the destination project, exporting and importing Cloud SQL data via a storage bucket, syncing GCS buckets, and pulling/tagging/pushing container images between Artifact Registry repositories. It highlights the Terraform variable changes required, shows how to update GitHub Actions secrets for workload identity, and includes Cloud Run Job fixes (VPC connector, env vars) plus a one-shot migration script.

When to use it

• Migrating production services from one GCP project to another for billing or isolation reasons.
• Cloning an environment for staging, disaster recovery, or regional relocation.
• Transferring databases, buckets, and container images while keeping CI/CD pipelines intact.
• When you need a reproducible checklist and scripts to avoid manual omissions.
• During a consolidation or split of projects that use Terraform and GitHub Actions.

Best practices

• Ensure Owner/Editor access on both projects and authenticate gcloud to the correct accounts before each step.
• Deploy Terraform infra in the new project first, then update only project_id and region variables; handle backend.bucket manually.
• Use a dedicated GCS migration bucket and grant service accounts minimal IAM roles required for export/import.
• Preserve existing environment variables when updating Cloud Run jobs by using --update-env-vars, not --set-env-vars.
• Create and attach a VPC Connector when Cloud Run jobs need Cloud SQL Private IP access; verify network ranges to avoid conflicts.
• Test the migration in a non-production copy, validate traffic and credentials, and perform a cutover during a maintenance window.

Example use cases

• Move a fullstack monorepo deployment (Next.js, FastAPI, Flutter) to a new billing project without downtime.
• Copy production Cloud SQL data and assets to a regional replica project for DR testing.
• Migrate container images and Artifact Registry repos when reorganizing teams or projects.
• Switch GitHub Actions to a new workload identity provider and service account after project rename.
• Fix failing Cloud Run migration jobs by creating VPC connectors and reconfiguring env vars before re-executing.