oci_core_instance

This resource provides the Instance resource in Oracle Cloud Infrastructure Core service.

Creates a new instance in the specified compartment and the specified availability domain. For general information about instances, see Overview of the Compute Service.

For information about access control and compartments, see Overview of the IAM Service.

For information about availability domains, see Regions and Availability Domains. To get a list of availability domains, use the ListAvailabilityDomains operation in the Identity and Access Management Service API.

All Oracle Cloud Infrastructure resources, including instances, get an Oracle-assigned, unique ID called an Oracle Cloud Identifier (OCID). When you create a resource, you can find its OCID in the response. You can also retrieve a resource's OCID by using a List API operation on that resource type, or by viewing the resource in the Console.

To launch an instance using an image or a boot volume use the sourceDetails parameter in LaunchInstanceDetails.

When you launch an instance, it is automatically attached to a virtual network interface card (VNIC), called the primary VNIC. The VNIC has a private IP address from the subnet's CIDR. You can either assign a private IP address of your choice or let Oracle automatically assign one. You can choose whether the instance has a public IP address. To retrieve the addresses, use the ListVnicAttachments operation to get the VNIC ID for the instance, and then call GetVnic with the VNIC ID.

You can later add secondary VNICs to an instance. For more information, see Virtual Network Interface Cards (VNICs).

To launch an instance from a Marketplace image listing, you must provide the image ID of the listing resource version that you want, but you also must subscribe to the listing before you try to launch the instance. To subscribe to the listing, use the GetAppCatalogListingAgreements operation to get the signature for the terms of use agreement for the desired listing resource version. Then, call CreateAppCatalogSubscription with the signature. To get the image ID for the LaunchInstance operation, call GetAppCatalogListingResourceVersion.

To determine whether capacity is available for a specific shape before you create an instance, use the CreateComputeCapacityReport operation.

Example Usage

