aherman
/
packer
mirror of https://github.com/hashicorp/packer
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the GCE Builder Documentation (#9820)

Browse Source 
* update documentation
* add HCL2 examples
pull/9824/head
Upo 6 years ago committed by GitHub
parent 0d0bd9ce75
commit 3506b8876f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 161 additions and 48 deletions
Show Stats Download Patch File Download Diff File

209
website/pages/docs/builders/googlecompute.mdx
Unescape View File

@ -25,64 +25,80 @@ 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
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 With a Compute Engine Service Account
### Running locally on your workstation.
If you run the `googlecompute` Packer builder from a GCE instance, you can
configure that instance to use a [Compute Engine Service
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.
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:
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-1804-lts \
--image-project gce-uefi-images \
--image-family ubuntu-2004-lts \
--image-project ubuntu-os-cloud \
--network YOUR_GCP_NETWORK \
--zone YOUR_GCP_ZONE \
--scopes "https://www.googleapis.com/auth/compute,https://www.googleapis.com/auth/devstorage.full_control"
--service-account=packer@YOUR_GCP_PROJECT.iam.gserviceaccount.com \
--scopes="https://www.googleapis.com/auth/cloud-platform"
```
For the [Google Developers Console](https://console.developers.google.com):
1. Choose "Show advanced options"
2. Tick "Enable Compute Engine service account"
3. Choose "Read Write" for Compute
4. 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
### Running outside of Google Cloud
The [Google Developers Console](https://console.developers.google.com) allows
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 Developers
Console](https://console.developers.google.com) and select a project.
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.
2. Under the "API Manager" section, click "Credentials."
3. Click Create Service Account.
3. Click the "Create credentials" button, select "Service account key"
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.
4. Create a new service account that at least has
`Compute Engine Instance Admin (v1)` and `Service Account User` roles.
5. Generate a JSON Key and save it in a secure location.
5. Choose `JSON` as the Key type and click "Create". A JSON file will be
downloaded automatically. This is your _account file_.
5. Set the Environment Variable `GOOGLE_APPLICATION_CREDENTIALS` to point to the path of the service account key.
### Precedence of Authentication Methods
@ -115,9 +131,7 @@ location found:
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.
repackage an existing GCE image.
<Tabs>
<Tab heading="JSON">
@ -127,9 +141,8 @@ 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",
"source_image": "debian-9-stretch-v20200805",
"ssh_username": "packer",
"zone": "us-central1-a"
}
@ -142,9 +155,8 @@ it is assumed to be the path to the file containing the JSON.
```hcl
source "googlecompute" "basic-example" {
account_file = "account.json"
project_id = "my project"
source_image = "debian-7-wheezy-v20150127"
source_image = "debian-9-stretch-v20200805"
ssh_username = "packer"
zone = "us-central1-a"
}
@ -168,18 +180,20 @@ using the gcloud command.
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 `account_file` and `project_id`:
setting a valid `project_id`:
<Tabs>
<Tab heading="JSON">
```json
{
"builders": [
{
"type": "googlecompute",
"account_file": "account.json",
"project_id": "my project",
"source_image": "windows-server-2016-dc-v20170227",
"source_image": "windows-server-2019-dc-v20200813",
"disk_size": "50",
"machine_type": "n1-standard-1",
"machine_type": "n1-standard-2",
"communicator": "winrm",
"winrm_username": "packer_user",
"winrm_insecure": true,
@ -193,6 +207,33 @@ setting a valid `account_file` and `project_id`:
}
```
</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/
@ -206,12 +247,14 @@ 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",
"account_file": "account.json",
"project_id": "my project",
"source_image_family": "centos-7",
"ssh_username": "packer",
@ -222,6 +265,77 @@ for details.
}
```
</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
@ -252,9 +366,9 @@ 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.
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
@ -267,8 +381,7 @@ that it finishes before the instance shuts down.
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`.
The GCS location must be writeable by the service account of the instance that Packer created.
## Gotchas

Write Preview
Loading…
Cancel
Save