412 lines
13 KiB
Plaintext
412 lines
13 KiB
Plaintext
---
|
|
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.
|