resource "oci_core_instance" "test_instance" {
    #Required
    availability_domain = var.instance_availability_domain
    compartment_id = var.compartment_id
    shape = var.instance_shape

    #Optional
    agent_config {

        #Optional
        are_all_plugins_disabled = var.instance_agent_config_are_all_plugins_disabled
        is_management_disabled = var.instance_agent_config_is_management_disabled
        is_monitoring_disabled = var.instance_agent_config_is_monitoring_disabled
        plugins_config {
            #Required
            desired_state = var.instance_agent_config_plugins_config_desired_state
            name = var.instance_agent_config_plugins_config_name
        }
    }
    availability_config {

        #Optional
        is_live_migration_preferred = var.instance_availability_config_is_live_migration_preferred
        recovery_action = var.instance_availability_config_recovery_action
    }
    cluster_placement_group_id = oci_identity_group.test_group.id
    compute_cluster_id = oci_core_compute_cluster.test_compute_cluster.id
    create_vnic_details {

        #Optional
        assign_ipv6ip = var.instance_create_vnic_details_assign_ipv6ip
        assign_private_dns_record = var.instance_create_vnic_details_assign_private_dns_record
        assign_public_ip = var.instance_create_vnic_details_assign_public_ip
        defined_tags = {"Operations.CostCenter"= "42"}
        display_name = var.instance_create_vnic_details_display_name
        freeform_tags = {"Department"= "Finance"}
        hostname_label = var.instance_create_vnic_details_hostname_label
        ipv6address_ipv6subnet_cidr_pair_details = var.instance_create_vnic_details_ipv6address_ipv6subnet_cidr_pair_details
        nsg_ids = var.instance_create_vnic_details_nsg_ids
        private_ip = var.instance_create_vnic_details_private_ip
        skip_source_dest_check = var.instance_create_vnic_details_skip_source_dest_check
        subnet_id = oci_core_subnet.test_subnet.id
        vlan_id = oci_core_vlan.test_vlan.id
    }
    dedicated_vm_host_id = oci_core_dedicated_vm_host.test_dedicated_vm_host.id
    defined_tags = {"Operations.CostCenter"= "42"}
    display_name = var.instance_display_name
    extended_metadata = {
        some_string = "stringA"
        nested_object = "{\"some_string\": \"stringB\", \"object\": {\"some_string\": \"stringC\"}}"
    }
    fault_domain = var.instance_fault_domain
    freeform_tags = {"Department"= "Finance"}
    hostname_label = var.instance_hostname_label
    instance_configuration_id = oci_core_instance_configuration.test_instance_configuration.id
    instance_options {

        #Optional
        are_legacy_imds_endpoints_disabled = var.instance_instance_options_are_legacy_imds_endpoints_disabled
    }
    ipxe_script = var.instance_ipxe_script
    is_pv_encryption_in_transit_enabled = var.instance_is_pv_encryption_in_transit_enabled
    launch_options {

        #Optional
        boot_volume_type = var.instance_launch_options_boot_volume_type
        firmware = var.instance_launch_options_firmware
        is_consistent_volume_naming_enabled = var.instance_launch_options_is_consistent_volume_naming_enabled
        is_pv_encryption_in_transit_enabled = var.instance_launch_options_is_pv_encryption_in_transit_enabled
        network_type = var.instance_launch_options_network_type
        remote_data_volume_type = var.instance_launch_options_remote_data_volume_type
    }
    launch_volume_attachments {
        #Required
        type = var.instance_launch_volume_attachments_type

        #Optional
        device = var.instance_launch_volume_attachments_device
        display_name = var.instance_launch_volume_attachments_display_name
        encryption_in_transit_type = var.instance_launch_volume_attachments_encryption_in_transit_type
        is_agent_auto_iscsi_login_enabled = var.instance_launch_volume_attachments_is_agent_auto_iscsi_login_enabled
        is_read_only = var.instance_launch_volume_attachments_is_read_only
        is_shareable = var.instance_launch_volume_attachments_is_shareable
        launch_create_volume_details {
            #Required
            size_in_gbs = var.instance_launch_volume_attachments_launch_create_volume_details_size_in_gbs
            volume_creation_type = var.instance_launch_volume_attachments_launch_create_volume_details_volume_creation_type

            #Optional
            compartment_id = var.compartment_id
            display_name = var.instance_launch_volume_attachments_launch_create_volume_details_display_name
            kms_key_id = oci_kms_key.test_key.id
            vpus_per_gb = var.instance_launch_volume_attachments_launch_create_volume_details_vpus_per_gb
        }
        use_chap = var.instance_launch_volume_attachments_use_chap
        volume_id = oci_core_volume.test_volume.id
    }
    metadata = var.instance_metadata
    platform_config {
        #Required
        type = var.instance_platform_config_type

        #Optional
        are_virtual_instructions_enabled = var.instance_platform_config_are_virtual_instructions_enabled
        config_map = var.instance_platform_config_config_map
        is_access_control_service_enabled = var.instance_platform_config_is_access_control_service_enabled
        is_input_output_memory_management_unit_enabled = var.instance_platform_config_is_input_output_memory_management_unit_enabled
        is_measured_boot_enabled = var.instance_platform_config_is_measured_boot_enabled
        is_memory_encryption_enabled = var.instance_platform_config_is_memory_encryption_enabled
        is_secure_boot_enabled = var.instance_platform_config_is_secure_boot_enabled
        is_symmetric_multi_threading_enabled = var.instance_platform_config_is_symmetric_multi_threading_enabled
        is_trusted_platform_module_enabled = var.instance_platform_config_is_trusted_platform_module_enabled
        numa_nodes_per_socket = var.instance_platform_config_numa_nodes_per_socket
        percentage_of_cores_enabled = var.instance_platform_config_percentage_of_cores_enabled
    }
    preemptible_instance_config {
        #Required
        preemption_action {
            #Required
            type = var.instance_preemptible_instance_config_preemption_action_type

            #Optional
            preserve_boot_volume = var.instance_preemptible_instance_config_preemption_action_preserve_boot_volume
        }
    }
    shape = var.instance_shape
    shape_config {

        #Optional
        baseline_ocpu_utilization = var.instance_shape_config_baseline_ocpu_utilization
        memory_in_gbs = var.instance_shape_config_memory_in_gbs
        nvmes = var.instance_shape_config_nvmes
        ocpus = var.instance_shape_config_ocpus
        vcpus = var.instance_shape_config_vcpus
    }
    source_details {
        #Required
        source_id = oci_core_image.test_image.id
        source_type = "image"

        #Optional
        boot_volume_size_in_gbs = var.instance_source_details_boot_volume_size_in_gbs
        boot_volume_vpus_per_gb = var.instance_source_details_boot_volume_vpus_per_gb
        instance_source_image_filter_details {
            #Required
            compartment_id = var.compartment_id

            #Optional
            defined_tags_filter = var.instance_source_details_instance_source_image_filter_details_defined_tags_filter
            operating_system = var.instance_source_details_instance_source_image_filter_details_operating_system
            operating_system_version = var.instance_source_details_instance_source_image_filter_details_operating_system_version
        }
        kms_key_id = oci_kms_key.test_key.id
    }
    preserve_boot_volume = false
}

