GCE Rescue

Rescue unbootable Google Compute Engine VMs by swapping disks on the same VM — no new instance created, same IP, no data loss. Creates a safety snapshot before any changes.

Auto-fix path: The repair command reads serial console output, identifies the boot failure, and applies a fix automatically end to end.

Rescue path: When auto-fix is not available for the detected issue, the rescue command swaps your broken boot disk with a rescue disk and attaches the original boot disk as a secondary disk, providing a rescue environment for manual repair. Once fixed, the restore command puts your fixed boot disk back.

gce-rescue diagnose my-vm --zone=us-central1-a    # What's wrong?
gce-rescue repair my-vm --zone=us-central1-a      # Auto-fix it

Note: GCE Rescue is not an officially supported Google Cloud product. The Google Cloud Support team maintains this repository.

Requirements: Python >= 3.9, gcloud CLI, roles/compute.instanceAdmin.v1 IAM role.

Installation

Google Cloud Shell (recommended)

Open Cloud Shell — Python, gcloud, and authentication are already set up.

pip install gce-rescue

Verify the installation:

gce-rescue -h

If gce-rescue is not found after install, start a new shell session or run:

export PATH="$HOME/.local/bin:$PATH"

curl -sSL https://raw.githubusercontent.com/GoogleCloudPlatform/gce-rescue/main/install.sh | bash

irm https://raw.githubusercontent.com/GoogleCloudPlatform/gce-rescue/main/install.ps1 | iex

git clone https://github.com/GoogleCloudPlatform/gce-rescue.git
cd gce-rescue
pip install .

Usage

Start with diagnose — understand what's wrong (safe, read-only)

gce-rescue diagnose VM_NAME --zone=ZONE

Auto-fix available? — let repair handle it automatically

gce-rescue repair VM_NAME --zone=ZONE

Already know the fix? — supply your own fix script (skips diagnosis)

gce-rescue repair VM_NAME --zone=ZONE --fix-script=fix.sh

Ideal for large-scale events where many VMs share one known fix: the script runs against the mounted boot disk, then the VM is restored and boot-verified automatically. Add --quiet for automation.

Need manual access? — enter rescue mode, fix it yourself

gce-rescue rescue VM_NAME --zone=ZONE

# SSH/RDP in, fix the issue on /mnt/sysroot

gce-rescue restore VM_NAME --zone=ZONE

All operations create a snapshot before changes, roll back automatically on failure, and can resume if interrupted.

$ gce-rescue diagnose my-vm --zone=us-central1-a
Diagnosis: my-vm (us-central1-a)
Status:    RUNNING
OS:        Linux (debian-12-bookworm, x86_64, Free)
Result:    Found 1 boot error(s)

  [fstab_bad_uuid] Bad UUID in /etc/fstab (critical)
    Line: UUID=abcd-1234  /data  ext4  defaults  0  2
    Fix:  Remove or correct the fstab entry, then reboot

  Recommended: gce-rescue repair my-vm --zone=us-central1-a

Authentication

More info: Application Default Credentials

Flags

Update check

At the end of rescue, restore, diagnose, and repair, the CLI checks PyPI (https://pypi.org/pypi/gce-rescue/json) for a newer release and prints an upgrade notice to stderr if one exists. The check runs at most once every 24 hours (cached in ~/.config/gce-rescue/version-check.json), never delays or fails a command, and is skipped entirely with --quiet, with machine-readable --format values, or when the environment variable GCE_RESCUE_DISABLE_VERSION_CHECK=1 is set — use the variable in restricted networks where outbound calls to pypi.org are unwanted.

Features

Permissions

roles/compute.instanceAdmin.v1 includes all permissions needed for every command.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:EMAIL" \
    --role="roles/compute.instanceAdmin.v1"

V1 Legacy

V1 is available as gce-rescue-v1 for backward compatibility:

gce-rescue-v1 -n VM_NAME -z ZONE -p PROJECT

See the V1 documentation for details.

Uninstall

pip uninstall gce-rescue

# Linux/macOS (if installed via install script)
rm -rf ~/.gce-rescue

Contact

GCE Rescue Team: gce-rescue-dev@google.com