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