Argument Reference

The following arguments are supported:

md5-02a0663d91521a542f33c7239e40e46c
**Getting Metadata on the Instance**

To get information about your instance, connect to the instance using SSH and issue any of the following GET requests:
md5-5b54225d49215f5b107a7ea366cf3b51
You'll get back a response that includes all the instance information; only the metadata information; or the metadata information for the specified key name, respectively.

The combined size of the `metadata` and `extendedMetadata` objects can be a maximum of 32,000 bytes.

**Note:** Both the 'user_data' and 'ssh_authorized_keys' fields cannot be changed after an instance has launched. Any request which updates, removes, or adds either of these fields will be rejected. You must provide the same values for 'user_data' and 'ssh_authorized_keys' that already exist on the instance.
* `platform_config` - (Optional) (Updatable only for VM's) The platform configuration requested for the instance.
If you provide the parameter, the instance is created with the platform configuration that you specify. For any values that you omit, the instance uses the default configuration values for the `shape` that you specify. If you don't provide the parameter, the default values for the `shape` are used.

Each shape only supports certain configurable values. If the values that you provide are not valid for the specified `shape`, an error is returned.

For more information about shielded instances, see [Shielded Instances](https://docs.cloud.oracle.com/iaas/Content/Compute/References/shielded-instances.htm).

For more information about BIOS settings for bare metal instances, see [BIOS Settings for Bare Metal Instances](https://docs.cloud.oracle.com/iaas/Content/Compute/References/bios-settings.htm). 
* `are_virtual_instructions_enabled` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | GENERIC_BM) Whether virtualization instructions are available. For example, Secure Virtual Machine for AMD shapes or VT-x for Intel shapes. 
* `config_map` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | GENERIC_BM | INTEL_ICELAKE_BM | INTEL_SKYLAKE_BM) Instance Platform Configuration Configuration Map for flexible setting input. 
* `is_access_control_service_enabled` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | GENERIC_BM) Whether the Access Control Service is enabled on the instance. When enabled, the platform can enforce PCIe device isolation, required for VFIO device pass-through. 
* `is_input_output_memory_management_unit_enabled` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | GENERIC_BM | INTEL_ICELAKE_BM | INTEL_SKYLAKE_BM) Whether the input-output memory management unit is enabled. 
* `is_measured_boot_enabled` - (Optional) Whether the Measured Boot feature is enabled on the instance. 
* `is_memory_encryption_enabled` - (Optional) Whether the instance is a confidential instance. If this value is `true`, the instance is a confidential instance. The default value is `false`. 
* `is_secure_boot_enabled` - (Optional) Whether Secure Boot is enabled on the instance. 
* `is_symmetric_multi_threading_enabled` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | AMD_VM | GENERIC_BM | INTEL_ICELAKE_BM | INTEL_SKYLAKE_BM | INTEL_VM) (Updatable only for INTEL_VM and AMD_VM) Whether symmetric multithreading is enabled on the instance. Symmetric multithreading is also called simultaneous multithreading (SMT) or Intel Hyper-Threading.

    Intel and AMD processors have two hardware execution threads per core (OCPU). SMT permits multiple independent threads of execution, to better use the resources and increase the efficiency of the CPU. When multithreading is disabled, only one thread is permitted to run on each core, which can provide higher or more predictable performance for some workloads. 
