iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update the GCE Builder Documentation (#9820) 

* update documentation
* add HCL2 examples
This commit is contained in:
Upo 2020-08-25 16:33:02 +01:00 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 Expand all files Collapse all files

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

@ -25,64 +25,80 @@ information.
## Authentication ## Authentication
Authenticating with Google Cloud services requires at most one JSON file, Authenticating with Google Cloud services requires either a User Application Default Credentials
called the _account file_. The _account file_ is **not** required if you are or a JSON Service Account Key. These are **not** required if you are
running the `googlecompute` Packer builder from a GCE instance with a running the `googlecompute` Packer builder on Google Cloud with a
properly-configured [Compute Engine Service properly-configured [Google Service
Account](https://cloud.google.com/compute/docs/authentication). 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 If you run the `googlecompute` Packer builder locally on your workstation, you will
configure that instance to use a [Compute Engine Service 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 Account](https://cloud.google.com/compute/docs/authentication). This will allow
Packer to authenticate to Google Cloud without having to bake in a separate Packer to authenticate to Google Cloud without having to bake in a separate
credential/authentication file. credential/authentication file.
To create a GCE instance that uses a service account, provide the required It is recommended that you create a custom service account for Packer and assign it
scopes when launching the instance. `Compute Instance Admin (v1)` & `Service Account User` roles.
For `gcloud`, do this via the `--scopes` parameter:
For `gcloud`, you can run the following commands:
```shell-session ```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 \ $ gcloud compute instances create INSTANCE-NAME \
--project YOUR_GCP_PROJECT \ --project YOUR_GCP_PROJECT \
--image-family ubuntu-1804-lts \ --image-family ubuntu-2004-lts \
--image-project gce-uefi-images \ --image-project ubuntu-os-cloud \
--network YOUR_GCP_NETWORK \ --network YOUR_GCP_NETWORK \
--zone YOUR_GCP_ZONE \ --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 **The service account will be used automatically by Packer as long as there is
no _account file_ specified in the Packer configuration file.** 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 you to create and download a credential file that will let you use the
`googlecompute` Packer builder anywhere. To make the process more `googlecompute` Packer builder anywhere. To make the process more
straightforwarded, it is documented here. straightforwarded, it is documented here.
1. Log into the [Google Developers 1. Log into the [Google Cloud
Console](https://console.developers.google.com) and select a project. Console](https://console.cloud.google.com/iam-admin/serviceaccounts) and select a project.
2. Under the "API Manager" section, click "Credentials." 2. Click Select a project, choose your project, and click Open.
3. Click the "Create credentials" button, select "Service account key" 3. Click Create Service Account.
4. Create a new service account that at least has 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.
`Compute Engine Instance Admin (v1)` and `Service Account User` roles.
5. Choose `JSON` as the Key type and click "Create". A JSON file will be 5. Generate a JSON Key and save it in a secure location.
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 ### Precedence of Authentication Methods
@ -115,9 +131,7 @@ location found:
Below is a fully functioning example. It doesn't do anything useful since no 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 provisioners or startup-script metadata are defined, but it will effectively
repackage an existing GCE image. The account_file is obtained in the previous repackage an existing GCE image.
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.
<Tabs> <Tabs>
<Tab heading="JSON"> <Tab heading="JSON">
@ -127,9 +141,8 @@ it is assumed to be the path to the file containing the JSON.
"builders": [ "builders": [
{ {
"type": "googlecompute", "type": "googlecompute",
"account_file": "account.json",
"project_id": "my project", "project_id": "my project",
"source_image": "debian-7-wheezy-v20150127", "source_image": "debian-9-stretch-v20200805",
"ssh_username": "packer", "ssh_username": "packer",
"zone": "us-central1-a" "zone": "us-central1-a"
} }
@ -142,9 +155,8 @@ it is assumed to be the path to the file containing the JSON.
```hcl ```hcl
source "googlecompute" "basic-example" { source "googlecompute" "basic-example" {
account_file = "account.json"
project_id = "my project" project_id = "my project"
source_image = "debian-7-wheezy-v20150127" source_image = "debian-9-stretch-v20200805"
ssh_username = "packer" ssh_username = "packer"
zone = "us-central1-a" 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). 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 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 ```json
{ {
"builders": [ "builders": [
{ {
"type": "googlecompute", "type": "googlecompute",
"account_file": "account.json",
"project_id": "my project", "project_id": "my project",
"source_image": "windows-server-2016-dc-v20170227", "source_image": "windows-server-2019-dc-v20200813",
"disk_size": "50", "disk_size": "50",
"machine_type": "n1-standard-1", "machine_type": "n1-standard-2",
"communicator": "winrm", "communicator": "winrm",
"winrm_username": "packer_user", "winrm_username": "packer_user",
"winrm_insecure": true, "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: -> **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/ 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) Instances](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances)
for details. for details.
<Tabs>
<Tab heading="JSON">
```json ```json
{ {
"builders": [ "builders": [
{ {
"type": "googlecompute", "type": "googlecompute",
"account_file": "account.json",
"project_id": "my project", "project_id": "my project",
"source_image_family": "centos-7", "source_image_family": "centos-7",
"ssh_username": "packer", "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 Reference
Configuration options are organized below into two categories: required and 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 `startup_script_file` is set, the `startup-script` `metadata` field will be
overwritten. In other words, `startup_script_file` takes precedence. overwritten. In other words, `startup_script_file` takes precedence.
The builder does not check for a pass/fail/error signal from the startup The builder does check for a pass/fail/error signal from the startup
script, at this time. Until such support is implemented, startup scripts should script by tracking the `startup-script-status` metadata. Packer will check if this key
be robust, as an image will still be built even when a startup script fails. is set to done and if it not set to done before the timeout, Packer will fail the build.
### Windows ### 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 Startup script logs can be copied to a Google Cloud Storage (GCS) location
specified via the `startup-script-log-dest` instance creation `metadata` field. specified via the `startup-script-log-dest` instance creation `metadata` field.
The GCS location must be writeable by the credentials provided in the builder The GCS location must be writeable by the service account of the instance that Packer created.
config's `account_file`.
## Gotchas ## Gotchas