View and append licenses


This document shows you how to view the licenses that are associated with a virtual machine (VM) instance, append licenses to a VM, and view the history of license updates. For more information about licenses on Compute Engine, see About licenses.

Before you begin

  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

View the licenses associated with a VM

To view the licenses associated with a VM, use the Google Cloud console, gcloud CLI, or the Compute Engine API.

Console

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Click the name of the VM to check the license of. The Instance detail page opens.

  3. At the bottom of the Instance detail page, click Equivalent REST.

  4. View the licenses field for the boot disk.

gcloud

  1. Run the following gcloud compute instances describe command:

    gcloud compute instances describe VM_NAME
    

    Replace VM_NAME with the name of your VM.

  2. View the disks section of the output. The licenses field shows the licenses associated with the boot disk.

REST

  1. Call the following instances.get v1 method:

    GET https://compute.googleapis.com/compute/v1/projects/PROJECT/zones/ZONE/instances/VM_NAME
    

    Replace the following:

    • PROJECT: the name of the project
    • ZONE: the zone containing the VM
    • VM_NAME: the name of the VM
  2. The Compute Engine API returns the licenses associated with the boot disk in the disks section of the licenses field.

View the user licenses associated with a VM

To view the user licenses associated with a VM, use the Google Cloud console, gcloud CLI, or the Compute Engine API.

Console

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Click the name of the VM to check the user licenses of. The Instance detail page opens.

  3. At the bottom of the Instance detail page, click Equivalent REST.

  4. View the userLicenses field for the boot disk.

gcloud

  1. Run the following gcloud beta compute instances describe command:

    gcloud beta compute instances describe VM_NAME
    

    Replace VM_NAME with the name of your VM.

  2. View the disks section of the output. The licenses field shows the licenses associated with the boot disk.

REST

  1. Call the following instances.get beta method:

    GET https://compute.googleapis.com/compute/beta/projects/PROJECT/zones/ZONE/instances/VM_NAME
    

    Replace the following:

    • PROJECT: the name of the project
    • ZONE: the zone containing the VM
    • VM_NAME: the name of the VM
  2. The Compute Engine API returns the licenses associated with the boot disk in the disks section of the licenses field.

Append a license when importing an image

To append a license when importing an image, use the following gcloud compute images import command.

gcloud compute images import IMAGE_NAME \
  --source-file=SOURCE_FILE
  --os=OS

Replace the following:

  • IMAGE_NAME: the name of the image to create.
  • SOURCE_FILE: a local file or Cloud Storage URI of the virtual disk to import.
  • OS: the OS of the disk image to import. The license for the OS is inferred from the value of this flag; there isn't an explicit flag to provide license information when importing. For a list of the supported values, see --os flag.

For more information about importing images, see Importing virtual disks.

Append licenses when creating an image

To append licenses when creating an image, use the following gcloud compute images create command.

gcloud compute images create IMAGE_NAME \
  --source-image=SOURCE_IMAGE \
  --licenses=LICENSES

Replace the following:

  • IMAGE_NAME: the name of the image to create.
  • SOURCE_IMAGE: the name of the image to create the new image from.
  • LICENSES: a comma-separated list of license strings. For example, "license1", "license2".

For more information about creating images, see Creating, deleting, and deprecating custom images, and Creating a Windows image.

Append licenses and user licenses when creating an image

To append licenses and user licenses when creating an image, use the following gcloud beta compute images create command.

gcloud beta compute images create IMAGE_NAME \
  --source-image=SOURCE_IMAGE \
  --licenses=LICENSES \
  --user-licenses=USER_LICENSES

Replace the following:

  • IMAGE_NAME: the name of the image to create.
  • SOURCE_IMAGE: the name of the image to create the new image from.
  • LICENSES: a comma-separated list of license strings. For example, "license1", "license2".
  • USER_LICENSES: a comma-separated list of user license strings. For example, "userlicense1", "userlicense2".

For more information about creating images, see Creating, deleting, and deprecating custom images, and Creating a Windows image.

Append and validate a user license

To append and validate a user license, do the following:

  1. Stop the VM.

  2. List the disks associated with the VM by using the gcloud compute instances describe command:

    gcloud compute instances describe VM_NAME --format="yaml(disks)"
    
  3. Verify that the output is similar to the following:

    disks:
    - autoDelete: true
      boot: true
      deviceName: BOOT_DISK_NAME
      diskSizeGb: '20'
      guestOsFeatures:
      - type: UEFI_COMPATIBLE
      index: 0
      interface: SCSI
      kind: compute#attachedDisk
      licenses:
      - BOOT_DISK_LICENSE_STRING
      mode: READ_WRITE
      source: https://www.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/disks/BOOT_DISK_NAME
      type: PERSISTENT
    
  4. In the output from the previous step, find the name of the boot disk. For the boot disk, the value of boot is true, and the name of the boot disk is the value of deviceName.

  5. Append a user license to the boot disk by using the gcloud beta compute disks update command:

    gcloud beta compute disks update BOOT_DISK_NAME \
       --update-user-licenses=LICENSE_URIS
    

    Replace the following:

    • BOOT_DISK_NAME: the name of the boot disk to append the license to

    • LICENSE_URIS: a comma-separated list of license strings, which replaces all existing user licenses

  6. Get information about the boot disk by using the gcloud beta compute disks describe command:

    gcloud beta compute disks describe BOOT_DISK_NAME
    

    Replace BOOT_DISK_NAME with the name of the boot disk to check for the appended license.

  7. Verify that the output is similar to the following:

    creationTimestamp: '2021-05-05T15:26:27.835-07:00'
    guestOsFeatures:
    - type: UEFI_COMPATIBLE
    id: '727854272460268924'
    interface: SCSI
    kind: compute#disk
    labelFingerprint: 42WmSpB8rSM=
    lastAttachTimestamp: '2021-05-05T15:26:27.836-07:00'
    licenseCodes:
    - '1000006'
    - '6213885950785916969'
    licenses:
    - BOOT_DISK_LICENSE_STRING
    multiWriter: false
    name: VM_NAME
    physicalBlockSizeBytes: '4096'
    selfLink: https://www.googleapis.com/compute/beta/projects/PROJECT_NAME/zones/ZONE/disks/DISK_NAME
    selfLinkWithId: https://www.googleapis.com/compute/beta/projects/PROJECT_NAME/zones/ZONE/disks/727854272460268924
    sizeGb: '20'
    sourceImage: https://www.googleapis.com/compute/beta/projects/IMAGE_PROJECT/global/images/IMAGE
    sourceImageId: '7397991294075835597'
    status: READY
    type: https://www.googleapis.com/compute/beta/projects/PROJECT_NAME/zones/ZONE/diskTypes/pd-standard
    userLicenses:
    - LICENSE_URI
    users:
    - https://www.googleapis.com/compute/beta/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME
    zone: https://www.googleapis.com/compute/beta/projects/PROJECT_NAME/zones/ZONE
    
  8. Validate that the user license is appended to the boot disk by checking the output of the previous step for the userLicenses field for the appropriate license string.

    If the userLicenses field doesn't contain the intended license strings, you might need to clear and then update the list of license strings. You can do this by using the gcloud beta compute disks update command.

  9. Start the VM.

View the history of license updates

View the history of license updates for VMs in a project by using the following procedure:

  1. In the Google Cloud console, go to the Activity page.

    Go to Activity

  2. In the Filters pane in Categories, for Activity types select Configuration.

  3. In the Filters pane in Categories, for the Resource type select Disk.

What's next