Creating machine images

Use a machine image to store all the configuration, metadata, permissions, and data from one or more disks for a VM instance running on Compute Engine. The VM instance that you use to create a machine image is referred to as a source instance.

For information about when and how to use machine images, see Machine images.

This page covers the steps for creating a machine image from a source instance.

Before you begin

Limitations and restrictions

Creating a machine image from an instance

You can create machine images using either the Google Cloud Console, the gcloud command-line tool, or the Compute Engine API.

To create a machine image, you need the following information:

  • A name for the machine image that you want to create.
  • The name of the source instance.
  • The zone that the source instance is located in.
  • An optional description.
  • An optional storageLocation. If you do not specify a location, the default storage location is the multiregional Cloud Storage location of the source instance.
  • An optional encryption key. You can choose between a Google-managed key, a Cloud Key Management Service (Cloud KMS) key or a customer-supplied encryption (CSEK) key. If no encryption key is specified, machine images are encrypted using a Google-managed key.
  • If you want to use a machine image for instance cloning and replication, remove the OS and app information that is unique to the instance before generating the machine image from an instance. For example, for Windows VM instances, use GCESysprep to prepare the system for replication.

console

  1. In the Google Cloud Console, go to the Machine images page.

    Go to the Machine images page

  2. Click Create Machine image.
  3. Specify a Name for your machine image.
  4. (Optional) Provide a Description.
  5. Select the Source VM instance.
  6. (Optional) Specify where to store the machine image. Choose between Multi-regional or Regional storage. For more information about location, see Machine image storage location.
  7. (Optional) Select an Encryption method.
  8. Click Create.

gcloud

Use the gcloud beta compute machine-images create command to create a machine image from an instance.

gcloud beta compute machine-images create MACHINE_IMAGE_NAME \
    --source-instance SOURCE_INSTANCE_NAME

Replace the following:

  • MACHINE_IMAGE_NAME: The name of the machine image that you want to create.
  • SOURCE_INSTANCE_NAME: The name of the source instance that you want to create the image from.

Example

For example, you can use the following gcloud command to create a machine image called my-machine-image from a source instance called my-instance:

gcloud beta compute machine-images create my-machine-image  \
    --source-instance my-instance

The process takes a few minutes. When the machine image is created, you get an output that resembles the following:

