Google Compute Builder

Type: googlecompute

The googlecompute Packer builder is able to create images for use with Google Compute Engine (GCE) based on existing images.

It is possible to build images from scratch, but not with the googlecompute Packer builder. The process is recommended only for advanced users, please see Building GCE Images from Scratch and the Google Compute Import Post-Processor for more information.

Authentication

Authenticating with Google Cloud services requires at most one JSON file, called the account file. The account file is not required if you are running the googlecompute Packer builder from a GCE instance with a properly-configured Compute Engine Service Account.

Running With a Compute Engine Service Account

If you run the googlecompute Packer builder from a GCE instance, you can configure that instance to use a Compute Engine Service Account. This will allow Packer to authenticate to Google Cloud without having to bake in a separate credential/authentication file.

To create a GCE instance that uses a service account, provide the required scopes when launching the instance.

For gcloud, do this via the --scopes parameter:

$ gcloud compute instances create INSTANCE-NAME \
  --project YOUR_GCP_PROJECT \
  --image-family ubuntu-1804-lts \
  --image-project gce-uefi-images \
  --network YOUR_GCP_NETWORK \
  --zone YOUR_GCP_ZONE \
  --scopes "https://www.googleapis.com/auth/compute,https://www.googleapis.com/auth/devstorage.full_control"

For the Google Developers Console:

Choose "Show advanced options"
Tick "Enable Compute Engine service account"
Choose "Read Write" for Compute
Choose "Full" for "Storage"

The service account will be used automatically by Packer as long as there is no account file specified in the Packer configuration file.

Running Without a Compute Engine Service Account

The Google Developers Console allows you to create and download a credential file that will let you use the googlecompute Packer builder anywhere. To make the process more straightforwarded, it is documented here.

Log into the Google Developers Console and select a project.
Under the "API Manager" section, click "Credentials."
Click the "Create credentials" button, select "Service account key"
Create a new service account that at least has Compute Engine Instance Admin (v1) and Service Account User roles.
Choose JSON as the Key type and click "Create". A JSON file will be downloaded automatically. This is your account file.

Precedence of Authentication Methods

Packer looks for credentials in the following places, preferring the first location found:

An account_file option in your packer file.
A JSON file (Service Account) whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
A JSON file in a location known to the gcloud command-line tool. (gcloud auth application-default login creates it)
On Windows, this is:
```
%APPDATA%/gcloud/application_default_credentials.json
```
On other systems:
```
$HOME/.config/gcloud/application_default_credentials.json
```
On Google Compute Engine and Google App Engine Managed VMs, it fetches credentials from the metadata server. (Needs a correct VM authentication scope configuration, see above.)

Examples

Basic Example

Below is a fully functioning example. It doesn't do anything useful since no provisioners or startup-script metadata are defined, but it will effectively repackage an existing GCE image. The account_file is obtained in the previous section. If it parses as JSON it is assumed to be the file itself, otherwise, it is assumed to be the path to the file containing the JSON.

{
  "builders": [
    {
      "type": "googlecompute",
      "account_file": "account.json",
      "project_id": "my project",
      "source_image": "debian-7-wheezy-v20150127",
      "ssh_username": "packer",
      "zone": "us-central1-a"
    }
  ]
}

Windows Example

Before you can provision using the winrm communicator, you need to allow traffic through google's firewall on the winrm port (tcp:5986). You can do so using the gcloud command.

gcloud compute firewall-rules create allow-winrm --allow tcp:5986

Or alternatively by navigating to https://console.cloud.google.com/networking/firewalls/list.

Once this is set up, the following is a complete working packer config after setting a valid account_file and project_id:

{
  "builders": [
    {
      "type": "googlecompute",
      "account_file": "account.json",
      "project_id": "my project",
      "source_image": "windows-server-2016-dc-v20170227",
      "disk_size": "50",
      "machine_type": "n1-standard-1",
      "communicator": "winrm",
      "winrm_username": "packer_user",
      "winrm_insecure": true,
      "winrm_use_ssl": true,
      "metadata": {
        "windows-startup-script-cmd": "winrm quickconfig -quiet & net user /add packer_user & net localgroup administrators packer_user /add & winrm set winrm/config/service/auth @{Basic=\"true\"}"
      },
      "zone": "us-central1-a"
    }
  ]
}

