Working with Instance Configurations

An instance configuration contains settings that are used to create a compute instance. Instance configurations enable you to consistently create instances with the same configuration without re-typing the configuration values using the OCI CLI or re-entering the configuration in the Compute Web UI. You can use an instance configuration to create a single instance or to create an instance pool.

Creating an Instance Configuration

You can create an instance configuration from an existing instance (a template instance) or by entering the individual configuration settings.

Note the following when you use a template instance to create an instance configuration:

The new instance configuration does not include any information from the boot volume of the template instance. For example, installed applications, binaries, and files that are on the template instance are not included in the instance configuration.

Use the following procedure to create an instance configuration that includes the custom setup from the template instance:
1. Create a custom image from the template instance. See Creating an Image from an Instance.
2. Use the custom image to create a new instance. See Creating an Instance.
3. Use the instance that you created in the preceding step as the template to create the instance configuration.
The instance configuration does not include the contents of any block volumes that are attached to the template instance.
Instances that are created from this new instance configuration are placed in the same compartment as the template instance.

To include block volumes or secondary VNICs in the configuration, or to specify the compartment where new instances will be created, create the instance configuration as described in Creating an Instance Configuration by Entering Configuration Values.

Creating an Instance Configuration from an Instance

These procedures describe how to create an instance configuration by using the configuration information from an existing compute instance.

Using the Compute Web UI

On the Dashboard, click the Compute/View Instances button.
If the instance that you want to use to create the new instance configuration is not listed, use the Compartment drop-down menu above the instances list to select the correct compartment.
Click the name of the instance that you want to use to create the new instance configuration.
On the instance details page, click the Controls menu, and then click the Create Instance Configuration option.
In the Create Instance Configuration dialog, enter the following information:
- Name: Enter a name for the instance configuration.
- Compartment: Select the compartment where this instance configuration will be created.
- Tagging: (Optional) Add defined or free-form tags for this instance as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Instance Configuration button in the dialog.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to create this instance configuration.
- The OCID of the instance to use to create the instance configuration.
Run the instance configuration create command.

Syntax:
```
oci compute-management instance-configuration create-from-instance \
--compartment-id compartment_OCID --instance-id ocid1.instance.unique_ID \
--display-name IC_name
```
The specified compartment is where this instance configuration will be created.

The specified display name is the name of the instance configuration. If you do not provide a value for the --display-name option, the default name of the instance configuration is instanceconfigurationYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

The output of this command is the same as the output of the instance-configuration get command.

Creating an Instance Configuration by Entering Configuration Values

These procedures describe how to create an instance configuration by entering values for individual instance configuration settings in the Compute Web UI or in command line options.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Configurations.
Click the Create Instance Configuration button.
In the Create Instance Configuration dialog, enter the following information:
- Name: Enter a name for the instance configuration.
- Create in compartment: Select the compartment where you want this instance configuration to be created.
- Compartment to create instances in: Select the compartment where you want the instances that are created using this instance configuration to be created.
- Fault Domain: (Optional) You can select a fault domain. By default, the system automatically selects the best fault domain for instances created using this instance configuration. If you specify a fault domain, and the requested fault domain cannot accommodate the instance, instance launch fails. See more information about fault domains in Creating an Instance.
- Source Image: Select an image or boot volume.
  1. Select the Source Type: Platform Image, Custom Image, or Boot Volume.
  2. If you selected Custom Image or Boot Volume, select the compartment where the image or boot volume that you want to use is located.
  3. Select an image or boot volume from the list.
    
    If you selected Platform Image, you see a tabular list with columns Operating System, OS Version, and Image Build (the date the image was built). You can use the drop-down menu arrow to the right of the OS Version to select a different version. For example, for the Oracle Linux operating system, you can use the drop-down menu to select 9, 8, or 7.9.
    
    If you selected Custom Image, you see a tabular list with columns Name, Operating System, and OS Version. You can use the arrows in the column headings to sort the list. You can filter the list by using the Operating System drop-down menu above the list of images.
    
    If you selected Boot Volume, you see a tabular list with columns Name, Size (GB), and Created (the date the boot volume was created). You can use the arrows in the column headings to sort the list. In the Boot Volume section (after the Shape section), you can customize the boot volume size.
    
    If the list is too long to fit in one view, use the arrow buttons to view another page of the list.
    
    To use a platform image that was previously available but is no longer listed, use the OCI CLI to create the instance and specify the OCID of the image.
