»Oracle Cloud Infrastructure (OCI) Builder

Type: oracle-oci Artifact BuilderId: packer.oracle.oci

The oracle-oci Packer builder is able to create new custom images for use with Oracle Cloud Infrastructure (OCI). The builder takes a base image, runs any provisioning necessary on the base image after launching it, and finally snapshots it creating a reusable custom image.

It is recommended that you familiarise yourself with the Key Concepts and Terminology prior to using this builder if you have not done so already.

The builder does not manage images. Once it creates an image, it is up to you to use it or delete it.

»Authentication

There are three authentication methods available for the OCI builder. The API Signing Key of the DEFAULT profile in the OCI SDK and CLI Configuration File will be used by default.

»API Signing Key

The OCI REST API requires that requests be signed with the RSA public key associated with your IAM user account. For a comprehensive example of how to configure the required authentication see the documentation on Required Keys and OCIDs (Oracle Cloud IDs).

»Instance Principal

If you run Packer on an OCI compute instance, you can configure Packer to use the Instance Principal associated with that instance to authenticate instead of an API Signing Key that is associated with a specific user. This method requires the creation of appropriately configured Dynamic Groups and Policies.

The use_instance_principals parameter is used to enable this method.

The oci_instance_principals.pkr.hcl and oci_instance_principals.json examples can be used as a reference for configuring this authentication method.

»Security Token

Token-based authentication requires you to interactively authenticate a session using the OCI CLI and a web browser. The token that is created has an extremely limited TTL and must be refreshed every hour for up to 24 hours. However, this method allows for authentication using non-SCIM supported federated identity providers.

To use token-based authentication, start a new session using the CLI's oci session authenticate command and provide the path to the configuration file as the access_cfg_file configuration parameter and the name of the profile as the access_cfg_file_account configuration parameter.

The oci_security_token.pkr.hcl and oci_security_token.json examples can be used as a reference for this method.

»Configuration Reference

There are many configuration options available for the oracle-oci builder. 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 configuration parameters

• availability_domain (string) - The name of the Availability Domain within which a new instance is launched and provisioned. The names of the Availability Domains have a prefix that is specific to your tenancy.

  To get a list of the Availability Domains, use the ListAvailabilityDomains operation, which is available in the IAM Service API.

• base_image_ocid (string) - The OCID of the base image to use. This is the unique identifier of the image that will be used to launch a new instance and provision it.

  To get a list of the accepted image OCIDs, use the ListImages operation available in the Core Services API.

• base_image_filter (map of strings) - As an alternative to providing base_image_ocid, the user can supply search criteria, and Packer will use the the most recent image that meets all search criteria. If no image meets all search criteria, Packer returns an error. The following fields, if specified, must match exactly:

  • compartment_id - The OCID of the compartment to find the image. If not specified, will use compartment_ocid used for the instance.
  • display_name - The full name of the image, e.g., Oracle-Linux-7.8-2020.05.26-0
  • operating_system - The operating system used on the image, e.g., Oracle Linux
  • operating_system_version - The version of the operating system on the image, e.g., 7.8
  • shape - A shape that the image supports. If not specified, will use shape used for the instance

  Additionally, the following field takes a regular expression:

  • display_name_search - a regular expression for the display name, e.g., ^Oracle-Linux. This is ignored if display_name is also specified under base_image_filter. If no images match the expression, Packer returns an error. If multiple images match, the most recent is used.

  base_image_filter is ignored if base_image_ocid is also specified.

• compartment_ocid (string) - The OCID of the compartment that the instance will run in.

• shape (string) - The template that determines the number of CPUs, amount of memory, and other resources allocated to a newly created instance.

  To get a list of the available shapes, use the ListShapes operation available in the Core Services API.

  When using flexible shapes, ocpus must be set.

• subnet_ocid (string) - The name of the subnet within which a new instance is launched and provisioned.

  To get a list of your subnets, use the ListSubnets operation available in the Core Services API.

  Note: the subnet must be configured to allow access via your chosen communicator (communicator defaults to SSH tcp/22).

»Authentication parameters

Each of the following configuration parameters is either mandatory or unacceptable based on which authentication method is used.

• use_instance_principals (boolean) - Whether to use Instance Principals instead of User Principals. If this key is set to true, setting any one of the access_cfg_file, access_cfg_file_account, region, tenancy_ocid, user_ocid, key_file, fingerprint, pass_phrase parameters will cause an invalid configuration error. Defaults to false.

• access_cfg_file (string) - The path to the OCI config file. This parameter is optional when using token-based authentication. This parameter cannot be used along with the use_instance_principals key. Defaults to $HOME/.oci/config.