Created [https://www.googleapis.com/compute/beta/projects/project-12345/global/machineImages/my-machine-image].
NAME               STATUS
my-machine-image   READY

API

In the API, construct a POST request to the machineimages.insert method. In the request body, include the following POST request:

POST https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/machineImages

{
  "name": "MACHINE_IMAGE_NAME",
  "sourceInstance": "SOURCE_INSTANCE_URL"
}

Replace the following:

  • PROJECT_ID: Your project ID.
  • MACHINE_IMAGE_NAME: The name of the machine image that you want to create.
  • SOURCE_INSTANCE_URL: The full or partial URL of the source instance that you want to use to create the machine image. For example, if you have a source instance called my-instance in a project called myProject. The following URLs are valid:

    • https://www.googleapis.com/compute/v1/projects/myProject/global/instances/my-instance
    • projects/myProject/global/instances/my-instance
    • global/instances/my-instance

Creating a machine image from a virtual appliance

Enable the Cloud Build API

In most cases, gcloud beta compute machine-images import attempts to grant these permissions to the Cloud Build service account. However, you can manually grant these permissions to ensure that the required permissions are in effect.

Console

  1. Enable the Cloud Build API.

    Enable the Cloud Build API

    When you enable the Cloud Build API from the console, Compute Engine grants the Cloud Build service account the following roles so that the Cloud Build service can import instances into Compute Engine:

    • roles/iam.serviceAccountTokenCreator
    • roles/compute.admin
    • roles/iam.serviceAccountUser

    The import tool also uses the default Compute Engine service account. By default, the Compute Engine service account has the IAM project editor role. If this role is removed, the import process might fail. To add the role back to the service account, see Granting access. For more information about the Compute Engine default service account, see Compute Engine default service account.

gcloud

To set up the Cloud Build service using gcloud command-line tool, complete the following steps:

  1. Enable Cloud Build.

    gcloud services enable cloudbuild.googleapis.com

    The import tool also uses the default Compute Engine service account. By default, the Compute Engine service account has the IAM project editor role. If this role is removed, the import process might fail. To add the role back to the service account, see Granting access. For more information about the Compute Engine default service account, see Compute Engine default service account.

  2. Add the compute.admin role to the service account for the Cloud Build API.

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
       --role roles/compute.admin
    
  3. Add the iam.serviceAccountUser role to the service account for the Cloud Build API.

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
       --role roles/iam.serviceAccountUser
    
  4. Add the iam.serviceAccountTokenCreator role to the service account for the Cloud Build API.

    gcloud projects add-iam-policy-binding PROJECT_ID \
       --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
       --role roles/iam.serviceAccountTokenCreator
    

    Replace the following:

Review operating system support and requirements

Creating a machine image from a virtual appliance

You can create machine images from virtual appliances using either the gcloud command-line tool, or the Compute Engine API.

Before you can import a virtual appliance, you need to complete the following steps:

gcloud

Use the gcloud beta compute machine-images import command to create a machine image from virtual appliances.

gcloud beta compute machine-images import MACHINE_IMAGE_NAME \
    --source-uri=gs:PATH_TO_VIRTUAL_APPLIANCE_FILE
    --os=OS

Replace the following:

  • MACHINE_IMAGE_NAME: The name of the machine image that you want to create.
  • PATH_TO_VIRTUAL_APPLIANCE_FILE: The path to your OVA or OVF file on Cloud Storage.
  • OS: The operating system of the OVA file. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag.

Example

For example, you can use the following gcloud command to create a machine image called my-machine-image from a source OVA file called my-ova that is stored in the gs://my-bucket directory and runs centos-7:

gcloud beta compute machine-images import my-machine-image  \
    --source-uri=gs://my-bucket/my-ova/ \
    --os=centos-7

API

  1. Upload the virtual appliance to Cloud Storage.

  2. In the API, create a POST request to the Cloud Build API.

    POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
    {
     "timeout":"TIMEOUT",
     "steps":[
       {
         "args":[
           "-machine-image-name=MACHINE_IMAGE_NAME",
           "-ovf-gcs-path=SOURCE_URI",
           "-os=OS",
           "-client-id=api",
           "-timeout=TIMEOUT"
         ],
         "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
         "env":[
           "BUILD_ID=$BUILD_ID"
         ]
       }
     ],
     "tags":"gce-ovf-machine-image-import"
    }
    

    Replace the following:

    • PROJECT_ID: The project ID for the project that you want to import the OVA file into.
    • TIMEOUT: The maximum time a build should last before it fails with a TIMEOUT message. In the API, the time must be specified in seconds. A timeout value of 7200s should work for most scenarios.
    • MACHINE_IMAGE_NAME: The name for the machine image to create. For example, my-machine-image.
    • SOURCE_URI: The URI for the OVA file or a directory containing OVF packages that is stored in Cloud Storage. For example, gs://my-bucket/my-instance.ova.
    • OS: The operating system of the OVA file. For example, ubuntu-1604. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag.

    For additional args values that can be provided, see the optional flags section of the Compute Engine OVF import GitHub page.

Creating machine images with OVF overrides

Custom CPU and memory

gcloud

To override the CPU or memory configuration specified in the OVF file, follow the gcloud command-line tool steps to create a machine image from a virtual appliance and specify the --custom-cpu and --custom-memory flags.

Example

For example, to create a machine image named my-machine-image that has the following overrides applied to the settings in the OVF file:

  • Operating system: Ubuntu 1404
  • CPU: 2 CPUs
  • Memory: 2048 MB

Run the following command:

gcloud beta compute machine-images import my-machine-image \
    --os=ubuntu-1404 --source-uri=gs://my-bucket/Ubuntu.ova \
    --custom-cpu=2 --custom-memory=2048MB

API

To override the CPU or memory configuration specified in the OVF file, follow the Compute Engine API steps to create a machine image from a virtual appliance and specify the -machine-type argument. This -machine-type represents a predefined or custom machine type to use.

Example

For example, to create a machine image named my-machine-image that has the following overrides applied to the settings in the OVF file:

  • Operating system: Ubuntu 1404
  • CPU: 2 CPUs
  • Memory: 2048 MB

Make the following request to the Compute Engine API. Replace PROJECT_ID with your project ID.

{
  "timeout":"7200s",
  "steps":[
    {
      "args":[
        "-machine-image-name=my-machine-image",
        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
        "-os=ubuntu-1404",
        "-machine-type=custom-2-2048",
        "-client-id=api",
        "-timeout=7056s"
      ],
      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
      "env":[
        "BUILD_ID=$BUILD_ID"
      ]
    }
  ],
  "tags":"gce-ovf-machine-image-import"
}

Custom networks

gcloud

To set up a custom network, follow the gcloud command-line tool steps to to create a machine image from a virtual appliance and specify a --network flag. If the network is configured with a custom subnet mode, you must also specify --subnet and --zone flags.

Example

For example, to create a machine image named my-machine-image that has the following overrides applied to the settings in the OVF file:

  • Operating system: Ubuntu 1404
  • Network: custom-vpc-network
  • Subnet: company-vpc-us-east1-c
  • Zone: us-east1-c

Run the following command:

gcloud beta compute machine-images import my-machine-image \
    --os ubuntu-1404 \
    --source-uri=gs://my-bucket/Ubuntu.ova \
    --network custom-vpc-network \
    --subnet company-vpc-us-east1-c \
    --zone us-east1-c

API

To use a custom network, follow the Compute Engine API steps to to create a machine image from a virtual appliance and specify a -network argument. If the network is configured with a custom subnet mode, you must also specify -subnet and -zone arguments.

Example

For example, to create a machine image named my-machine-image that has the following overrides applied to the settings in the OVF file:

  • Operating system: Ubuntu 1404
  • Network: custom-vpc-network
  • Subnet: company-vpc-us-east1-c
  • Zone: us-central1-c

Make the following request to the Compute Engine API. Replace PROJECT_ID with your project ID.

POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
{
  "timeout":"7200s",
  "steps":[
    {
      "args":[
        "-machine-image-name=my-machine-image",
        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
        "-os=ubuntu-1404",
        "-zone=us-central1-c",
        "-network=custom-vpc-network",
        "-subnet=company-vpc-us-east1-c",
        "-client-id=api",
        "-timeout=7056s"
      ],
      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
      "env":[
        "BUILD_ID=$BUILD_ID"
      ]
    }
  ],
  "tags":"gce-ovf-machine-image-import"
}

What's next?