- Shape: Select a shape. For a description of each compute instance shape, see Compute Shapes in the Oracle Private Cloud Appliance Concepts Guide.
  
  If you select a standard shape, the amount of memory and number of OCPUs are displayed. These numbers match the numbers shown for this shape in the table in the Oracle Private Cloud Appliance Concepts Guide.
  
  If you select the flexible shape, VM.PCAStandard1.Flex, you must specify the number of OCPUs you want and you can specify the total amount of memory you want. The default value for gigabytes of memory is 16 times the number you specify for OCPUs. Click inside each value field to see the minimum and maximum allowed values.
- Boot Volume: (Optional) Check the box to specify a custom boot volume size or volume performance setting.
  - Boot volume size (GB): The default boot volume size for the selected image is shown. To specify a larger size, enter an integer number of gigabytes up to 16384 (16 TB) or use the increment and decrement arrows. You cannot enter a value smaller than the default size.
    
    If you specify a custom boot volume size, you need to extend the partition to take advantage of the larger size. Oracle Linux platform images include the oci-utils package. Use the oci-growfs command from that package to extend the root partition and then grow the file system. For other operating systems or for custom images, follow the instructions for that operating system.
  - Boot volume performance (VPUs): Use the increment and decrement arrows to toggle between balanced performance (10 VPUs/GB) and high performance (20 VPUs/GB). For more information, see "Block Volume Performance Options" in the Block Volume Storage Overview chapter in the Oracle Private Cloud Appliance Concepts Guide.
- Subnet: Select a subnet.
  1. Select a VCN from the list. You might need to change the compartment to the compartment where the VCN is located.
  2. Select a subnet.
- Public IP Address: To use SSH to connect to instances created with this instance configuration, check the Assign Public IP box to have a public IP address assigned to the instances. This box is checked by default if you specified a public subnet. If you do not check this box, or if you clear this box, and then want to assign a public IP address later, see Assigning an Ephemeral Public IP Address to an Instance for instructions.
- Secondary VNICs: (Optional) Check the Create Additional VNIC box to create secondary VNICs for instances created with this instance configuration, For descriptions of the information requested here, see Creating and Attaching a Secondary VNIC.
- Private IP Address: (Optional) Specify an available private IP address from the subnet's CIDR. By default, a private IP address is automatically assigned. Because the private IP address must be unique for each instance, do not specify a private IP address if you are going to use this instance configuration to create an instance pool.
- DNS Record: (Optional) Check the Assign a private DNS record box to assign a DNS record to instances created with this instance configuration,
- Hostname: (Optional) Enter a hostname if you are using DNS within the cloud network. The hostname must be unique across all VNICs in the subnet. Do not specify a host name if you are going to use this instance configuration to create an instance pool.
  
  By default, the instance name is used for the hostname. The hostname can also be configured in the OS after the instance is created.
  
  If this is a UNIX instance, see Creating a Mount Target and Mounting File Systems on UNIX-Based Instances for more information about setting the host name correctly for mounting file systems.
- SSH Keys: To connect to the instance using SSH, provide a public SSH key.
  
  Note:
  
  You cannot provide this SSH key after the instance is created.
- Network Security Group: (Optional) By default, instances are not attached to any NSG. Check the Enable Network Security Group box to add the primary VNIC for this instance to one or more NSGs.
  1. Select an NSG from the drop-down list. You might need to change the compartment to find the NSG you want.
  2. Click the Add Network Security Group button to attach to another NSG.
  3. To remove an NSG from the list, click the trash can to the right of that NSG. To remove the last NSG or all NSGs, clear the Enable Network Security Groups box.
  See Controlling Traffic with Network Security Groups for information about NSGs.
- Instance Options: Check the box to disable Legacy Instance Metadata Service Endpoints. By default, legacy (/v1) Instance Metadata Service (IMDS) routes are enabled. If you have upgraded your applications to use /v2 endpoints, check this box to disable /v1 endpoints. For more information about the Instance Metadata Service, see Retrieving Instance Metadata from Within the Instance. For more information about upgrading your applications, see Upgrading to IMDS Version 2 Endpoints.
- Availability configuration: (Optional) By default, the system automatically selects the best instance availability option during a maintenance operation such as live migration. Check the "Restore instance lifecycle state after infrastructure maintenance" box to specify that running instances should be automatically restarted after a maintenance event. If this box is not checked, the instance is recovered in the stopped state. For more information, see Configuring the Compute Service for High Availability in the Oracle Private Cloud Appliance Administrator Guide.
- Tagging: (Optional) Add defined or free-form tags for this instance as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Instance Configuration button in the dialog.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to create this instance configuration.
- The OCID of the compartment where you want instances that use this instance configuration to be created.
- The OCID of the image or boot volume for instances that use this instance configuration.
- The name of the shape for instances that use this instance configuration.
- The OCID of the subnet for instances that use this instance configuration.
Create the configuration file that is input to the configuration create command.

