Oracle Cloud Infrastructure Documentation

Creating Instance Configurations

Instance configurations let you define the settings to use when creating compute instances. Use an instance configuration in the following scenarios:

  • To create one or more instances in an instance pool.
  • As a template for launching individual instances that are not part of a pool.

When you create an instance configuration, you can either use an existing compute instance as a template, or you can provide a list of configuration settings.

You can optionally specify a secondary virtual network interface card (VNIC) and block volumes to attach to the instances that are created from an instance configuration. To do this, create the instance configuration by providing a list of configuration settings.

Limitations and Considerations

  • If you use an existing instance as a template to create an instance configuration, be aware of the following information:

    • The instance configuration does not include any information from the instance's boot volume, such as installed applications, binaries, and files on the instance. To create an instance configuration that includes the custom setup from an instance, you must first create a custom image from the instance and then use the custom image to create a new instance. Finally, create the instance configuration based on the instance that you created from the custom image.
    • The instance configuration does not include the contents of any block volumes that are attached to the instance.
    • Any instances created from the instance configuration are placed in the same compartment as the instance that was used as the basis for the instance configuration, regardless of the compartment of the instance configuration. For example, an instance in compartment A is used to create an instance configuration. For example, you use an instance in compartment A as the basis to create an instance configuration. You place the instance configuration in compartment B. Any instances created using that instance configuration will be located in compartment A, the same compartment as the original instance.

  • If you provide a list of configuration settings to create an instance configuration, be aware of the following information:

    • When you create an instance from the instance configuration, many of the settings defined in the instance configuration cannot be changed. For example, the availability domain, compartment, image, shape, and subnet cannot be changed when you create the instance.

    • Many of the settings for creating instance configurations are the same as the settings in the create compute instance workflow. However, not all settings are available for instance configurations. For some settings, you can provide a value when you create an instance from the instance configuration.

      • For capacity type, you can't select preemptible capacity when creating the instance configuration. However, if you select on-demand capacity for the instance configuration, instances created from the instance configuration can use preemptible capacity.
      • Shielded instance configuration options aren't available when you create the instance configuration. However, if you select a shape and image in the instance configuration that are compatible with shielded instances, you can create shielded instances from the instance configuration.
      • When you create the instance configuration, for boot volumes, you don't have the option to encrypt the volume with a key that you manage, but you can select this option when you create an instance from the instance configuration.
      • You can't configure live migration options on the instance configuration. However, if the options selected in the instance configuration support live migration, you can configure live migration when you create instances from the instance configuration.

    • For Linux instances: Using Secure Shell (SSH) keys with instance configurations:

      • If you add an SSH key when you create the instance configuration, that SSH key must be used to connect to all instances created from the instance configuration.
      • After you create the instance configuration, you cannot change the SSH key.
      • If you create an instance configuration without an SSH key, you can add an SSH key to individual instances created from the instance configuration.
      • If you use the instance configuration to create an instance pool, you should add an SSH key when you create the instance configuration.
  • When an instance pool creates instances in the pool based on an instance configuration, the pool's settings define the availability domain and subnet, regardless of the settings in the instance configuration.
  • If the instance configuration is associated with a capacity reservation, that reservation is automatically applied to any instances or instance pools created using that instance configuration. As long as sufficient capacity is available, when the instances launch, they use capacity from the associated reservation.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: For a typical policy that gives access to instance pools and instance configurations, see Let users manage Compute instance configurations, instance pools, and cluster networks.

Tagging Resources

You can add tags to your resources to help you organize them according to your business needs. You can add tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.
To manage tags for an instance configuration
  1. Open the navigation menu and click Compute. Under Compute, click Instance Configurations.
  2. Click the instance configuration that you're interested in.
  3. Click the Tags tab to view or edit the existing tags. Or click More Actions, and then click Add Tags to add new ones.

For more information, see Resource Tags.

Propagation of Tagging on Resources

OCI services propagate all of a primary resource's freeform tags and defined tags to secondary resources when both resources support the type of tags. For example, when instance pools create instances, the tags from the instance pool and the instance configuration propagate to the resources created. Resources include instances created by the pool, primary VNICs, secondary VNICs, and boot volumes and block volumes created with the instance. Tags are not propagated to existing instances that are attached to the pool.

Sometimes, the tags on the instance pool, the instance configuration, and the resources might conflict. In those cases, the tag values from the instance configuration are propagated to the resources, overwriting both the instance pool and resource tag values. If the instance pool and resource tags conflict and the instance configuration doesn't have a tag, the tag values from the instance pool are propagated to the resources, overwriting the resource tag values.

Prerequisites

