Creating Instances Using Launch Plans

A launch plan is a JSON-formatted file that defines the properties of one or more instances. You can use a launch plan to quickly create and start multiple instances in Compute Classic.

About Launch Plans

A launch plan specifies the provisioning sequence and attributes of the instances that you want to create. Note that while you can reuse your launch plan JSON file to create new instances based on the attributes and provisioning sequence specified in the JSON file, the launch plan itself doesn’t persist in Compute Classic.

To understand how using launch plans differs from using orchestrations to create instances, see the FAQ How are orchestrations different from launch plans?.

Sample Launch Plan

The following is an example of a JSON-formatted file showing the attributes for two instances with different shapes and SSH keys but using the same image.

{
        "instances":
    [
        {
            "shape": "oc4",
            "imagelist": "/oracle/public/OL_6.7_UEKR4_x86_64",
            "sshkeys": ["/Compute-acme/admin/dev-ssh"],
            "name": "/Compute-acme/admin/dev-vm",
            "label": "dev-vm"
        },
        {
            "shape": "oc5",
            "imagelist": "/oracle/public/OL_6.7_UEKR4_x86_64",
            "sshkeys": ["/Compute-acme/admin/prod-ssh"],
            "name": "/Compute-acme/admin/prod-vm",
            "label": "prod-vm"
         }
        ]
}

Launch Plan Attributes

Parameter Required or Optional Description

instances

required

A list of instances.

Each instance is defined using the instance attributes.

relationships

optional

The relationships between various instances.

Valid values:

  • same_node: The specified instances are created on the same physical server. This is useful if you want to ensure low latency across instances.

  • different_node: The specified instances aren’t created on the same physical server. This is useful if you want to isolate instances for security or redundancy.

Instance Attributes Specified in a Launch Plan

Parameter Required or Optional Description

shape

required

The name of the shape that defines the number of OCPUs and the RAM that you require for the instance. For general purpose and high-memory shapes, you can select the block storage disk size, but for high I/O shapes, the size of the SSD storage is determined by the shape.

name

optional

The three-part name of the instance (/Compute-identity_domain/user/name).

If you specify this parameter, then the full name of the instance would be in the format, /Compute-identity_domain/user/name_you_specify/id.

If you don’t specify this parameter, then the full name would be in the format, /Compute-identity_domain/user/id.

In either case, id is an autogenerated ID.

Examples of Instance Names:

  • When you specify /Compute-acme/jack/vm1 as the value of the name parameter:

    /Compute-acme/jack/vm1/300a7479-ec90-4826-98b9-a725662628f1

  • When you don’t specify the name parameter:

    /Compute-acme/jack/38ef677e-9e13-41a7-a40c-2d99afce1714

Although this is an optional parameter, specifying a meaningful name makes it easier for you to identify your instances.

label

optional

A text string to identify the instance.

This label is used when defining relationships in an orchestration.

tags

optional

A JSON array or list of strings used to tag the instance.

By assigning a human-friendly tag to an instance, you can identify the instance easily when you perform an instance listing. These tags aren’t available from within the instance.

attributes

optional

A JSON object or dictionary of user-defined attributes to be made available to the instance.

If you’re creating a Windows instance, you must specify the following required attributes:
{
          "enable_rdp": true,
          "administrator_password": "Specify_password_here"
  }

For more information about specifying user-defined attributes that can be used to automate instance configuration, see Automating Instance Initialization Using opc-init.

Note:

Solaris machine images don’t include the opc-init scripts. So you can’t use opc-init to automate instance configuration of Solaris instances.

The attributes that you specify can be accessed from within the instance at http://192.0.0.192/latest/attributes. For more information about retrieving user-defined attributes, see Retrieving User-Defined Instance Attributes.

imagelist

optional

The three-part name (oracle/public/imagelist_name) of the image list containing the image to be used (example: /oracle/public/OL_6.7_UEKR4_x86_64).

You must use this attribute if you don’t specify a bootable storage volume by using the boot_order attribute. If you specify the imagelist attribute as well as the boot_order attribute, then the imagelist attribute is ignored.

storage_attachments

optional

If you specify the storage_attachments parameter, then specify the following subparameters for each attachment:

  • volume: The three-part name (/Compute-identity_domain/user/object_name) of the storage volume that you want to attach to the instance.

    Note that volumes attached to an instance at launch time can't be detached.

  • index: The index number for the volume.

    The allowed range is 1 to 10. If you want to use a storage volume as the boot disk for an instance, you must specify the index number for that volume as 1.

    The index determines the device name by which the volume is exposed to the instance. Index 0 is allocated to a nonpersistent boot disk, /dev/xvda. An attachment with index 1 is exposed to the instance as /dev/xvdb, an attachment with index 2 is exposed as /dev/xvdc, and so on.

boot_order

optional

The index number of the bootable storage volume that should be used to boot the instance. The only valid value is 1.

If you set this attribute, you must also specify a bootable storage volume with index number 1 in the volume sub-parameter of storage_attachments.

When you specify boot_order, you don’t need to specify the imagelist attribute, because the instance is booted using the image on the specified bootable storage volume. If you specify both boot_order and imagelist, the imagelist attribute is ignored.

hostname

optional

