---
description: |
  The googlecompute Packer builder is able to create images for use with Google
  Cloud Compute Engine (GCE) based on existing images.
layout: docs
page_title: Google Compute - Builders
sidebar_title: Google Cloud
---

# Google Compute Builder

Type: `googlecompute`

The `googlecompute` Packer builder is able to create
[images](https://developers.google.com/compute/docs/images) for use with
[Google Compute Engine](https://cloud.google.com/products/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](https://cloud.google.com/compute/docs/tutorials/building-images)
and the [Google Compute Import
Post-Processor](/docs/post-processors/googlecompute-import) for more
information.

## Authentication

Authenticating with Google Cloud services requires either a User Application Default Credentials
or a JSON Service Account Key. These are **not** required if you are
running the `googlecompute` Packer builder on Google Cloud with a
properly-configured [Google Service
Account](https://cloud.google.com/compute/docs/authentication).

### Running locally on your workstation.

If you run the `googlecompute` Packer builder locally on your workstation, you will 
need to install the Google Cloud SDK and authenticate using [User Application Default
Credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default).
You don't need to specify an _account file_ if you are using this method. Your user
must have at least `Compute Instance Admin (v1)` & `Service Account User` roles 
to use Packer succesfully.


### Running on Google Cloud

If you run the `googlecompute` Packer builder on GCE or GKE, you can
configure that instance or cluster to use a [Google Service
Account](https://cloud.google.com/compute/docs/authentication). This will allow
Packer to authenticate to Google Cloud without having to bake in a separate
credential/authentication file.

It is recommended that you create a custom service account for Packer and assign it
 `Compute Instance Admin (v1)` & `Service Account User` roles.

For `gcloud`, you can run the following commands:
```shell-session
$ gcloud iam service-accounts create packer \
  --project YOUR_GCP_PROJECT \
  --description="Packer Service Account" \
  --display-name="Packer Service Account"

$ gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT \
    --member=serviceAccount:packer@YOUR_GCP_PROJECT.iam.gserviceaccount.com \
    --role=roles/compute.instanceAdmin.v1

$ gcloud projects add-iam-policy-binding YOUR_GCP_PROJECT \
    --member=serviceAccount:packer@YOUR_GCP_PROJECT.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountUser

$ gcloud compute instances create INSTANCE-NAME \
  --project YOUR_GCP_PROJECT \
  --image-family ubuntu-2004-lts \
  --image-project ubuntu-os-cloud \
  --network YOUR_GCP_NETWORK \
  --zone YOUR_GCP_ZONE \
  --service-account=packer@YOUR_GCP_PROJECT.iam.gserviceaccount.com \
  --scopes="https://www.googleapis.com/auth/cloud-platform"
```

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

### Running outside of Google Cloud

The [Google Cloud Console](https://console.cloud.google.com) 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.

1.  Log into the [Google Cloud
    Console](https://console.cloud.google.com/iam-admin/serviceaccounts) and select a project.

2.  Click Select a project, choose your project, and click Open.

3.  Click Create Service Account.

4.  Enter a service account name (friendly display name), an optional description, select the `Compute Engine Instance Admin (v1)` and `Service Account User` roles, and then click Save.

5.  Generate a JSON Key and save it in a secure location.

5.  Set the Environment Variable `GOOGLE_APPLICATION_CREDENTIALS` to point to the path of the service account key.

### Precedence of Authentication Methods

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

1.  An `account_file` option in your packer file.

2.  A JSON file (Service Account) whose path is specified by the
    `GOOGLE_APPLICATION_CREDENTIALS` environment variable.

3.  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

4.  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.

<Tabs>
<Tab heading="JSON">

```json
{
  "builders": [
    {
      "type": "googlecompute",
      "project_id": "my project",
      "source_image": "debian-9-stretch-v20200805",
      "ssh_username": "packer",
      "zone": "us-central1-a"
    }
  ]
}
```

</Tab>
<Tab heading="HCL2">

```hcl
source "googlecompute" "basic-example" {
  project_id = "my project"
  source_image = "debian-9-stretch-v20200805"
  ssh_username = "packer"
  zone = "us-central1-a"
}

build {
  sources = ["sources.googlecompute.basic-example"]
}
```

</Tab>
</Tabs>

### 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](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 `project_id`:

<Tabs>
<Tab heading="JSON">

```json
{
  "builders": [
    {
      "type": "googlecompute",
      "project_id": "my project",
      "source_image": "windows-server-2019-dc-v20200813",
      "disk_size": "50",
      "machine_type": "n1-standard-2",
      "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"
    }
  ]
}
```

</Tab>
<Tab heading="HCL2">

```hcl
source "googlecompute" "windows-example" {
  project_id = "MY_PROJECT"
  source_image = "windows-server-2019-dc-v20200813"
  zone = "us-central1-a"
  disk_size = 50,
  machine_type = "n1-standard-2",
  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\"}"
  }
}

build {
  sources = ["sources.googlecompute.windows-example"]
}
```

</Tab>
</Tabs>

-> **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](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances)
for details.

<Tabs>
<Tab heading="JSON">

```json
{
  "builders": [
    {
      "type": "googlecompute",
      "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"]
    }
  ]
}
```

</Tab>
<Tab heading="HCL2">

```hcl
source "googlecompute" "basic-example" {
  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"]
}

build {
  sources = ["sources.googlecompute.basic-example"]
}
```

</Tab>
</Tabs>

### Shared VPC Example

This is an example of using the `network_project_id` configuration option to create
a GCE instance in a Shared VPC Network. See [Creating a GCE Instance using Shared
VPC](https://cloud.google.com/vpc/docs/provisioning-shared-vpc#creating_an_instance_in_a_shared_subnet)
for details. The user/service account running Packer must have `Compute Network User` role on
the Shared VPC Host Project to create the instance in addition to the other roles mentioned in the
Running on Google Cloud section.

<Tabs>
<Tab heading="JSON">

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

</Tab>
<Tab heading="HCL2">

```hcl
source "googlecompute" "sharedvpc-example" {
  project_id = "my project"
  source_image_family = "centos-7"
  subnetwork = "default"
  network_project_id = "SHARED_VPC_PROJECT"
  ssh_username = "packer"
  zone = "us-central1-a"
  image_licenses = ["projects/vm-options/global/licenses/enable-vmx"]
}

build {
  sources = ["sources.googlecompute.sharedvpc-example"]
}
```

</Tab>
</Tabs>

## 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](/docs/templates/communicator) can be configured for this
builder.

### Communicator Configuration

#### Optional:

@include 'helper/communicator/Config-not-required.mdx'

@include 'helper/communicator/SSH-not-required.mdx'

@include 'helper/communicator/SSH-Private-Key-File-not-required.mdx'

### Required:

@include 'builder/googlecompute/Config-required.mdx'

### Optional:

@include 'builder/googlecompute/Config-not-required.mdx'

@include 'builder/googlecompute/IAPConfig-not-required.mdx'

### 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 check for a pass/fail/error signal from the startup
script by tracking the `startup-script-status` metadata. Packer will check if this key
is set to done and if it not set to done before the timeout, Packer will fail the build.

### 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 service account of the instance that Packer created.

### Temporary SSH keypair

@include 'helper/communicator/SSHTemporaryKeyPair.mdx'

#### Optional:

@include 'helper/communicator/SSHTemporaryKeyPair-not-required.mdx'


### 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.