diff --git a/docs/howto/index.md b/docs/howto/index.md index 05c2a84..208f14e 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -65,4 +65,5 @@ admin/systemd providers/digitalocean providers/azure +providers/google ``` diff --git a/docs/howto/providers/google.md b/docs/howto/providers/google.md new file mode 100644 index 0000000..0d81e95 --- /dev/null +++ b/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 + ``` diff --git a/docs/images/providers/google/boot-disk-edit-button.png b/docs/images/providers/google/boot-disk-edit-button.png new file mode 100644 index 0000000..65319c5 Binary files /dev/null and b/docs/images/providers/google/boot-disk-edit-button.png differ diff --git a/docs/images/providers/google/boot-disk-resize-properties.png b/docs/images/providers/google/boot-disk-resize-properties.png new file mode 100644 index 0000000..862115a Binary files /dev/null and b/docs/images/providers/google/boot-disk-resize-properties.png differ diff --git a/docs/images/providers/google/boot-disk-resize.png b/docs/images/providers/google/boot-disk-resize.png new file mode 100644 index 0000000..638fc4d Binary files /dev/null and b/docs/images/providers/google/boot-disk-resize.png differ diff --git a/docs/images/providers/google/serial-port-console.png b/docs/images/providers/google/serial-port-console.png new file mode 100644 index 0000000..61384dc Binary files /dev/null and b/docs/images/providers/google/serial-port-console.png differ diff --git a/docs/troubleshooting/providers/google.md b/docs/troubleshooting/providers/google.md index 714d261..74c4417 100644 --- a/docs/troubleshooting/providers/google.md +++ b/docs/troubleshooting/providers/google.md @@ -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).