The host name assigned to the instance. On an Oracle Linux instance, this host name is displayed in response to the hostname command.

Only relative DNS is supported. The domain name is suffixed to the host name that you specify. The host name must not end with a period. If you don’t specify a host name, then a name is generated automatically. The DNS name of an instance depends on its host name, as follows:

  • If no DNS name is specified in the networking attribute, then the DNS name is set to the host name, and a reverse DNS record (PTR) is created for the host name.

  • If the DNS name specified in the networking attribute matches the host name, then that record also creates a reverse DNS record for the host name.

  • If the dns attribute under networking is set to an empty list ([]), then no DNS records are created even if a host name is specified. The instance still receives its host name through DHCP, and can perform a reverse lookup of its host name. However, no other instance can perform this reverse lookup.

Note:

If an instance has network interfaces defined only for IP networks and doesn’t have any interface on the shared network, then when hostname is specified, no DNS entries are set. In this case, DNS entries are set by the dns subparameter of the networking attribute.

reverse_dns

optional

If set to true (default), then reverse DNS records are created.

If set to false, no reverse DNS records are created.

networking (attributes for the shared network)

optional

ethn: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from eth0 to eth7.

Note:

For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same ethn interface.

Only one interface on an instance can be added to the shared network. To add an interface to the shared network, you can specify the following subparameters:

  • seclists: (Optional) The security lists that you want to add the instance to.

  • nat: (Optional) Indicates whether a temporary or permanent public IP address should be assigned to the instance.

  • dns: (Optional) DNS name for this instance. This name is relative to the internal DNS domain.

  • model: (Optional) The type of network interface card (NIC). The only allowed value is e1000.

  • name_servers: (Optional) The name servers that are sent through DHCP as option 6.  You can specify a maximum of eight name server IP addresses per interface.

  • search_domains: (Optional) The search domains that should be sent through DHCP as option 119.  You can enter a maximum of eight search domain zones per interface.

For more information about each of these subparameters, see Subparameters for a Network Interface on the Shared Network.

networking (attributes for IP networks)

optional

ethn: The interface that you’re defining. Oracle-provided images with release version 16.3.6 and later support eight vNICs. You can also create private images that support multiple vNICs. If the image you’ve specified supports eight vNICs, then you can specify up to eight network interfaces, from eth0 to eth7.

Note:

For each interface, you can specify parameters for either the shared network, or for an IP network. You can’t specify parameters for both networks for the same ethn interface.

To add this instance to an IP network, specify the following subparameters:

  • ipnetwork: The name of the IP network that you want to add the instance to.

  • ip: (Optional) If you want to associate a static private IP address with the instance, specify an available IP address from the IP address range of the specified ipnetwork.

  • address: (Optional) The MAC address of the interface, in hexadecimal format.

  • nat: (Optional) A list of IP reservation that you want to associate with this interface, in the format: "nat": ["network/v1/ipreservation:IP_reservation_name"].

    Here IP_reservation_name is the three-part name of the IP reservation in the /Compute-identity_domain/user/object_name format.

  • vnic: (Optional) The three-part name of the vNIC in the /Compute-identity_domain/user/object_name format.

  • vnicsets: (Optional) A list of the three-part names of the vNICsets that you want to add this interface to.

  • is_default_gateway: (Optional) If you want to specify the interface to be used as the default gateway for all traffic, set this to true. The default is false. If the instance has an interface on the shared network, that interface is always used as the default gateway.

  • dns: (Optional) A list of the DNS A record names for the instance.

  • name_servers: (Optional) A list of the name servers that should be sent through DHCP as option 6.  You can specify a maximum of eight name server IP addresses per interface.

  • search_domains: (Optional) A list of the search domains that should be sent through DHCP as option 119.  You can enter a maximum of eight search domain zones per interface.

For more information about each of these subparameters, see Subparameters for a Network Interface on an IP Network.

sshkeys

optional

A list of the SSH public keys that you want to associate with the instance.

Note:

You don’t need to provide any SSH public keys if you’re creating a Windows instance, because you can’t access a Windows instance using SSH. To access a Windows instance, see Accessing a Windows Instance Using RDP.

For each key, specify the three-part name in the /Compute-identity_domain/user/object_name format.

You can associate the same key with multiple instances.

The keys that you specify are stored as metadata on the instance. This metadata can be accessed from within the instance at http://192.0.0.192/{version}/meta-data/public-keys/{index}/openssh-key.
  • Oracle-provided images include a script that runs automatically when the instance starts, retrieves the keys, and adds them to the authorized_keys file of the opc user.

  • In images that you build, you can write and include a script that runs automatically when the instance starts, retrieves the SSH public keys, and adds the keys to the authorized_keys file of the appropriate users.

Prerequisite for Creating Instances Using Launch Plans

Ensure that you’ve created your launch plan JSON file.

Procedure for Creating Instances Using Launch Plans

To create instances from a launch plan by using the CLI, use the opc compute launch-plans add command. For help with that command, run the command with the -h option. For the instructions to install the CLI client, see Preparing to Use the Compute Classic CLI in CLI Reference for Oracle Cloud Infrastructure Compute Classic.

To create instances from a launch plan by using the API, use the POST /launchplan/ method. For more information, see REST API for Oracle Cloud Infrastructure Compute Classic.