Merge pull request #906 from jrdnbradford/google-troubleshooting-updates

Google Cloud troubleshooting and configuration updates

Author: consideRatio

docs/howto/index.md

@@ -65,4 +65,5 @@ admin/systemd
 
 providers/digitalocean
 providers/azure
+providers/google
 ```

docs/howto/providers/google.md

@@ -0,0 +1,63 @@
+(howto-providers-google)=
+
+# Perform common Google Cloud configuration tasks
+
+This page lists various common tasks you can perform on your
+Google Cloud virtual machine.
+
+(howto-providers-google-resize-disk)=
+
+## Increasing your boot disk size
+
+Boot disks contain the operating system and boot loader for your TLJH instance. If you followed
+the [Google Cloud TLJH installation instructions](#install-google) then you created a virtual machine
+with one disk: a boot disk that will _also_ be used to hold user data in your hub. For various reasons
+you may need to change your boot disk size.
+
+Google Cloud Compute Engine supports _increasing_ (but not _decreasing_) the size of existing disks.
+If you selected a boot disk with a supported version of **Ubuntu** or **Debian** as the operating
+system, then your boot disk can be resized easily from the console with these steps.
+
+:::{note}
+Google Cloud resizes the root partition and file system for _boot_ disks with _public_ images
+(such as the TLJH supported **Ubuntu** and **Debian** images) automatically after your increase
+the size of your disk. If you have any other _non-boot_ disks attached to your instance, you
+will need to perform extra steps yourself after resizing your disk. For more information on
+this and other aspects of resizing persistent disks, see
+[Google's documentation](https://cloud.google.com/compute/docs/disks/resize-persistent-disk).
+:::
+
+1. Go to [Google Cloud Console -> Compute Engine -> VM instances](https://console.cloud.google.com/compute/instances) and select your TLJH instance.
+
+1. Scroll down until you find your boot disk and select it.
+
+   ```{image} ../../images/providers/google/boot-disk-resize.png
+   :alt: Boot disk with Ubuntu jammy image
+   ```
+
+1. Select **Edit** in the top menu. This may require selecting the kebab menu (the 3 vertical dots).
+
+   ```{image} ../../images/providers/google/boot-disk-edit-button.png
+   :alt: Disk edit button
+   ```
+
+1. Update the **Size** property and save the changes at the bottom of the page.
+
+   ```{image} ../../images/providers/google/boot-disk-resize-properties.png
+   :alt: Boot disk size property
+   ```
+
+1. Reboot the VM instance by logging into your TLJH, opening the terminal, and running `sudo reboot`.
+   You will lose your connection to the instance while it restarts. Once it comes back up, your disk
+   will reflect your changes. You can verify that the automatic resize of your root partition and
+   file system took place by running `df -h` in the terminal, which will show the size of the disk
+   mounted on `/`:
+   ```bash
+   $ df -h
+   Filesystem      Size  Used Avail Use% Mounted on
+   /dev/root        25G  6.9G   18G  28% /
+   tmpfs           2.0G     0  2.0G   0% /dev/shm
+   tmpfs           785M  956K  784M   1% /run
+   tmpfs           5.0M     0  5.0M   0% /run/lock
+   /dev/sda15      105M  6.1M   99M   6% /boot/efi
+   ```

docs/images/providers/google/boot-disk-edit-button.png

@@ -3,6 +3,23 @@
 This is an incomplete list of issues people have run into when running
 TLJH on Google Cloud, and how they have fixed them!
 
+## Viewing VM instance logs
+
+In addition to [installer, JupyterHub, traefik, and other logs](#troubleshooting-logs)
+you can view VM instance logs on Google Cloud to help diagnose issues. These logs will contain
+detailed information and error stack traces and can be viewed from
+[Google Cloud Console -> Compute Engine -> VM instances](https://console.cloud.google.com/compute/instances).
+Once you select your TLJH instance, select **Serial port 1 (console)**:
+
+```{image} ../../images/providers/google/serial-port-console.png
+:alt: Serial port 1 (console) under Logs heading
+```
+
+:::{tip}
+The console will show the logs of any startup scripts you configured for your instance,
+making it easy to see if it has completed and/or encountered any errors.
+:::
+
 ## 'Connection Refused' error after restarting server
 
 If you restarted your server from the Google Cloud console & then try to access
@@ -15,3 +32,16 @@ IP address, you might have to change it to point to the new correct IP.
 
 You can prevent External IP changes by [reserving the static IP](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip)
 your server is using.
+
+## Issues caused by lack of disk space
+
+If your boot disk becomes full, this can cause your instance to become unavailable,
+among other problems. If your instance appears up and running in the console but
+you cannot access it at your configured external IP/domain name, this could be caused
+by a lack of disk space.
+
+You can explore your [VM logs in the console](#viewing-vm-instance-logs) to determine
+if any issues you are experiencing indicate disk space issues.
+
+To resolve these types of issues, you can
+[increase your boot disk size](#howto-providers-google-resize-disk).