• access_cfg_file_account (string) - The specific account in the OCI config file to use. This parameter is mandatory when using token-based authentication. This parameter cannot be used along with the use_instance_principals key. Defaults to DEFAULT.

»Overriding authentication defaults

The following parameters can be used to override the default value provided by or configured for the default OCI CLI authenticaton profile.

• region (string) - An Oracle Cloud Infrastructure region. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

• tenancy_ocid (string) - The OCID of your tenancy. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

• user_ocid (string) - The OCID of the user calling the OCI API. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

• key_file (string) - Full path and filename of the OCI API signing key. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

• fingerprint (string) - Fingerprint for the OCI API signing key. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

• pass_phrase (string) - Pass phrase used to decrypt the OCI API signing key. Overrides value provided by the OCI config file if present. This cannot be used along with the use_instance_principals key.

  »Additional configuration parameters

• image_name (string) - The name to assign to the resulting custom image.

• image_compartment_ocid (string) - The OCID of the target compartment for the resulting image. Defaults to compartment_ocid.

• instance_name (string) - The name to assign to the instance used for the image creation process. If not set a name of the form instanceYYYYMMDDhhmmss will be used.

• instance_tags (map of strings) - Add one or more freeform tags to the instance used for the image creation process.

• instance_defined_tags_json (string) - Json string to add one or more defined tags for a given namespace to the instance used for the image creation process. Only works on HCL2 templates. For old-style JSON templates, use instance_defined_tags instead.

  instance_defined_tags_json = jsonencode({
    "Operations" = {
      "Environment" = "prod"
      "Team"        = "CostCenter"
    }
  })
  

  instance_defined_tags_json = jsonencode({  "Operations" = {    "Environment" = "prod"    "Team"        = "CostCenter"  }})

  Copy

• instance_defined_tags (map of maps of strings) - Add one or more defined tags for a given namespace to the instance used for the image creation process. Only works on old-style JSON templates. For HCL2 templates, use instance_defined_tags_json instead.

• create_vnic_details (map of strings) - Specify details for the virtual network interface card (VNIC) that is attached to the instance. Possible keys (all optional) are: assign_public_ip (bool), display_name (string), hostname_lable (string), nsg_ids (list), private_ip (string), skip_source_dest_check (bool), subnet_id (string), tags (map of string). Besides the previous keys, the defined_tags (map of maps of strings) is also available on old-style JSON templates, while defined_tags_json (string) is the json string equivalent variant for HCL2 templates. See the Oracle docs for more information about VNICs.

• disk_size (int64) - The size of the boot volume in GBs. Minimum value is 50 and maximum value is 16384 (16TB). Sets the BootVolumeSizeInGBs when launching the instance. Defaults to 50.

• image_launch_mode (string) - Specifies the configuration mode for launching instances. Valid values are "NATIVE", "EMULATED", "PARAVIRTUALIZED", and "CUSTOM". See the Oracle CLI docs for more information about these modes.

• use_private_ip (boolean) - Use private ip addresses to connect to the instance via ssh.

• shape_config (object) - The shape configuration for an instance. The shape configuration determines the resources allocated to an instance. Options:

  • ocpus (required when using flexible shapes or memory_in_gbs is set) (float32) - The total number of OCPUs available to the instance.
  • memory_in_gbs (optional) (float32) - The total amount of memory, in gigabytes, available to the instance.

• metadata (map of strings) - Metadata optionally contains custom metadata key/value pairs provided in the configuration. While this can be used to set metadata["user_data"] the explicit "user_data" and "user_data_file" values will have precedence. An instance's metadata can be obtained from at http://169.254.169.254 on the launched instance.

• user_data (string) - User data to be used by cloud-init. See the Oracle docs for more details. Generally speaking, it is easier to use the user_data_file, but you can use this option to put either the plaintext data or the base64 encoded data directly into your Packer config. Packer will not automatically wait for a user script to finish before shutting down the instance this must be handled in a provisioner.

• user_data_file (string) - Path to a file to be used as user data by cloud-init. See the Oracle docs for more details. Example: "user_data_file": "./boot_config/myscript.sh"

• tags (map of strings) - Add one or more freeform tags to the resulting custom image. See the Oracle docs for more details. Example:

'tags':
  'tag1': 'value1'
  'tag2': 'value2'

'tags':  'tag1': 'value1'  'tag2': 'value2'

