Creating an Instance Configuration

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 creating individual instances that aren't part of a pool.

When you create an instance configuration, you can 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. Then, 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 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, 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.

Before You Begin

If you're providing a list of configuration settings, prepare the following items:

  • Set up 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) 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.
  • To launch instances from the instance configuration by 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.

To attach block volumes to the instances that are created from the instance configuration, perform one of the following actions:

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

    Create an Instance Configuration Using an Existing Instance as a Template

    1. On the Compute list page, select the instance that you want to work with. If you need help finding the list page, see Listing Instances.
    2. Select an instance.
    3. Select the option you see:
      • Select Actions then More actions then Create instance configuration.
      • Select More actions then Create instance configuration.
    4. Select the compartment that 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. To add tags to the instance configuration, select Show tagging options or Tagging and enter the tagging values.

      If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.

    7. Select Create instance configuration.

    Create an Instance Configuration by Providing a List of Settings

    Important

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

    1. Basic Information

    • Navigate to the Instance Configurations list page. If you need help finding the list page, see Listing Instance Configurations
    • Select Create instance configuration.
    • Instance configuration information
      • Name: Specify a name for the instance configuration. It doesn't have to be unique, and you can change it later. Avoid entering confidential information.
      • Compartment: Select the compartment that you want to create the instance configuration in.
      • Compartment to create instances in: Select the compartment where you want to place instances created from this instance configuration.
      • Select the option you see:
        • Tagging
        • Show tagging options

        Enter the tagging values. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.

    • Placement
      • Select an Availability domain
      • Configure Advanced options. For example, Capacity type or Fault domain
    • Image and Shape
      • Select an Image.
      • Select a Shape.
      • For Advanced Options configure:
        • Management
        • Tagging
        • Security attributes
        • Availability configuration
        • Oracle Cloud Agent
    • Select Next.

    2. Security

    Configure the security options if they are available.

    • Shielded instances
    • Confidential computing

    Select Next.

    3. Networking

    • Configure the Primary VNIC section. Specify the details for the instances that are created from this instance configuration.
    • Configure Advanced options, for example:
      • DNS
      • SSH keys
      • Secondary VNIC
    • Select Next.

    4. Storage

    • Specify the Boot volume details for the instances that are created from this instance configuration.
    • Block volumes

      To attach block volumes to the instances that are created from this instance configuration, select Attach block volume. Then, specify the configuration details for the block volume.

    • Select Create.

    Review

    • Review your configuration options. Use the Previous button to go back and adjust any settings.
    • Select Create.
  • 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).

  • For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

    Use the CreateInstanceConfiguration operation to create an instance configuration.