The configuration file is a JSON file of property/value pairs.
- The following command shows the correct syntax of the configuration file and names of properties:
```
$ oci compute-management instance-configuration create \
--generate-param-json-input instance-details > instance_details.json
```
  You do not need all of the data that is output by this command. Copy just the information you need, being careful to keep each property in its correct context.
  
  If you omit the fault domain specification, the system automatically selects the best fault domain. If you specify only a single fault domain, all instances will be placed in only that fault domain.
  
  If a fault domain that you specify does not have enough resources, instances could fail to launch:
  - When you launch a single instance (Using an Instance Configuration to Launch an Instance), and you specify a fault domain in the instance configuration, only that specified fault domain will be used to launch the instance. Resource constraints could cause the instance launch to fail.
  - When you create instances in a pool, fault domains specified in the placement configuration override fault domains specified in the instance configuration. See Creating an Instance Pool for more information.
  You can specify secondary VNICs and subnets. If you specify a hostname label for a secondary VNIC, the specified hostname label must be unique across all VNICs in the subnet. If you provide a value for the hostnameLabel property, you must also set the value of assignPrivateDnsRecord to true.
  - If the specified hostname label is already in use in the subnet, instance launch (Using an Instance Configuration to Launch an Instance) will fail with the error "Hostname hostname already in use for the subnet."
  - The hostnameLabel property is ignored when you use the instance configuration to create a pool of instances. By default, the instance name is used for the hostname.
  If you omit the assignPublicIp property, a public IP address is assigned by default if you specify a public subnet. If you set this property to false and then decide to assign a public IP address later, see Assigning an Ephemeral Public IP Address to an Instance for instructions.
  
  If users will use ssh to connect to the instance, specify the SSH public key as the value of the ssh_authorized_keys property in the metadata block. You cannot add the SSH public key after the instance is created.
  
  The displayName property is used for the instance name when you use the launch-compute-instance command as described in Using an Instance Configuration to Launch an Instance. If you do not provide a value for the displayName property, the default name of instances will be instanceYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.
  
  The displayName property is ignored when you create instances in a pool as described in Creating an Instance Pool.
- The following command shows which properties are required to create an instance:
```
$ oci compute instance launch -h
```
  Scroll to the Required Parameters section. Optional parameters are described below the required parameters.
The names of the properties in the configuration file are similar to, but different from, the names of the instance launch options. Also, some properties are organized into groups of properties, such as createVnicDetails, shapeConfig, and sourceDetails, as shown in the following example configuration file:
```
{
  "instanceType": "compute",
  "launchDetails": {
    "availabilityDomain": "AD-1",
    "compartmentId": "compartment_OCID",
    "createVnicDetails": {
      "assignPublicIp": true,
      "freeformTags": {
        "ConfigType": "Configuration for an XYZ instance."
      },
      "subnetId": "subnet_OCID"
    },
    "displayName": "instance_name",
    "instanceOptions": {
      "areLegacyImdsEndpointsDisabled": true
    },
    "metadata": {
      "ssh_authorized_keys": "public_SSH_key"
    },
    "shape": "shape_name",
    "shapeConfig": {
      "memoryInGBs": 512,
      "ocpus": 32
    },
    "sourceDetails": {
      "bootVolumeSizeInGBs": 100,
      "bootVolumeVpusPerGB": 20,
      "imageId": "image_OCID",
      "sourceType": "image"
    }
  }
}
```
Use instanceOptions if you need to disable IMDSv1 endpoints for this instance. See Retrieving Instance Metadata from Within the Instance.

If you specify the flexible shape, VM.PCAStandard1.Flex, then you must also specify the shape configuration, as shown in the preceding example. You must provide a value for ocpus. The memoryInGBs property is optional; the default value in gigabytes is 16 times the number of ocpus.

If you specify a standard shape, do not specify shapeConfig.

For information about bootVolumeSizeInGBs, see "Boot volume size" in the preceding Compute Web UI procedure.