* `is_trusted_platform_module_enabled` - (Optional) Whether the Trusted Platform Module (TPM) is enabled on the instance. 
* `numa_nodes_per_socket` - (Applicable when type=AMD_MILAN_BM | AMD_MILAN_BM_GPU | AMD_ROME_BM | AMD_ROME_BM_GPU | GENERIC_BM | INTEL_ICELAKE_BM | INTEL_SKYLAKE_BM) The number of NUMA nodes per socket (NPS). 
* `percentage_of_cores_enabled` - (Applicable when type=AMD_MILAN_BM | AMD_ROME_BM | GENERIC_BM | INTEL_ICELAKE_BM | INTEL_SKYLAKE_BM) The percentage of cores enabled. Value must be a multiple of 25%. If the requested percentage results in a fractional number of cores, the system rounds up the number of cores across processors and provisions an instance with a whole number of cores.

    If the applications that you run on the instance use a core-based licensing model and need fewer cores than the full size of the shape, you can disable cores to reduce your licensing costs. The instance itself is billed for the full shape, regardless of whether all cores are enabled. 
* `type` - (Required) The type of platform being configured.
* `preemptible_instance_config` - (Optional) Configuration options for preemptible instances. * `preemption_action` - (Required) The action to run when the preemptible instance is interrupted for eviction. * `preserve_boot_volume` - (Optional) Whether to preserve the boot volume that was used to launch the preemptible instance when the instance is terminated. Defaults to false if not specified. * `type` - (Required) The type of action to run when the instance is interrupted for eviction. md5-8674bf6894043e51e721f4a1e1b07e29

For volumes with the auto-tuned performance feature enabled, this is set to the default (minimum) VPUs/GB.

  • instance_source_image_filter_details - (Applicable when source_type=image) These are the criteria for selecting an image. This is required if imageId is not specified.

  • kms_key_id - (Applicable when source_type=image) (Updatable) The OCID of the Vault service key to assign as the master encryption key for the boot volume.
  • source_id - (Required) (Updatable) The OCID of the boot volume used to boot the instance.
  • source_type - (Required) (Updatable) The source type for the instance. Use image when specifying the image OCID. Use bootVolume when specifying the boot volume OCID.
  • is_preserve_boot_volume_enabled - (Optional) (Updatable) Whether to preserve the boot volume that was previously attached to the instance after a successful replacement of that boot volume.
  • subnet_id - (Optional) Deprecated. Instead use subnetId in CreateVnicDetails. At least one of them is required; if you provide both, the values must match.
  • state - (Optional) (Updatable) The target state for the instance. Could be set to RUNNING or STOPPED.
  • * IMPORTANT * Any change to a property that does not support update will force the destruction and recreation of the resource with the new property values

    Attributes Reference

    The following attributes are exported:

    Timeouts

    The timeouts block allows you to specify timeouts for certain operations: * create - (Defaults to 45 minutes), when creating the Instance * update - (Defaults to 45 minutes), when updating the Instance * delete - (Defaults to 75 minutes), when destroying the Instance

    Import

    Instances can be imported using the id, e.g.

    $ terraform import oci_core_instance.test_instance "id"