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.