Yandex Compute

Type: yandex Artifact BuilderId: packer.yandex

The yandex Packer builder is able to create images for use with Yandex Compute Cloud based on existing images.

Authentication

Builder can authenticate with Yandex.Cloud using one of the following methods:

• OAuth token
• IAM token
• File with Service Account Key
• Service Account assigned to Compute Instance

Authentication Using Token

To authenticate with an OAuth token or IAM token only token config key is needed. Or use the YC_TOKEN environment variable with proper value. Token you could get here. Check documentation about how to create IAM token.

Authentication Using Service Account Key File

To authenticate with a service account credential, only service_account_key_file is needed. Or use the YC_SERVICE_ACCOUNT_KEY_FILE environment variable. The parameter expects a value path to the service account file in json format. Check documentation about how to create SA and its key.

Authentication Using a Compute Instance Service Account

Authentication with a Service Account on an instance happens when neither the token nor the service_account_key_file parameter is set. To get more information about this kind of authentication check documentaion.

Basic Example

JSON

{
  "type": "yandex",
  "token": "YOUR OAUTH TOKEN",
  "folder_id": "YOUR FOLDER ID",
  "source_image_family": "ubuntu-1804-lts",
  "ssh_username": "ubuntu",
  "use_ipv4_nat": "true"
}

HCL2

source "yandex" "autogenerated_1" {
  folder_id           = "YOUR FOLDER ID"
  source_image_family = "ubuntu-1804-lts"
  ssh_username        = "ubuntu"
  token               = "YOUR OAUTH TOKEN"
  use_ipv4_nat        = "true"
}
 
build {
  sources = ["source.yandex.autogenerated_1"]
 
}

Configuration Reference

Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described.

In addition to the options listed here, a communicator can be configured for this builder. In addition to the options defined there, a private key file can also be supplied to override the typical auto-generated key:

• ssh_private_key_file (string) - Path to a PEM encoded private key file to use to authenticate with SSH. The ~ can be used in path and will be expanded to the home directory of current user.

Required:

Access

• token (string) - OAuth token or IAM token to use to authenticate to Yandex.Cloud. Alternatively you may set value by environment variable YC_TOKEN.

Builder

• source_image_family (string) - The source image family to create the new image from. You can also specify source_image_id instead. Just one of a source_image_id or source_image_family must be specified. Example: ubuntu-2204-lts.

Common

• folder_id (string) - The folder ID that will be used to launch instances and store images. Alternatively you may set value by environment variable YC_FOLDER_ID. To use a different folder for looking up the source image or saving the target image to check options 'source_image_folder_id' and 'target_image_folder_id'.

Optional:

Access

• endpoint (string) - Non standard API endpoint. Default is api.cloud.yandex.net:443.

• service_account_key_file (string) - Contains either a path to or the contents of the Service Account file in JSON format. This can also be specified using environment variable YC_SERVICE_ACCOUNT_KEY_FILE. You can read how to create service account key file here.

• max_retries (int) - The maximum number of times an API request is being executed.

Builder

• service_account_id (string) - Service account identifier to assign to instance.

• target_image_folder_id (string) - The ID of the folder to save built image in. This defaults to value of 'folder_id'.

• source_image_folder_id (string) - The ID of the folder containing the source image.

• source_image_id (string) - The source image ID to use to create the new image from.

• source_image_name (string) - The source image name to use to create the new image from. Name will be looked up in source_image_folder_id.

Common

• serial_log_file (string) - File path to save serial port output of the launched instance.

• state_timeout (duration string | ex: "1h5m2s") - The time to wait for instance state changes. Defaults to 5m.

Instance

• instance_cores (int) - The number of cores available to the instance.

• instance_core_fraction (int) - The vCPU performance level (core fraction) of the instance

• instance_gpus (int) - The number of GPU available to the instance.

• instance_mem_gb (int) - The amount of memory available to the instance, specified in gigabytes.

• instance_name (string) - The name assigned to the instance.

• platform_id (string) - Identifier of the hardware platform configuration for the instance. This defaults to standard-v2.

• labels (map[string]string) - Key/value pair labels to apply to the launched instance.

• metadata (map[string]string) - Metadata applied to the launched instance.

• metadata_from_file (map[string]string) - Metadata applied to the launched instance. The values in this map are the paths to the content files for the corresponding metadata keys.

• preemptible (bool) - Launch a preemptible instance. This defaults to false.

Disk

• disk_name (string) - The name of the disk, if unset the instance name will be used.

• disk_size_gb (int) - The size of the disk in GB. This defaults to 10/100GB.

• disk_type (string) - Specify disk type for the launched instance. Defaults to network-ssd.

• disk_labels (map[string]string) - Key/value pair labels to apply to the disk.

Image

• image_name (string) - The name of the resulting image, which contains 1-63 characters and only supports lowercase English characters, numbers and hyphen. Defaults to packer-{{timestamp}}.

• image_description (string) - The description of the image.

• image_family (string) - The family name of the image.

• image_labels (map[string]string) - Key/value pair labels to apply to the image.

• image_min_disk_size_gb (int) - Minimum size of the disk that will be created from built image, specified in gigabytes. Should be more or equal to disk_size_gb.

• image_product_ids ([]string) - License IDs that indicate which licenses are attached to resulting image.

• image_pooled (bool) - When true, an image pool will be created for fast creation disks from the image.

• skip_create_image (bool) - Skip creating the image. Useful for setting to true during a build test stage. Defaults to false.

Network

• subnet_id (string) - The Yandex VPC subnet id to use for the launched instance. Note, the zone of the subnet must match the zone in which the VM is launched.

• zone (string) - The name of the zone to launch the instance. This defaults to ru-central1-a.

• security_group_ids ([]string) - Security group ids for network interface of the instance.

• use_ipv4_nat (bool) - If set to true, then launched instance will have external internet access.

• use_ipv6 (bool) - Set to true to enable IPv6 for the instance being created. This defaults to false, or not enabled.

  Note: Usage of IPv6 will be available in the future.

• use_internal_ip (bool) - If true, use the instance's internal IP address instead of its external IP during building.

Build template data

In configuration directives the following variables are available:

• ImageID - ID of the built image.
• ImageName - Name of the built image.
• ImageFamily - Family of the built image.
• ImageDescription - Description of the built image.
• ImageFolderID - Folder ID where the built image is stored.
• SourceImageID - The source image ID (for example fd8fjtn3mj2kfe7h6f0r) used to build the image.
• SourceImageName - The source image name (for example ubuntu-1604-lts-1579200746) used to build the image.
• SourceImageDescription - The source image description (for example ubuntu 16.04 lts).
• SourceImageFamily - The source image family (for example ubuntu-1604-lts).
• SourceImageFolderID - The folder ID where source image located (for example standard-images).

Build Shared Information Variables

This builder generates data that are shared with provisioner and post-processor via build function of template engine for JSON and contextual variables for HCL2.

The generated variables available for this builder see above

Usage example:

JSON

"post-processors": [
    {
      "type": "manifest",
      "output": "manifest.json",
      "strip_path": true,
      "custom_data": {
        "source_image_id": "{{ build `SourceImageID` }}"
      }
    }
]

HCL2

post-processor "manifest" {
    output = "manifest.json"
    strip_path = true
    custom_data = {
        source_image_id = "${build.SourceImageID}"
    }
}