# GCE Rescue #
[](https://github.com/GoogleCloudPlatform/gce-rescue/actions/workflows/test.yml?query=branch%3Amain+event%3Apush)
This page shows you how to rescue a virtual machine (VM) instance by using GCE Rescue.
With GCE Rescue, you can boot the VM instance using a temporary boot disk to fix any problem that may be stopping the VM instance. Specifically, GCE Rescue uses a temporary Linux image as the VM instance’s boot disk to let you do maintenance on the faulty boot disk while it is in rescue mode.
When running GCE Rescue, it creates a snapshot of the existing boot disk for backup.
After you’ve fixed the faulty disk, you can then restore the original configuration by running GCE Rescue again to reboot the VM instance in normal mode again.
The advantage of using GCE Rescue is that it uses the resources already configured on the VM instance, such as networking, VPC firewalls or routes, to restore the faulty boot disk instead of creating a duplicate VM instance to restore the faulty boot disk.
>Note: **`GCE Rescue is not an officially supported Google Cloud product`**. The Google Cloud Support team maintains this repository, but the product is experimental and, therefore, it can be unstable.
## Installation ##
To install GCE Rescue, follow these steps:
1. Clone the git repository to your local machine:
```
$ git clone https://github.com/GoogleCloudPlatform/gce-rescue.git
```
2. Navigate to the `cd/gce-rescue` folder:
```
$ cd gce-rescue/
```
3. To install GCE Rescue, select one of the following options:
* Install GCE Rescue globally.
```
$ sudo python3 setup.py install
```
* Install GCE Rescue locally.
```
$ python3 setup.py install --user
```
> Note: If you cannot find the gce-rescue executable after your install
GCE Rescue, add the Python Library to your PATH:
>
```
$ export PATH=$PATH:$(python3 -m site --user-base)/bin
```
---
## Usage ##
```
gce-rescue --help
usage: gce-rescue [-h] [-p PROJECT] -z ZONE -n NAME [-d] [-f] [--skip-snapshot]
GCE Rescue v0.4-beta - Set/Reset GCE instances to boot in rescue mode.
optional arguments:
-h, --help show this help message and exit
-p PROJECT, --project PROJECT
The project-id that has the instance.
-z ZONE, --zone ZONE Zone where the instance is created.
-n NAME, --name NAME Instance name.
-d, --debug Print to the log file in debug leve
-f, --force Don't ask for confirmation.
--skip-snapshot Skip backing up the disk using a snapshot.
```
- ### --zone ###
- The instances zone. (REQUIRED)
- ### --name ###
- The instance name (not instance ID). (REQUIRED)
- ### --project ###
- The project-id of the faulty instance. (OPTIONAL)
- ### --force ###
- Do not ask for confirmation. It can be useful when running from a script.
- ### --debug ###
- If provided, the log output will be set to DEBUG level. (OPTIONAL)
- The log file will be created on ./ containing the VM name and timestamp on the name, that can be used to help to troubleshoot failed executions as well as to manually recover the instance's original configuration, if necessary.
- > The log files contain important information about the initial state of the VM instance that may be required to manually restore it.
- ### --skip-snapshot ###
- Skip the snapshot creation. (OPTIONAL)
- Before setting your instance in rescue mode, GCE Rescue will always create a snapshot of your boot disk before taking any action. For some users this might be time consuming and not always necessary. Use this argument if you want to skip this step.
---
## Examples ##
```shellscript
$ gce-rescue --zone europe-central2-a --name test
This option will boot the instance test in RESCUE MODE.
If your instance is running it will be rebooted.
Do you want to continue [y/N]: y
Starting...
┌── Configuring...
│ └── Progress 6/6 [█████████████████████████████████████████████████████████████]
├── Configurations finished.
└── Your instance is READY! You can now connect your instance "test" via:
1. CLI. (add --tunnel-through-iap if necessary)
$ gcloud compute ssh test --zone=europe-central2-a --project=my-project --ssh-flag="-o StrictHostKeyChecking=no"
OR
2. Google Cloud Console:
https://ssh.cloud.google.com/v2/ssh/projects/my-project/zones/europe-central2-a/instances/test?authuser=0&hl=en_US&useAdminProxy=true&troubleshoot4005Enabled=true
```
Once your VM instance is in rescue mode you can connect via SSH, as you normally would do.
Notice that `-rescue` was added to your hostname, to highlight that you are currently in rescue mode.
The original boot disk should be automatically mounted on `/mnt/sysroot`:
```shellscript
user@test-rescue:~$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 10G 0 disk
├─sda1 8:1 0 9.9G 0 part /
├─sda14 8:14 0 3M 0 part
└─sda15 8:15 0 124M 0 part /boot/efi
sdb 8:16 0 30G 0 disk
├─sdb1 8:17 0 2M 0 part
├─sdb2 8:18 0 20M 0 part
└─sdb3 8:19 0 30G 0 part /mnt/sysroot
user@test-rescue:~$ chroot /mnt/sysroot
```
At this point you should take the necessary actions to restore your faulty boot disk.
When finished you can close your SSH connections and restore the VM instance to the original mode, by running the same command again:
```shellscript
$ gce-rescue --zone europe-central2-a --name test
The instance "test" is currently configured to boot as rescue mode since 2022-11-01 12:05:08.
Would you like to restore the original configuration ? [y/N]: y
Restoring VM...
- Configuring...
\- Progress 4/4 [█████████████████████████████████████████████████████████████]
- Configurations finished.
- The instance test was restored! Use the snapshot below if you need to restore the modification made while the instance was in rescue mode.
Snapshot name: test-1668009968
More information: https://cloud.google.com/compute/docs/disks/restore-snapshot
```
> A snapshot was taken before setting the instance in Rescue Mode and can be used to recover the disk status.
You will be able to idenfiy the snapshot name, like in the example above is: `test-1668009968`.
#
# You are ready !
When you connect again you will noticed the your instance is back to the normal mode:
```shellscript
user@test:~> uptime
12:24:18 up 0:05, 1 user, load average: 0.00, 0.00, 0.00
user@test:~> lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
sda 8:0 0 30G 0 disk
├─sda1 8:1 0 2M 0 part
├─sda2 8:2 0 20M 0 part /boot/efi
└─sda3 8:3 0 30G 0 part /
user@test:~>
```
---
## Authentication ##
This script makes use of Application Default Credentials (ADC). Make sure you have gcloud installed and your ADC updated.
You can find more information on: https://cloud.google.com/docs/authentication/provide-credentials-adc
----
## Permissions ##
This is the list of the minimal IAM permissions required.
| Description | Permissions|
|----------:|----------|
| Start and stop instance | compute.instances.stop <br/> compute.instances.start |
| Create and remove disk | compute.instances.attachDisk on the instance <br/> compute.instances.detachDisk on the instance <br/> compute.images.useReadOnly on the image if creating a new root persistent disk <br/> compute.disks.use on the disk if attaching an existing disk in read/write mode <br/> compute.disks.setLabels on the disk if setting labels |
| Create snapshot | compute.snapshots.create on the project <br/> compute.disks.createSnapshot on the disk |
| Configure metadata | compute.instances.setMetadata if setting metadata <br/> compute.instances.setLabels on the instance if setting labels |
----
## Contact ##
### GCE Rescue Team ###
gce-rescue-dev@google.com
Raw data
{
"_id": null,
"home_page": "https://github.com/googlecloudplatform/gce-rescue",
"name": "gce-rescue",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Halley de Souza",
"author_email": "gce-rescue-dev@google.com",
"download_url": "https://files.pythonhosted.org/packages/d5/50/5533d0e7db078ada3fc2e2c31b302a06caad203fe9b19271c42b3160978a/gce-rescue-0.4.tar.gz",
"platform": null,
"description": "# GCE Rescue #\n[](https://github.com/GoogleCloudPlatform/gce-rescue/actions/workflows/test.yml?query=branch%3Amain+event%3Apush)\n\n\nThis page shows you how to rescue a virtual machine (VM) instance by using GCE Rescue. \n\nWith GCE Rescue, you can boot the VM instance using a temporary boot disk to fix any problem that may be stopping the VM instance. Specifically, GCE Rescue uses a temporary Linux image as the VM instance\u2019s boot disk to let you do maintenance on the faulty boot disk while it is in rescue mode.\n\nWhen running GCE Rescue, it creates a snapshot of the existing boot disk for backup. \n\nAfter you\u2019ve fixed the faulty disk, you can then restore the original configuration by running GCE Rescue again to reboot the VM instance in normal mode again.\n\nThe advantage of using GCE Rescue is that it uses the resources already configured on the VM instance, such as networking, VPC firewalls or routes, to restore the faulty boot disk instead of creating a duplicate VM instance to restore the faulty boot disk. \n\n>Note: **`GCE Rescue is not an officially supported Google Cloud product`**. The Google Cloud Support team maintains this repository, but the product is experimental and, therefore, it can be unstable.\n\n\n## Installation ##\n\n\nTo install GCE Rescue, follow these steps:\n\n1. Clone the git repository to your local machine:\n\n``` \n$ git clone https://github.com/GoogleCloudPlatform/gce-rescue.git\n```\n\n2. Navigate to the `cd/gce-rescue` folder:\n\n```\n$ cd gce-rescue/\n```\n\n3. To install GCE Rescue, select one of the following options: \n\n* Install GCE Rescue globally.\n\n``` \n$ sudo python3 setup.py install\n```\n\n* Install GCE Rescue locally.\n\n```\n$ python3 setup.py install --user\n```\n\n> Note: If you cannot find the gce-rescue executable after your install \nGCE Rescue, add the Python Library to your PATH:\n>\n```\n$ export PATH=$PATH:$(python3 -m site --user-base)/bin\n```\n\n---\n\n## Usage ##\n\n```\ngce-rescue --help\nusage: gce-rescue [-h] [-p PROJECT] -z ZONE -n NAME [-d] [-f] [--skip-snapshot]\n\nGCE Rescue v0.4-beta - Set/Reset GCE instances to boot in rescue mode.\n\noptional arguments:\n -h, --help show this help message and exit\n -p PROJECT, --project PROJECT\n The project-id that has the instance.\n -z ZONE, --zone ZONE Zone where the instance is created.\n -n NAME, --name NAME Instance name.\n -d, --debug Print to the log file in debug leve\n -f, --force Don't ask for confirmation.\n --skip-snapshot Skip backing up the disk using a snapshot.\n```\n\n- ### --zone ### \n - The instances zone. (REQUIRED)\n- ### --name ###\n - The instance name (not instance ID). (REQUIRED)\n- ### --project ###\n - The project-id of the faulty instance. (OPTIONAL)\n- ### --force ###\n - Do not ask for confirmation. It can be useful when running from a script.\n- ### --debug ###\n - If provided, the log output will be set to DEBUG level. (OPTIONAL)\n - The log file will be created on ./ containing the VM name and timestamp on the name, that can be used to help to troubleshoot failed executions as well as to manually recover the instance's original configuration, if necessary.\n\n - > The log files contain important information about the initial state of the VM instance that may be required to manually restore it.\n\n\n- ### --skip-snapshot ###\n - Skip the snapshot creation. (OPTIONAL) \n - Before setting your instance in rescue mode, GCE Rescue will always create a snapshot of your boot disk before taking any action. For some users this might be time consuming and not always necessary. Use this argument if you want to skip this step.\n\n---\n\n## Examples ##\n\n```shellscript\n$ gce-rescue --zone europe-central2-a --name test\n\nThis option will boot the instance test in RESCUE MODE.\nIf your instance is running it will be rebooted.\nDo you want to continue [y/N]: y\nStarting...\n\u250c\u2500\u2500 Configuring...\n\u2502 \u2514\u2500\u2500 Progress 6/6 [\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588]\n\u251c\u2500\u2500 Configurations finished.\n\u2514\u2500\u2500 Your instance is READY! You can now connect your instance \"test\" via:\n 1. CLI. (add --tunnel-through-iap if necessary)\n $ gcloud compute ssh test --zone=europe-central2-a --project=my-project --ssh-flag=\"-o StrictHostKeyChecking=no\"\n OR\n 2. Google Cloud Console:\n https://ssh.cloud.google.com/v2/ssh/projects/my-project/zones/europe-central2-a/instances/test?authuser=0&hl=en_US&useAdminProxy=true&troubleshoot4005Enabled=true\n\n```\n\nOnce your VM instance is in rescue mode you can connect via SSH, as you normally would do.\n\nNotice that `-rescue` was added to your hostname, to highlight that you are currently in rescue mode.\n\nThe original boot disk should be automatically mounted on `/mnt/sysroot`:\n\n```shellscript\nuser@test-rescue:~$ lsblk\nNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT\nsda 8:0 0 10G 0 disk\n\u251c\u2500sda1 8:1 0 9.9G 0 part /\n\u251c\u2500sda14 8:14 0 3M 0 part\n\u2514\u2500sda15 8:15 0 124M 0 part /boot/efi\nsdb 8:16 0 30G 0 disk\n\u251c\u2500sdb1 8:17 0 2M 0 part\n\u251c\u2500sdb2 8:18 0 20M 0 part\n\u2514\u2500sdb3 8:19 0 30G 0 part /mnt/sysroot\n\nuser@test-rescue:~$ chroot /mnt/sysroot\n```\n\nAt this point you should take the necessary actions to restore your faulty boot disk.\n\nWhen finished you can close your SSH connections and restore the VM instance to the original mode, by running the same command again:\n\n```shellscript\n$ gce-rescue --zone europe-central2-a --name test\n\nThe instance \"test\" is currently configured to boot as rescue mode since 2022-11-01 12:05:08.\nWould you like to restore the original configuration ? [y/N]: y\nRestoring VM...\n- Configuring...\n \\- Progress 4/4 [\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588]\n- Configurations finished.\n- The instance test was restored! Use the snapshot below if you need to restore the modification made while the instance was in rescue mode.\n Snapshot name: test-1668009968\n More information: https://cloud.google.com/compute/docs/disks/restore-snapshot\n\n```\n\n> A snapshot was taken before setting the instance in Rescue Mode and can be used to recover the disk status.\nYou will be able to idenfiy the snapshot name, like in the example above is: `test-1668009968`.\n\n#\n# You are ready !\n\nWhen you connect again you will noticed the your instance is back to the normal mode:\n\n```shellscript\nuser@test:~> uptime\n 12:24:18 up 0:05, 1 user, load average: 0.00, 0.00, 0.00\n\nuser@test:~> lsblk\nNAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS\nsda 8:0 0 30G 0 disk\n\u251c\u2500sda1 8:1 0 2M 0 part\n\u251c\u2500sda2 8:2 0 20M 0 part /boot/efi\n\u2514\u2500sda3 8:3 0 30G 0 part /\n\nuser@test:~>\n```\n\n---\n\n## Authentication ##\n\nThis script makes use of Application Default Credentials (ADC). Make sure you have gcloud installed and your ADC updated.\n\nYou can find more information on: https://cloud.google.com/docs/authentication/provide-credentials-adc\n\n----\n\n## Permissions ##\n\nThis is the list of the minimal IAM permissions required.\n\n| Description | Permissions|\n|----------:|----------|\n| Start and stop instance | compute.instances.stop <br/> compute.instances.start |\n| Create and remove disk | compute.instances.attachDisk on the instance <br/> compute.instances.detachDisk on the instance <br/> compute.images.useReadOnly on the image if creating a new root persistent disk <br/> compute.disks.use on the disk if attaching an existing disk in read/write mode <br/> compute.disks.setLabels on the disk if setting labels |\n| Create snapshot | compute.snapshots.create on the project <br/> compute.disks.createSnapshot on the disk |\n| Configure metadata | compute.instances.setMetadata if setting metadata <br/> compute.instances.setLabels on the instance if setting labels |\n\n----\n\n## Contact ##\n\n### GCE Rescue Team ###\ngce-rescue-dev@google.com\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "GCE Rescue - Boot your GCE VM in rescue mode.",
"version": "0.4",
"project_urls": {
"Homepage": "https://github.com/googlecloudplatform/gce-rescue"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8fa094d4956ff3e135f52cacbbaa3d826ed4fbfe22cddfad6d26e569953511dc",
"md5": "96d5cd7e3a3644870e28611ff7cae15f",
"sha256": "e62a6f20f4eedf3ff516d9677dbdaf64f1dd3647742887ae6f2900f0c6ac1757"
},
"downloads": -1,
"filename": "gce_rescue-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96d5cd7e3a3644870e28611ff7cae15f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 37984,
"upload_time": "2023-09-26T12:42:52",
"upload_time_iso_8601": "2023-09-26T12:42:52.659469Z",
"url": "https://files.pythonhosted.org/packages/8f/a0/94d4956ff3e135f52cacbbaa3d826ed4fbfe22cddfad6d26e569953511dc/gce_rescue-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5505533d0e7db078ada3fc2e2c31b302a06caad203fe9b19271c42b3160978a",
"md5": "97cc87628bcf46a143adf71646ba5cf9",
"sha256": "21533ed88573b6a86203749b256b03c5831b66934b34cb2255f845e561b4fc96"
},
"downloads": -1,
"filename": "gce-rescue-0.4.tar.gz",
"has_sig": false,
"md5_digest": "97cc87628bcf46a143adf71646ba5cf9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24912,
"upload_time": "2023-09-26T12:42:54",
"upload_time_iso_8601": "2023-09-26T12:42:54.461066Z",
"url": "https://files.pythonhosted.org/packages/d5/50/5533d0e7db078ada3fc2e2c31b302a06caad203fe9b19271c42b3160978a/gce-rescue-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-26 12:42:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "googlecloudplatform",
"github_project": "gce-rescue",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "absl-py",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "google-api-python-client",
"specs": []
},
{
"name": "google-auth",
"specs": []
}
],
"lcname": "gce-rescue"
}
JSON