For information about bootVolumeVpusPerGB, see "High Performance" in the preceding Compute Web UI procedure. When instances are launched, the value of bootVolumeVpusPerGB is null because this boot volume property is not stored in the instance object after the instance is launched. To check the value, use the get boot volume command and see the value of vpus-per-gb.

To change the value of the firmware property, provide a value for the launchOptions property. The default value is BIOS. You can alternatively specify UEFI_64. Other properties in launchOptions cannot be changed.
```
"launchOptions": {
  "bootVolumeType": "PARAVIRTUALIZED",
  "firmware": "UEFI_64",
  "isConsistentVolumeNamingEnabled": false,
  "isPvEncryptionInTransitEnabled": false,
  "networkType": "PARAVIRTUALIZED",
  "remoteDataVolumeType": "PARAVIRTUALIZED"
}
```
Run the instance configuration create command.

Syntax:
```
oci compute-management instance-configuration create -c compartment_OCID \
--display-name IC_name --instance-details file://custom_config_file.json
```
The specified compartment is where this instance configuration will be created. This compartment could be different from the compartment specified in the instance details JSON file, which is where the instances will be created.

The specified display name is the name of the instance configuration. If you do not provide a value for the --display-name option, the default name of the instance configuration is instanceconfigurationYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time. (See Step 2 for a description of the display name specified in the instance details JSON file.)

The output of this command is the same as the output of the instance-configuration get command.

Updating an Instance Configuration

You can change the name of the instance configuration and change the tags. To change configuration such as the compartment, subnet, or image, create a new instance configuration.

Using the Compute Web UI

On the Dashboard, click the Compute/View Instances button.
In the Compute menu, click Instance Configurations.
If the instance configuration that you want to update is not listed, use the Compartment drop-down menu above the instance configurations list to select the correct compartment.
For the instance configuration that you want to update, click the Actions menu, and click the Edit option.
In the Update Instance Configuration dialog, make the changes.
Click the Update Instance Configuration button in the dialog.

Using the OCI CLI

Get the OCID of the instance configuration that you want to update: oci compute-management instance-configuration list

Run the instance configuration update command.

Example:

$ oci compute-management instance-configuration update \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID \
--defined-tags file://instcfgdeftags.json

Moving an Instance Configuration to a Different Compartment

You can move an instance configuration to a different compartment within the same tenancy. When you move an instance configuration to a different compartment, instances and instance pools created by using this instance configuration are not moved.

New instances and instance pools that are created using this instance configuration are created in the compartment specified in the instance configuration, not in the compartment to which the instance configuration has been moved.

To move an instance configuration, you must use the OCI CLI.

Using the OCI CLI

Get the following information:
- The OCID of the current compartment, and the OCID of the destination compartment: oci iam compartment list
- The OCID of the instance configuration: oci compute-management instance-configuration list

Run the instance configuration change compartment command.

Syntax:

oci compute-management instance-configuration change-compartment \
--compartment-id destination_compartment_OCID \
--instance-configuration-id instance_configuration_OCID

Deleting an Instance Configuration

An instance configuration that is being used by any pool cannot be deleted.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Configurations.
If the instance configuration that you want to delete is not listed, use the Compartment drop-down menu above the instance configurations list to select the correct compartment.
Click the name of the instance configuration that you want to delete.
On the instance configuration details page, click the Delete button.
Click the Confirm button.

Using the OCI CLI

Get the OCID of the instance configuration that you want to delete: oci compute-management instance-configuration list

Run the instance configuration delete command.

Example:

$ oci compute-management instance-configuration delete \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID
Are you sure you want to delete this resource? [y/N]: y

Using an Instance Configuration to Launch an Instance

This section shows how to use the instance configuration that you created in Creating an Instance Configuration to launch a compute instance.

This method of launching a compute instance is an alternative to the method described in Creating an Instance.

The name of the instance will be one of the following:

If the instance configuration specifies a value for the displayName property, the name of the instance will be displayName. If you use the same instance configuration with multiple launch-compute-instance commands, all instances will have the same name. Instance names are not required to be unique.
If the instance configuration does not specify a value for the displayName property, the default name of the instance will be instanceYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

Using the OCI CLI

Get the OCID of the instance configuration that you want to use to launch the instance: oci compute-management instance-configuration list
Run the instance configuration launch instance command.

Example:
```
$ oci compute-management instance-configuration launch-compute-instance \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID
```
The output of this command is the same as the output of the compute instance get command with the addition of a work request OCID. Use the work-requests work-request get command to check the status of the instance launch.

If the launch operation fails because of resource constraints, see the suggested remedies in Creating an Instance.