====== iPXE in Google Cloud ======

You can use iPXE to boot [[https://cloud.google.com/products/compute|Google Cloud Compute Enigne (GCE)]] instances using a public iPXE image.  You can use an iPXE [[:scripting|script]] to direct the GCE instance to boot via any means supported by iPXE.  For example, you could boot a set of diskless GCE instances using HTTPS or iSCSI from a single server hosted in the same Google Cloud region.

===== Launching =====

The GCE iPXE images are published from the ''ipxe-images'' project.

^ CPU architecture   ^ Project name     ^ Image family name     ^
| ''x86_64''         | ''ipxe-images''  | ''ipxe''              |
| ''x86_64'' (UEFI)  | ''ipxe-images''  | ''ipxe-uefi-x86-64''  |
| ''arm64'' (UEFI)   | ''ipxe-images''  | ''ipxe-uefi-arm64''   |

You can launch an instance using a command such as

    gcloud compute instances create \
           --image-project ipxe-images --image-family ipxe \
           ...

You can use any compatible GCE instance type (including instance types with the Google Virtual NIC (gVNIC) enabled).

===== Configuring =====

iPXE GCE instances are controlled via an iPXE [[:scripting|script]] stored as instance [[https://cloud.google.com/compute/docs/metadata/overview|metadata]] using the key name ''ipxeboot''.  The iPXE image includes an [[https://github.com/ipxe/ipxe/blob/master/src/config/cloud/gce.ipxe|embedded script]] that will automatically obtain an IP address via DHCP, print out some useful diagnostic information, and then download and execute ''%%http://metadata.google.internal/computeMetadata/v1/instance/attributes/ipxeboot%%''.

You can set the ''ipxeboot'' metadata using the ''%%--metadata-from-file%%'' option when creating the instance.  For example:

    gcloud compute instances create \
           --image-project ipxe-images --image-family ipxe \
           --metadata-from-file=ipxeboot=my-ipxe-boot-script.ipxe \
           ...

You can use this metadata iPXE script to direct the remainder of the network boot process.  For example, to download and boot [[http://tinycorelinux.net/welcome.html|Tiny Core Linux]], you could set your instance's ''ipxeboot'' metadata to contain:

    #!ipxe
    set base http://tinycorelinux.net/12.x/x86/release/distribution_files/
    kernel ${base}/vmlinuz64 initrd=rootfs.gz initrd=modules64.gz
    initrd ${base}/rootfs.gz
    initrd ${base}/modules64.gz
    boot

{{ :screenshots:gce-boot.png?320x232 |GCE iPXE boot}}

Congratulations on successfully booting a Google Cloud instance using iPXE!

{{ :clipart:smile.png?200x200 |Success}}

===== Troubleshooting =====

You can view the iPXE output via the GCE [[https://cloud.google.com/compute/docs/troubleshooting/viewing-serial-port-output|serial port output]].  For example:

    gcloud compute instances get-serial-port-output <name>

You should see output similar to:

    iPXE 1.21.1+ -- Open Source Network Boot Firmware -- https://ipxe.org
    Features: DNS HTTP HTTPS iSCSI TFTP SRP AoE ELF MBOOT PXE bzImage Menu PXEXT
    Google Compute Engine - iPXE boot via metadata
    CPU: GenuineIntel            Intel(R) Xeon(R) CPU @ 2.20GHz
    net0: 42:01:0a:9a:00:25 using gve on 0000:00:04.0 (Ethernet) [closed]
      [Link:down, TX:0 TXE:0 RX:0 RXE:0]
      [Link status: Unknown (https://ipxe.org/1a086101)]
    Waiting for link-up on net0... ok
    Configuring (net0 42:01:0a:9a:00:25)...... ok
    net0: 10.154.0.37/255.255.255.255 gw 10.154.0.1
    net0: fe80::4001:aff:fe9a:25/64
    http://metadata.google.internal/computeMetadata/v1/instance/attributes/ipxeboot... ok

===== Building from source =====

You can build your own version of the public iPXE images using:

    make CONFIG=cloud EMBED=config/cloud/gce.ipxe \
         bin-x86_64-pcbios/ipxe.usb bin-x86_64-efi/ipxe.usb

    make CONFIG=cloud EMBED=config/cloud/gce.ipxe \
         CROSS=aarch64-linux-gnu- bin-arm64-efi/ipxe.usb

and import them using the ''[[https://github.com/ipxe/ipxe/blob/master/contrib/cloud/gce-import|gce-import]]'' tool (found in the ''contrib'' directory in the iPXE source tree).