Securely boot a VM

Secure boot helps to ensure that the system runs only authentic software by verifying the digital signature of all boot components, and stopping the boot process if signature verification fails.

The Unified Extensible Firmware Interface (UEFI) firmware securely manages the certificates that contain the keys the software manufacturers use to sign the system firmware, the system boot loader, and any binaries they load. To see the UEFI documentation, visit https://uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf.

On each boot, the UEFI firmware verifies the digital signature of each boot component against the secure store of approved keys. Any boot component that you do not sign properly, or you do not sign at all, isn't allowed to run. You must set the bootloader type of the virtual machine (VM) to uefi to enable a secure boot.

Before you begin

To use gdcloud command-line interface (CLI) commands, ensure that you have downloaded, installed, and configured the gdcloud CLI. All commands for Distributed Cloud use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

Get the kubeconfig file path

To run commands against the org admin cluster, ensure you have the following resources:

  1. Locate the org admin cluster name, or ask your Platform Administrator (PA) what the cluster name is.

  2. Sign in and generate the kubeconfig file for the org admin cluster if you don't have one.

  3. Use the path to the kubeconfig file of the org admin cluster to replace ORG_ADMIN_KUBECONFIG in these instructions.

Request permissions and access

To perform the tasks listed in this page, you must have the Project VirtualMachine Admin role. Follow the steps to verify that you have the Project VirtualMachine Admin (project-vm-admin) role in the namespace of the project where the VM resides.

Enable secure boot

Enable secure boot for a VM. Use the following instructions for a VM called VM_NAME in the project's namespace (PROJECT_NAMESPACE).

  1. Run the following command:

    kubectl --kubeconfig ORG_ADMIN_KUBECONFIG patch virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE --type merge --patch $'
    spec:
       firmware:
          type: uefi
          enableSecureBoot: true
    '
    
    1. If the VM is running, restart it using the instructions to restart a VM.
    2. Verify that you've enabled SecureBoot. SSH into the VM and run the following command:

       mokutil --sb-state
       ```
      

    If you've successfully enabled SecureBoot, the command returns SecureBoot enabled.

    If the mokutil tool reports that you have not enabled SecureBoot, follow these steps:

    1. Run the following command:

       kubectl --kubeconfig ORG_ADMIN_KUBECONFIG edit virtualmachines.virtualmachine.gdc.goog VM_NAME -n PROJECT_NAMESPACE
       ```
      
    2. Look for missing fields or values as shown in the spec field in "Run the following command". These are required.

    3. If any are missing or are incorrect, edit spec to add the missing fields and correct erroneous values.

    4. Save the file.

    5. Follow the steps in Restart the VM.

    If the previous steps don't resolve your issue, check the documentation corresponding to the VM's operating system (OS) to verify that the OS version supports the secure boot.