{"id":15222179,"url":"https://github.com/googlecloudplatform/gce-rescue","last_synced_at":"2026-05-21T10:01:50.009Z","repository":{"id":63242347,"uuid":"563512205","full_name":"GoogleCloudPlatform/gce-rescue","owner":"GoogleCloudPlatform","description":"GCE Rescue is a command-line tool to boot Google Cloud Platform VMs in Rescue Mode.  Topics","archived":false,"fork":false,"pushed_at":"2025-02-19T16:20:18.000Z","size":253,"stargazers_count":45,"open_issues_count":10,"forks_count":5,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-03-30T15:42:45.135Z","etag":null,"topics":["boot-disk","bootdisk","cloud","gce","gce-instance","gcp","google","instances","rescue","rescue-system","troubleshooting","vm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-08T19:11:37.000Z","updated_at":"2025-03-26T00:16:21.000Z","dependencies_parsed_at":"2023-09-23T08:35:14.022Z","dependency_job_id":"2d9f2661-c6e5-45ad-a711-023e48db355b","html_url":"https://github.com/GoogleCloudPlatform/gce-rescue","commit_stats":{"total_commits":73,"total_committers":8,"mean_commits":9.125,"dds":0.6164383561643836,"last_synced_commit":"4d32bd23bb2b4863d788d1df5607f2c99851e120"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fgce-rescue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fgce-rescue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fgce-rescue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fgce-rescue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/gce-rescue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boot-disk","bootdisk","cloud","gce","gce-instance","gcp","google","instances","rescue","rescue-system","troubleshooting","vm"],"created_at":"2024-09-28T15:10:57.279Z","updated_at":"2026-05-21T10:01:50.002Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GCE Rescue\n\n[![V2 CI](https://github.com/GoogleCloudPlatform/gce-rescue/actions/workflows/v2-ci.yml/badge.svg?branch=main)](https://github.com/GoogleCloudPlatform/gce-rescue/actions/workflows/v2-ci.yml?query=branch%3Amain)\n[![PyPI version](https://img.shields.io/pypi/v/gce-rescue)](https://pypi.org/project/gce-rescue/)\n[![Python](https://img.shields.io/pypi/pyversions/gce-rescue)](https://pypi.org/project/gce-rescue/)\n[![License](https://img.shields.io/github/license/GoogleCloudPlatform/gce-rescue)](https://github.com/GoogleCloudPlatform/gce-rescue/blob/main/LICENSE)\n\nRescue 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.\n\n**Auto-fix path**: The `repair` command reads serial console output, identifies\nthe boot failure, and applies a fix automatically end to end.\n\n**Rescue path**: When auto-fix is not available for the detected issue, the\n`rescue` command swaps your broken boot disk with a rescue disk and attaches the\noriginal boot disk as a secondary disk, providing a rescue environment for manual\nrepair. Once fixed, the `restore` command puts your fixed boot disk back.\n\n```bash\ngce-rescue diagnose my-vm --zone=us-central1-a    # What's wrong?\ngce-rescue repair my-vm --zone=us-central1-a      # Auto-fix it\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"gce-rescue.svg\" alt=\"GCE Rescue Workflow\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003e **Note**: GCE Rescue is not an officially supported Google Cloud product. The Google Cloud Support team maintains this repository.\n\n**Requirements:** Python \u003e= 3.9, [gcloud CLI](https://cloud.google.com/sdk/docs/install), `roles/compute.instanceAdmin.v1` IAM role.\n\n## Installation\n\n### Google Cloud Shell (recommended)\n\nOpen \u003ca href=\"https://shell.cloud.google.com\" target=\"_blank\"\u003eCloud Shell\u003c/a\u003e — Python, gcloud, and authentication are already set up.\n\n```bash\npip install gce-rescue\n```\n\nVerify the installation:\n\n```bash\ngce-rescue -h\n```\n\n\u003e If `gce-rescue` is not found after install, start a new shell session or run:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLocal Machine\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n**Linux / macOS**\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/GoogleCloudPlatform/gce-rescue/main/install.sh | bash\n```\n\nMay require `sudo` if Python or pip is not installed.\n\n**Windows** (run PowerShell as Administrator)\n\n```powershell\nirm https://raw.githubusercontent.com/GoogleCloudPlatform/gce-rescue/main/install.ps1 | iex\n```\n\nThe installers handle all prerequisites (Python, gcloud, PATH, authentication)\nand will prompt before installing anything.\n\n---\n\n**Install from source** (requires Python \u003e= 3.9, [gcloud CLI](https://cloud.google.com/sdk/docs/install), Git)\n\n```bash\ngit clone https://github.com/GoogleCloudPlatform/gce-rescue.git\ncd gce-rescue\npip install .\n```\n\n\u003c/details\u003e\n\n## Usage\n\n**Start with diagnose** — understand what's wrong (safe, read-only)\n   ```bash\n   gce-rescue diagnose VM_NAME --zone=ZONE\n   ```\n\n**Auto-fix available?** — let repair handle it automatically\n   ```bash\n   gce-rescue repair VM_NAME --zone=ZONE\n   ```\n\n**Need manual access?** — enter rescue mode, fix it yourself\n   ```bash\n   gce-rescue rescue VM_NAME --zone=ZONE\n   \n   # SSH/RDP in, fix the issue on /mnt/sysroot\n\n   gce-rescue restore VM_NAME --zone=ZONE\n   ```\n| Command | What it does | Modifies VM? |\n|---------|-------------|:---:|\n| `diagnose` | Identifies boot errors from serial console output | No |\n| `repair` | Diagnoses and fixes boot issues automatically | Yes |\n| `rescue` | Provides a rescue environment for investigation via SSH/RDP | Yes |\n| `restore` | Reverses rescue, puts your fixed boot disk back | Yes |\n\nAll operations create a snapshot before changes, roll back automatically on\nfailure, and can resume if interrupted.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSample output: diagnose\u003c/b\u003e\u003c/summary\u003e\n\n```\n$ gce-rescue diagnose my-vm --zone=us-central1-a\nDiagnosis: my-vm (us-central1-a)\nStatus:    RUNNING\nOS:        Linux (debian-12-bookworm, x86_64, Free)\nResult:    Found 1 boot error(s)\n\n  [fstab_bad_uuid] Bad UUID in /etc/fstab (critical)\n    Line: UUID=abcd-1234  /data  ext4  defaults  0  2\n    Fix:  Remove or correct the fstab entry, then reboot\n\n  Recommended: gce-rescue repair my-vm --zone=us-central1-a\n```\n\n\u003c/details\u003e\n\n## Authentication\n\n| Environment | Setup |\n|---|---|\n| Cloud Shell | Pre-authenticated, nothing to do |\n| GCE VM (with service account) | Automatic via metadata server |\n| GCE VM (without compute scopes) | `gcloud auth application-default login` |\n| Local machine | `gcloud auth application-default login` |\n\nMore info: [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)\n\n### Flags\n\n| Flag | Description |\n|------|-------------|\n| `--zone` | GCP zone (required) |\n| `--project` | GCP project (default: current gcloud config) |\n| `--no-snapshot` | Skip safety snapshot (faster) |\n| `--quiet` | No confirmation prompts (for automation) |\n| `--format` | Output format: `json`, `yaml`, `table` |\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Linux + Windows** | Auto-detects OS, uses appropriate rescue environment |\n| **Boot Diagnostics** | Serial console analysis for fstab, GRUB, kernel, filesystem errors |\n| **Auto-Repair** | Automated fix for fstab errors (more categories planned) |\n| **Automatic Rollback** | Operations roll back on failure |\n| **Session Recovery** | Resume or rollback interrupted operations |\n| **Safety Snapshots** | Backup snapshot before any changes (default) |\n| **ARM64 Support** | Automatic architecture detection |\n\n## Permissions\n\n`roles/compute.instanceAdmin.v1` includes all permissions needed for every command.\n\n| Command | Minimum Role |\n|---------|-------------|\n| `diagnose` | `roles/compute.viewer` |\n| `rescue`, `restore`, `repair` | `roles/compute.instanceAdmin.v1` |\n\n```bash\ngcloud projects add-iam-policy-binding PROJECT_ID \\\n    --member=\"user:EMAIL\" \\\n    --role=\"roles/compute.instanceAdmin.v1\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull permissions matrix\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n| Permission | `diagnose` | `repair` | `rescue` | `restore` |\n|---|:---:|:---:|:---:|:---:|\n| `compute.projects.get` | x | x | x | x |\n| `compute.instances.get` | x | x | x | x |\n| `compute.instances.getSerialPortOutput` | x | x | x | |\n| `compute.instances.stop` | | x | x | x |\n| `compute.instances.start` | | x | x | x |\n| `compute.instances.attachDisk` | | x | x | x |\n| `compute.instances.detachDisk` | | x | x | x |\n| `compute.instances.setMetadata` | | x | x | x |\n| `compute.disks.create` | | x | x | |\n| `compute.disks.delete` | | x | x | x |\n| `compute.disks.get` | | x | x | x |\n| `compute.disks.createSnapshot` | | x* | x* | |\n| `compute.snapshots.create` | | x* | x* | |\n| `compute.snapshots.get` | | x* | x* | |\n| `compute.snapshots.list` | | x | | x |\n| `compute.snapshots.delete` | | x* | x* | |\n\n\\* Skippable with `--no-snapshot`\n\n\u003c/details\u003e\n\n## V1 Legacy\n\nV1 is available as `gce-rescue-v1` for backward compatibility:\n\n```bash\ngce-rescue-v1 -n VM_NAME -z ZONE -p PROJECT\n```\n\nSee the [V1 documentation](gce_rescue/README.md) for details.\n\n## Uninstall\n\n```bash\npip uninstall gce-rescue\n\n# Linux/macOS (if installed via install script)\nrm -rf ~/.gce-rescue\n```\n\n## Contact\n\nGCE Rescue Team: gce-rescue-dev@google.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fgce-rescue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecloudplatform%2Fgce-rescue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fgce-rescue/lists"}