• defined_tags_json (string) - JSON string to add one or more defined tags for a given namespace to the resulting custom image. Only works on HCL2 templates. For old-style JSON templates, use defined_tags instead.

  defined_tags_json = jsonencode({
    "tag1" = {
      "tag1.2" = "value1"
    }
    "tag2" = "value2"
  })
  

  defined_tags_json = jsonencode({  "tag1" = {    "tag1.2" = "value1"  }  "tag2" = "value2"})

  Copy

  See the Oracle docs for more details.

• defined_tags (map of map of strings) - Add one or more defined tags for a given namespace to the resulting custom image. Only works on old-style JSON templates. For HCL2 templates, use defined_tags_json instead. See the Oracle docs for more details. Example:

'tags':
  'namespace': { 'tag1': 'value1', 'tag2': 'value2' }

'tags':  'namespace': { 'tag1': 'value1', 'tag2': 'value2' }

»Basic Example

Here is a basic example. Note that account specific configuration has been substituted with the letter a and OCIDS have been shortened for brevity.

source "oracle-oci" "example" {
  availability_domain = "aaaa:PHX-AD-1"
  base_image_ocid     = "ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa"
  compartment_ocid    = "ocid1.compartment.oc1..aaa"
  image_name          = "ExampleImage"
  shape               = "VM.Standard1.1"
  ssh_username        = "opc"
  subnet_ocid         = "ocid1.subnet.oc1..aaa"
}

build {
  sources = ["source.oracle-oci.example"]
}

source "oracle-oci" "example" {  availability_domain = "aaaa:PHX-AD-1"  base_image_ocid     = "ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa"  compartment_ocid    = "ocid1.compartment.oc1..aaa"  image_name          = "ExampleImage"  shape               = "VM.Standard1.1"  ssh_username        = "opc"  subnet_ocid         = "ocid1.subnet.oc1..aaa"}
build {  sources = ["source.oracle-oci.example"]}

»Using Instance Principals

Here is a basic example. Note that account specific configuration has been substituted with the letter a and OCIDS have been shortened for brevity.

source "oracle-oci" "example" {
  availability_domain     = "aaaa:PHX-AD-1"
  base_image_ocid         = "ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa"
  compartment_ocid        = "ocid1.compartment.oc1..aaa"
  image_name              = "ExampleImage"
  shape                   = "VM.Standard2.1"
  ssh_username            = "opc"
  subnet_ocid             = "ocid1.subnet.oc1..aaa"
  use_instance_principals = "true"
}

build {
  sources = ["source.oracle-oci.example"]
}

source "oracle-oci" "example" {  availability_domain     = "aaaa:PHX-AD-1"  base_image_ocid         = "ocid1.image.oc1.phx.aaaaaaaa5yu6pw3riqtuhxzov7fdngi4tsteganmao54nq3pyxu3hxcuzmoa"  compartment_ocid        = "ocid1.compartment.oc1..aaa"  image_name              = "ExampleImage"  shape                   = "VM.Standard2.1"  ssh_username            = "opc"  subnet_ocid             = "ocid1.subnet.oc1..aaa"  use_instance_principals = "true"}
build {  sources = ["source.oracle-oci.example"]}

[opc@packerhost ~]$ packer build packer.json
oracle-oci: output will be in this color.

==> oracle-oci: Creating temporary ssh key for instance...
==> oracle-oci: Creating instance...
==> oracle-oci: Created instance (ocid1.instance.oc1.phx.aaa).
==> oracle-oci: Waiting for instance to enter 'RUNNING' state...
==> oracle-oci: Instance 'RUNNING'.
==> oracle-oci: Instance has IP: 10.10.10.10.
==> oracle-oci: Using ssh communicator to connect: 10.10.10.10
==> oracle-oci: Waiting for SSH to become available...
==> oracle-oci: Connected to SSH!
==> oracle-oci: Creating image from instance...
==> oracle-oci: Image created.
==> oracle-oci: Terminating instance (ocid1.instance.oc1.phx.aaa)...
==> oracle-oci: Terminated instance.
Build 'oracle-oci' finished.

==> Builds finished. The artifacts of successful builds are:
--> oracle-oci: An image was created: 'ExampleImage' (OCID: ocid1.image.oc1.phx.aaa) in region 'us-phoenix-1'
[opc@packerhost ~]$

