github.com/StackPointCloud/packer@v0.10.2-0.20180716202532-b28098e0f79b/website/source/docs/builders/googlecompute.html.md (about) 1 --- 2 description: | 3 The googlecompute Packer builder is able to create images for use with 4 Google Cloud Compute Engine (GCE) based on existing images. 5 layout: docs 6 page_title: 'Google Compute - Builders' 7 sidebar_current: 'docs-builders-googlecompute' 8 --- 9 10 # Google Compute Builder 11 12 Type: `googlecompute` 13 14 The `googlecompute` Packer builder is able to create 15 [images](https://developers.google.com/compute/docs/images) for use with [Google 16 Compute Engine](https://cloud.google.com/products/compute-engine)(GCE) based on 17 existing images. Building GCE images from scratch is not possible from Packer at 18 this time. For building images from scratch, please see 19 [Building GCE Images from Scratch](https://cloud.google.com/compute/docs/tutorials/building-images). 20 21 ## Authentication 22 23 Authenticating with Google Cloud services requires at most one JSON file, called 24 the *account file*. The *account file* is **not** required if you are running 25 the `googlecompute` Packer builder from a GCE instance with a 26 properly-configured [Compute Engine Service 27 Account](https://cloud.google.com/compute/docs/authentication). 28 29 ### Running With a Compute Engine Service Account 30 31 If you run the `googlecompute` Packer builder from a GCE instance, you can 32 configure that instance to use a [Compute Engine Service 33 Account](https://cloud.google.com/compute/docs/authentication). This will allow 34 Packer to authenticate to Google Cloud without having to bake in a separate 35 credential/authentication file. 36 37 To create a GCE instance that uses a service account, provide the required 38 scopes when launching the instance. 39 40 For `gcloud`, do this via the `--scopes` parameter: 41 42 ``` shell 43 $ gcloud compute --project YOUR_PROJECT instances create "INSTANCE-NAME" ... \ 44 --scopes "https://www.googleapis.com/auth/compute,https://www.googleapis.com/auth/devstorage.full_control" \ 45 ``` 46 47 For the [Google Developers Console](https://console.developers.google.com): 48 49 1. Choose "Show advanced options" 50 2. Tick "Enable Compute Engine service account" 51 3. Choose "Read Write" for Compute 52 4. Chose "Full" for "Storage" 53 54 **The service account will be used automatically by Packer as long as there is 55 no *account file* specified in the Packer configuration file.** 56 57 ### Running Without a Compute Engine Service Account 58 59 The [Google Developers Console](https://console.developers.google.com) allows 60 you to create and download a credential file that will let you use the 61 `googlecompute` Packer builder anywhere. To make the process more 62 straightforwarded, it is documented here. 63 64 1. Log into the [Google Developers 65 Console](https://console.developers.google.com) and select a project. 66 67 2. Under the "API Manager" section, click "Credentials." 68 69 3. Click the "Create credentials" button, select "Service account key" 70 71 4. Create new service account that at least has `Compute Engine Instance Admin (v1)` and `Service Account User` roles. 72 73 5. Choose `JSON` as Key type and click "Create". 74 A JSON file will be downloaded automatically. This is your *account file*. 75 76 ### Precedence of Authentication Methods 77 78 Packer looks for credentials in the following places, preferring the first location found: 79 80 1. A `account_file` option in your packer file. 81 82 2. A JSON file (Service Account) whose path is specified by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. 83 84 3. A JSON file in a location known to the `gcloud` command-line tool. (`gcloud` creates it when it's configured) 85 86 On Windows, this is: 87 88 %APPDATA%/gcloud/application_default_credentials.json 89 90 On other systems: 91 92 $HOME/.config/gcloud/application_default_credentials.json 93 94 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) 95 96 ## Examples 97 98 ### Basic Example 99 100 Below is a fully functioning example. It doesn't do anything useful, since no 101 provisioners or startup-script metadata are defined, but it will effectively 102 repackage an existing GCE image. The account\_file is obtained in the previous 103 section. If it parses as JSON it is assumed to be the file itself, otherwise it 104 is assumed to be the path to the file containing the JSON. 105 106 ``` json 107 { 108 "builders": [ 109 { 110 "type": "googlecompute", 111 "account_file": "account.json", 112 "project_id": "my project", 113 "source_image": "debian-7-wheezy-v20150127", 114 "ssh_username": "packer", 115 "zone": "us-central1-a" 116 } 117 ] 118 } 119 ``` 120 121 ### Windows Example 122 123 Before you can provision using the winrm communicator, you need to navigate to 124 https://console.cloud.google.com/networking/firewalls/list to allow traffic 125 through google's firewall on the winrm port (tcp:5986). 126 127 Once this is set up, the following is a complete working packer config after 128 setting a valid `account_file` and `project_id`: 129 130 ``` {.json} 131 { 132 "builders": [ 133 { 134 "type": "googlecompute", 135 "account_file": "account.json", 136 "project_id": "my project", 137 "source_image": "windows-server-2016-dc-v20170227", 138 "disk_size": "50", 139 "machine_type": "n1-standard-1", 140 "communicator": "winrm", 141 "winrm_username": "packer_user", 142 "winrm_insecure": true, 143 "winrm_use_ssl": true, 144 "metadata": { 145 "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\"}" 146 }, 147 "zone": "us-central1-a" 148 } 149 ] 150 } 151 ``` 152 153 ### Nested Hypervisor Example 154 155 This is an example of using the `image_licenses` configuration option to create a GCE image that has nested virtualization enabled. See 156 [Enabling Nested Virtualization for VM Instances](https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances) 157 for details. 158 159 ``` json 160 { 161 "builders": [ 162 { 163 "type": "googlecompute", 164 "account_file": "account.json", 165 "project_id": "my project", 166 "source_image_family": "centos-7", 167 "ssh_username": "packer", 168 "zone": "us-central1-a", 169 "image_licenses": ["projects/vm-options/global/licenses/enable-vmx"] 170 } 171 ] 172 } 173 ``` 174 175 ## Configuration Reference 176 177 Configuration options are organized below into two categories: required and 178 optional. Within each category, the available options are alphabetized and 179 described. 180 181 In addition to the options listed here, a 182 [communicator](/docs/templates/communicator.html) can be configured for this 183 builder. 184 185 ### Required: 186 187 - `project_id` (string) - The project ID that will be used to launch instances 188 and store images. 189 190 - `source_image` (string) - The source image to use to create the new image 191 from. You can also specify `source_image_family` instead. If both 192 `source_image` and `source_image_family` are specified, `source_image` 193 takes precedence. Example: `"debian-8-jessie-v20161027"` 194 195 - `source_image_family` (string) - The source image family to use to create 196 the new image from. The image family always returns its latest image that 197 is not deprecated. Example: `"debian-8"`. 198 199 - `zone` (string) - The zone in which to launch the instance used to create 200 the image. Example: `"us-central1-a"` 201 202 ### Optional: 203 204 - `account_file` (string) - The JSON file containing your account credentials. 205 Not required if you run Packer on a GCE instance with a service account. 206 Instructions for creating file or using service accounts are above. 207 208 - `accelerator_count` (number) - Number of guest accelerator cards to add to the launched instance. 209 210 - `accelerator_type` (string) - Full or partial URL of the guest accelerator type. GPU accelerators can only be used with 211 `"on_host_maintenance": "TERMINATE"` option set. 212 Example: `"projects/project_id/zones/europe-west1-b/acceleratorTypes/nvidia-tesla-k80"` 213 214 - `address` (string) - The name of a pre-allocated static external IP address. 215 Note, must be the name and not the actual IP address. 216 217 - `disable_default_service_account` (bool) - If true, the default service account will not be used if `service_account_email` 218 is not specified. Set this value to true and omit `service_account_email` to provision a VM with no service account. 219 220 - `disk_name` (string) - The name of the disk, if unset the instance name will be 221 used. 222 223 - `disk_size` (number) - The size of the disk in GB. This defaults to `10`, 224 which is 10GB. 225 226 - `disk_type` (string) - Type of disk used to back your instance, like `pd-ssd` or `pd-standard`. Defaults to `pd-standard`. 227 228 - `image_description` (string) - The description of the resulting image. 229 230 - `image_family` (string) - The name of the image family to which the 231 resulting image belongs. You can create disks by specifying an image family 232 instead of a specific image name. The image family always returns its 233 latest image that is not deprecated. 234 235 - `image_labels` (object of key/value strings) - Key/value pair labels to 236 apply to the created image. 237 238 - `image_licenses` (array of strings) - Licenses to apply to the created image. 239 240 - `image_name` (string) - The unique name of the resulting image. Defaults to 241 `"packer-{{timestamp}}"`. 242 243 - `instance_name` (string) - A name to give the launched instance. Beware that 244 this must be unique. Defaults to `"packer-{{uuid}}"`. 245 246 - `labels` (object of key/value strings) - Key/value pair labels to apply to 247 the launched instance. 248 249 - `machine_type` (string) - The machine type. Defaults to `"n1-standard-1"`. 250 251 - `metadata` (object of key/value strings) - Metadata applied to the launched 252 instance. 253 254 - `network` (string) - The Google Compute network id or URL to use for the 255 launched instance. Defaults to `"default"`. If the value is not a URL, it 256 will be interpolated to `projects/((network_project_id))/global/networks/((network))`. 257 This value is not required if a `subnet` is specified. 258 259 260 - `network_project_id` (string) - The project ID for the network and subnetwork 261 to use for launched instance. Defaults to `project_id`. 262 263 - `omit_external_ip` (boolean) - If true, the instance will not have an external IP. 264 `use_internal_ip` must be true if this property is true. 265 266 - `on_host_maintenance` (string) - Sets Host Maintenance Option. Valid 267 choices are `MIGRATE` and `TERMINATE`. Please see [GCE Instance Scheduling 268 Options](https://cloud.google.com/compute/docs/instances/setting-instance-scheduling-options), 269 as not all machine\_types support `MIGRATE` (i.e. machines with GPUs). 270 If preemptible is true this can only be `TERMINATE`. If preemptible 271 is false, it defaults to `MIGRATE` 272 273 - `preemptible` (boolean) - If true, launch a preemptible instance. 274 275 - `region` (string) - The region in which to launch the instance. Defaults to 276 to the region hosting the specified `zone`. 277 278 - `service_account_email` (string) - The service account to be used for launched instance. Defaults to 279 the project's default service account unless `disable_default_service_account` is true. 280 281 - `scopes` (array of strings) - The service account scopes for launched instance. 282 Defaults to: 283 284 ``` json 285 [ 286 "https://www.googleapis.com/auth/userinfo.email", 287 "https://www.googleapis.com/auth/compute", 288 "https://www.googleapis.com/auth/devstorage.full_control" 289 ] 290 ``` 291 292 - `source_image_project_id` (string) - The project ID of the 293 project containing the source image. 294 295 - `startup_script_file` (string) - The filepath to a startup script to run on 296 the VM from which the image will be made. 297 298 - `state_timeout` (string) - The time to wait for instance state changes. 299 Defaults to `"5m"`. 300 301 - `subnetwork` (string) - The Google Compute subnetwork id or URL to use for 302 the launched instance. Only required if the `network` has been created with 303 custom subnetting. Note, the region of the subnetwork must match the `region` 304 or `zone` in which the VM is launched. If the value is not a URL, it 305 will be interpolated to `projects/((network_project_id))/regions/((region))/subnetworks/((subnetwork))` 306 307 308 - `tags` (array of strings) 309 310 - `use_internal_ip` (boolean) - If true, use the instance's internal IP 311 instead of its external IP during building. 312 313 ## Startup Scripts 314 315 Startup scripts can be a powerful tool for configuring the instance from which the image is made. 316 The builder will wait for a startup script to terminate. A startup script can be provided via the 317 `startup_script_file` or 'startup-script' instance creation `metadata` field. Therefore, the build 318 time will vary depending on the duration of the startup script. If `startup_script_file` is set, 319 the 'startup-script' `metadata` field will be overwritten. In other words,`startup_script_file` 320 takes precedence. 321 322 The builder does not check for a pass/fail/error signal from the startup script, at this time. Until 323 such support is implemented, startup scripts should be robust, as an image will still be built even 324 when a startup script fails. 325 326 ### Windows 327 328 A Windows startup script can only be provided via the 'windows-startup-script-cmd' instance 329 creation `metadata` field. The builder will *not* wait for a Windows startup scripts to 330 terminate. You have to ensure that it finishes before the instance shuts down. 331 332 ### Logging 333 334 Startup script logs can be copied to a Google Cloud Storage (GCS) location specified via the 335 'startup-script-log-dest' instance creation `metadata` field. The GCS location must be writeable by 336 the credentials provided in the builder config's `account_file`. 337 338 ## Gotchas 339 340 CentOS and recent Debian images have root ssh access disabled by default. Set `ssh_username` to 341 any user, which will be created by packer with sudo access. 342 343 The machine type must have a scratch disk, which means you can't use an 344 `f1-micro` or `g1-small` to build images.