Warning: Please note that if you're setting up WinRM for provisioning, you'll probably want to turn it off or restrict its permissions as part of a shutdown script at the end of Packer's provisioning process. For more details on the why/how, check out this useful blog post and the associated code: https://cloudywindows.io/post/winrm-for-provisioning-close-the-door-on-the-way-out-eh/

This build can take up to 15 min.

Nested Hypervisor Example

This is an example of using the image_licenses configuration option to create a GCE image that has nested virtualization enabled. See Enabling Nested Virtualization for VM Instances for details.

{
  "builders": [
    {
      "type": "googlecompute",
      "account_file": "account.json",
      "project_id": "my project",
      "source_image_family": "centos-7",
      "ssh_username": "packer",
      "zone": "us-central1-a",
      "image_licenses": ["projects/vm-options/global/licenses/enable-vmx"]
    }
  ]
}

Configuration Reference

Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described.

In addition to the options listed here, a communicator can be configured for this builder.

Required:

project_id (string) - The project ID that will be used to launch instances and store images.
source_image (string) - The source image to use to create the new image from. You can also specify source_image_family instead. If both source_image and source_image_family are specified, source_image takes precedence. Example: "debian-8-jessie-v20161027"
source_image_family (string) - The source image family to use to create the new image from. The image family always returns its latest image that is not deprecated. Example: "debian-8".
zone (string) - The zone in which to launch the instance used to create the image. Example: "us-central1-a"

Optional:

account_file (string) - The JSON file containing your account credentials. Not required if you run Packer on a GCE instance with a service account. Instructions for creating the file or using service accounts are above.
accelerator_type (string) - Full or partial URL of the guest accelerator type. GPU accelerators can only be used with "on_host_maintenance": "TERMINATE" option set. Example: "projects/project_id/zones/europe-west1-b/acceleratorTypes/nvidia-tesla-k80"
accelerator_count (int64) - Number of guest accelerator cards to add to the launched instance.
address (string) - The name of a pre-allocated static external IP address. Note, must be the name and not the actual IP address.
disable_default_service_account (bool) - If true, the default service account will not be used if service_account_email is not specified. Set this value to true and omit service_account_email to provision a VM with no service account.
disk_name (string) - The name of the disk, if unset the instance name will be used.
disk_size (int64) - The size of the disk in GB. This defaults to 10, which is 10GB.
disk_type (string) - Type of disk used to back your instance, like pd-ssd or pd-standard. Defaults to pd-standard.
enable_secure_boot (bool) - Create a Shielded VM image with Secure Boot enabled. It helps ensure that the system only runs authentic software by verifying the digital signature of all boot components, and halting the boot process if signature verification fails. Details
enable_vtpm (bool) - Create a Shielded VM image with virtual trusted platform module Measured Boot enabled. A vTPM is a virtualized trusted platform module, which is a specialized computer chip you can use to protect objects, like keys and certificates, that you use to authenticate access to your system. Details
enable_integrity_monitoring (bool) - Integrity monitoring helps you understand and make decisions about the state of your VM instances. Note: integrity monitoring relies on having vTPM enabled. Details
image_name (string) - The unique name of the resulting image. Defaults to packer-{{timestamp}}.
image_description (string) - The description of the resulting image.
image_encryption_key (*CustomerEncryptionKey) - Image encryption key to apply to the created image. Possible values:
- kmsKeyName - The name of the encryption key that is stored in Google Cloud KMS.
- RawKey: - A 256-bit customer-supplied encryption key, encodes in RFC 4648 base64.
example:
```
{
   "kmsKeyName": "projects/${project}/locations/${region}/keyRings/computeEngine/cryptoKeys/computeEngine/cryptoKeyVersions/4"
}
```
image_family (string) - The name of the image family to which the resulting image belongs. You can create disks by specifying an image family instead of a specific image name. The image family always returns its latest image that is not deprecated.
image_labels (map[string]string) - Key/value pair labels to apply to the created image.
image_licenses ([]string) - Licenses to apply to the created image.
instance_name (string) - A name to give the launched instance. Beware that this must be unique. Defaults to packer-{{uuid}}.
labels (map[string]string) - Key/value pair labels to apply to the launched instance.
machine_type (string) - The machine type. Defaults to "n1-standard-1".
metadata (map[string]string) - Metadata applied to the launched instance.
metadata_files (map[string]string) - Metadata applied to the launched instance. Values are files.
min_cpu_platform (string) - A Minimum CPU Platform for VM Instance. Availability and default CPU platforms vary across zones, based on the hardware available in each GCP zone. Details
network (string) - The Google Compute network id or URL to use for the launched instance. Defaults to "default". If the value is not a URL, it will be interpolated to projects/((network_project_id))/global/networks/((network)). This value is not required if a subnet is specified.
network_project_id (string) - The project ID for the network and subnetwork to use for launched instance. Defaults to project_id.
omit_external_ip (bool) - If true, the instance will not have an external IP. use_internal_ip must be true if this property is true.
on_host_maintenance (string) - Sets Host Maintenance Option. Valid choices are MIGRATE and TERMINATE. Please see GCE Instance Scheduling Options, as not all machine_types support MIGRATE (i.e. machines with GPUs). If preemptible is true this can only be TERMINATE. If preemptible is false, it defaults to MIGRATE
preemptible (bool) - If true, launch a preemptible instance.
state_timeout (duration string | ex: "1h5m2s") - The time to wait for instance state changes. Defaults to "5m".
region (string) - The region in which to launch the instance. Defaults to the region hosting the specified zone.