[opc@packerhost ~]$ packer build packer.jsonoracle-oci: output will be in this color.
==> oracle-oci: Creating temporary ssh key for instance...==> oracle-oci: Creating instance...==> oracle-oci: Created instance (ocid1.instance.oc1.phx.aaa).==> oracle-oci: Waiting for instance to enter 'RUNNING' state...==> oracle-oci: Instance 'RUNNING'.==> oracle-oci: Instance has IP: 10.10.10.10.==> oracle-oci: Using ssh communicator to connect: 10.10.10.10==> oracle-oci: Waiting for SSH to become available...==> oracle-oci: Connected to SSH!==> oracle-oci: Creating image from instance...==> oracle-oci: Image created.==> oracle-oci: Terminating instance (ocid1.instance.oc1.phx.aaa)...==> oracle-oci: Terminated instance.Build 'oracle-oci' finished.
==> Builds finished. The artifacts of successful builds are:--> oracle-oci: An image was created: 'ExampleImage' (OCID: ocid1.image.oc1.phx.aaa) in region 'us-phoenix-1'[opc@packerhost ~]$

»Assigning Tags and Network Security Groups to the Instance

Tags are useful for breaking down costs and usage. The keys instance_tags and instance_defined_tags are assigned to the temporary instance, whereas tags and defined_tags are assigned to the resulting image.

Network Security Groups (NSGs) are used for granting networking permissions to the instance. Depending on network (VCN and subnet) setup, this may be required for Packer to successfully SSH into the instance. NSGs are a property of the virtual network interface card (VNIC) attached to the instance, and are listed in nsg_ids under create_vnic_details.

locals {
  timestamp = "${formatdate("YYYYMMDDhhmmss", timestamp())}"
}

source "oracle-oci" "base-image-example" {
  availability_domain = "aaaa:PHX-AD-1"
  base_image_ocid     = "ocid1.image.oc1.iad.aaa"
  compartment_ocid    = "ocid1.compartment.oc1..aaa"
  create_vnic_details {
    assign_public_ip = "false"
    display_name     = "testing-123"
    nsg_ids          = ["ocid1.networksecuritygroup.oc1.iad.aaa"]
  }
  image_name = "my-image-${local.timestamp}"
  instance_defined_tags_json = jsonencode({
    "Operations" = {
      "Environment" = "prod"
      "Team"        = "CostCenter"
    }
  })
  instance_name = "packer-build-${local.timestamp}"
  instance_tags = {
    testing = "yes"
  }
  shape       = "VM.Standard.E2.1"
  subnet_ocid = "ocid1.subnet.oc1.iad.aaa"
  tags = {
    CreationDate = "${legacy_isotime("20060102 03:04:05 MST")}"
  }
  use_private_ip = "true"
}

build {
  sources = ["source.oracle-oci.base-image-example"]
}

locals {  timestamp = "${formatdate("YYYYMMDDhhmmss", timestamp())}"}
source "oracle-oci" "base-image-example" {  availability_domain = "aaaa:PHX-AD-1"  base_image_ocid     = "ocid1.image.oc1.iad.aaa"  compartment_ocid    = "ocid1.compartment.oc1..aaa"  create_vnic_details {    assign_public_ip = "false"    display_name     = "testing-123"    nsg_ids          = ["ocid1.networksecuritygroup.oc1.iad.aaa"]  }  image_name = "my-image-${local.timestamp}"  instance_defined_tags_json = jsonencode({    "Operations" = {      "Environment" = "prod"      "Team"        = "CostCenter"    }  })  instance_name = "packer-build-${local.timestamp}"  instance_tags = {    testing = "yes"  }  shape       = "VM.Standard.E2.1"  subnet_ocid = "ocid1.subnet.oc1.iad.aaa"  tags = {    CreationDate = "${legacy_isotime("20060102 03:04:05 MST")}"  }  use_private_ip = "true"}
build {  sources = ["source.oracle-oci.base-image-example"]}

»Base Image Filter Example

Note that base_image_filter gets passed as a string, then interpreted as a regular expression. This means that all back-slashes must be doubled, e.g., use \\w+ to mean \w+, and \\\\ to create the regular expression equivalent of \\ (which will search for a literal back-slash).

{
  "name":                "base-image-{{isotime \"20060102030405\"}}",
  "type":                "oracle-oci",
  "availability_domain": "aaaa:PHX-AD-1",
  "base_image_filter": {
    "operating_system": "Oracle Linux",
    "operating_system_version": "7.8",
    "display_name_search": "^Oracle-Linux-7\\.8-2020\\.\\d+"
  }
  ...
}

{  "name":                "base-image-{{isotime \"20060102030405\"}}",  "type":                "oracle-oci",  "availability_domain": "aaaa:PHX-AD-1",  "base_image_filter": {    "operating_system": "Oracle Linux",    "operating_system_version": "7.8",    "display_name_search": "^Oracle-Linux-7\\.8-2020\\.\\d+"  }  ...}