If you're providing a list of configuration settings, prepare these things:

  • A virtual cloud network (VCN) in which to launch the instances that are created from the instance configuration. For information about setting up cloud networks, see Networking.
  • For Linux instances: If you want to use your own SSH key to connect using SSH to the instances that are created from the instance configuration, you need the public key from the SSH key pair that you plan to use. The key must be in OpenSSH format. For more information, see Managing Key Pairs on Linux Instances.

  • If you want to launch instances from the instance configuration using a host capacity type other than on-demand capacity, prepare the capacity:

    • To launch an instance and have it count against a capacity reservation, you must have a capacity reservation in the same availability domain as the instance.
    • To place an instance on a dedicated virtual machine host, you must have a dedicated virtual machine host in the same availability domain and fault domain that you want to launch the instance in.

    The capacity types are mutually exclusive.

If you want to attach block volumes to the instances that are created from the instance configuration, do one of the following things:

Using the Console

When you create an instance configuration, you can either use an existing compute instance as a template, or you can provide a list of configuration settings.

To create an instance configuration using an existing instance as a template

  1. Open the navigation menu and click Compute. Under Compute, click Instances.
  2. Click the instance whose image you want to use as a template to create the instance configuration.
  3. Click More Actions, and then click Create instance configuration.
  4. Select the compartment you want to create the instance configuration in.
  5. Specify a name for the instance configuration. It doesn't have to be unique, and you can change it later. Avoid entering confidential information.
  6. Show tagging options: Optionally, you can add tags. If you have permissions to create a resource, you also have permissions to add free-form tags to that resource. To add a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether you should add tags, skip this option (you can add tags later) or ask your administrator.
  7. Click Create instance configuration.

To create an instance configuration by providing a list of settings

  1. Open the navigation menu and click Compute. Under Compute, click Instance Configurations.
  2. Click Create instance configuration.
  3. Specify a name for the instance configuration. It doesn't have to be unique, and you can change it later. Avoid entering confidential information.
  4. Select the compartment you want to create the instance configuration in.
  5. Show tagging options: Tags to add to the instance configuration. Optionally, you can add tags. If you have permissions to create a resource, you also have permissions to add free-form tags to that resource. To add a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether you should add tags, skip this option (you can add tags later) or ask your administrator.
  6. In the Compartment to create instances in list, select the compartment where you want to place the instances that are created from this instance configuration.

  7. Specify the Placement, Image and shape, and Networking details for the instances that are created from this instance configuration.

    For more information about the settings in these sections, see Creating an Instance.

    Note

    For instance configurations, for Capacity type, Preemptible capacity isn't an option. However, if you select On-demand capacity for the instance configuration, instances created from this instance configuration can use preemptible capacity.

  8. If you want to create a secondary VNIC to attach to the instances that are created from this instance configuration, in the Networking section, click Create additional VNIC. Then, specify the configuration details for the secondary VNIC.

    For more information about the settings in this section, see To create and attach a secondary VNIC.

  9. For Linux instances: In the Add SSH keys section, generate an SSH key pair or upload your own public key for the instances that are created from this instance configuration.

    Important

    • If you add an SSH key when you create the instance configuration, that SSH key must be used to connect to all instances created from the instance configuration.
    • After you create the instance configuration, you cannot change the SSH key.
    • If you create an instance configuration without an SSH key, you can add an SSH key to individual instances created from the instance configuration.
    • If you use the instance configuration to create an instance pool, you should add the SSH key when you create the instance configuration.

    For more information about the settings in this section, see Creating an Instance. For more information about SSH keys, see Managing Key Pairs on Linux Instances.

    Caution

    Anyone who has access to the private key can connect to the instance. Store the private key in a secure location.

  10. Specify the Boot volume details for the instances that are created from this instance configuration.

    For more information about the settings in this section, see Creating an Instance.

    Note

    When you create the instance configuration, you don't have the option to encrypt the volume with a key that you manage, but you can select this option when you create an instance from the instance configuration.

  11. If you want to attach block volumes to the instances that are created from this instance configuration, in the Block volumes section, click Attach block volume. Then, specify the configuration details for the block volume.

    For more information about the settings in this section, see Using the Console to Attach a Volume.

  12. To configure advanced settings for the instances that are created from this instance configuration, such as the tags that are added to the instances, click Show advanced options. Then, specify the settings.

    For more information about the settings in this section, see Creating an Instance.

  13. Click Create.

Using the CLI

To create an instance configuration using the CLI, open a command prompt and run the instance-configuration create command:

oci compute-management instance-configuration create --compartment-id <COMPARTMENT_OCID> --instance-details <file://path/to/file.json>

<file://path/to/file.json> is the path to a JSON file that defines the instance details. For information about how to generate an example of the JSON file, see Advanced JSON Options.

For information about using the CLI, see Command Line Interface (CLI).