scopes ([]string) - The service account scopes for launched instance. Defaults to:

[
  "https://www.googleapis.com/auth/userinfo.email",
  "https://www.googleapis.com/auth/compute",
  "https://www.googleapis.com/auth/devstorage.full_control"
]

service_account_email (string) - The service account to be used for launched instance. Defaults to the project's default service account unless disable_default_service_account is true.
source_image_project_id ([]string) - A list of project IDs to search for the source image. Packer will search the first project ID in the list first, and fall back to the next in the list, until it finds the source image.
startup_script_file (string) - The path to a startup script to run on the VM from which the image will be made.
subnetwork (string) - The Google Compute subnetwork id or URL to use for the launched instance. Only required if the network has been created with custom subnetting. Note, the region of the subnetwork must match the region or zone in which the VM is launched. If the value is not a URL, it will be interpolated to projects/((network_project_id))/regions/((region))/subnetworks/((subnetwork))
tags ([]string) - Assign network tags to apply firewall rules to VM instance.
use_internal_ip (bool) - If true, use the instance's internal IP instead of its external IP during building.
vault_gcp_oauth_engine (string) - Can be set instead of account_file. If set, this builder will use HashiCorp Vault to generate an Oauth token for authenticating against Google's cloud. The value should be the path of the token generator within vault. For information on how to configure your Vault + GCP engine to produce Oauth tokens, see https://www.vaultproject.io/docs/auth/gcp You must have the environment variables VAULT_ADDR and VAULT_TOKEN set, along with any other relevant variables for accessing your vault instance. For more information, see the Vault docs: https://www.vaultproject.io/docs/commands/#environment-variables Example:"vault_gcp_oauth_engine": "gcp/token/my-project-editor",

Startup Scripts

Startup scripts can be a powerful tool for configuring the instance from which the image is made. The builder will wait for a startup script to terminate. A startup script can be provided via the startup_script_file or startup-script instance creation metadata field. Therefore, the build time will vary depending on the duration of the startup script. If startup_script_file is set, the startup-script metadata field will be overwritten. In other words, startup_script_file takes precedence.

The builder does not check for a pass/fail/error signal from the startup script, at this time. Until such support is implemented, startup scripts should be robust, as an image will still be built even when a startup script fails.

Windows

A Windows startup script can only be provided via the windows-startup-script-cmd instance creation metadata field. The builder will not wait for a Windows startup script to terminate. You have to ensure that it finishes before the instance shuts down.

Logging

Startup script logs can be copied to a Google Cloud Storage (GCS) location specified via the startup-script-log-dest instance creation metadata field. The GCS location must be writeable by the credentials provided in the builder config's account_file.

Gotchas

CentOS and recent Debian images have root ssh access disabled by default. Set ssh_username to any user, which will be created by packer with sudo access.

The machine type must have a scratch disk, which means you can't use an f1-micro or g1-small to build images.