oracle.oci.oci_compute_instance – Manage an Instance resource in Oracle Cloud Infrastructure

Note

This plugin is part of the oracle.oci collection (version 5.3.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install oracle.oci.

To use it in a playbook, specify: oracle.oci.oci_compute_instance.

New in version 2.9.0: of oracle.oci

Synopsis

  • This module allows the user to create, update and delete an Instance resource in Oracle Cloud Infrastructure

  • For state=present, 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 L(Virtual Network Interface Cards (VNICs),https://docs.cloud.oracle.com/iaas/Content/Network/Tasks/managingVNICs.htm).

  • 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.

  • This resource has the following action operations in the oracle.oci.oci_compute_instance_actions module: stop, start, softreset, reset, softstop, senddiagnosticinterrupt, diagnosticreboot, rebootmigrate.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter Choices/Defaults Comments
agent_config
dictionary
This parameter is updatable.
are_all_plugins_disabled
boolean
    Choices:
  • no
  • yes
Whether Oracle Cloud Agent can run all the available plugins. This includes the management and monitoring plugins.
To get a list of available plugins, use the ListInstanceagentAvailablePlugins operation in the Oracle Cloud Agent API. For more information about the available plugins, see Managing Plugins with Oracle Cloud Agent.
This parameter is updatable.
is_management_disabled
boolean
    Choices:
  • no
  • yes
Whether Oracle Cloud Agent can run all the available management plugins. Default value is false (management plugins are enabled).
These are the management plugins: OS Management Service Agent and Compute Instance Run Command.
The management plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
- If `isManagementDisabled` is true, all of the management plugins are disabled, regardless of the per-plugin configuration. - If `isManagementDisabled` is false, all of the management plugins are enabled. You can optionally disable individual management plugins by providing a value in the `pluginsConfig` object.
This parameter is updatable.
is_monitoring_disabled
boolean
    Choices:
  • no
  • yes
Whether Oracle Cloud Agent can gather performance metrics and monitor the instance using the monitoring plugins. Default value is false (monitoring plugins are enabled).
These are the monitoring plugins: Compute Instance Monitoring and Custom Logs Monitoring.
The monitoring plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
- If `isMonitoringDisabled` is true, all of the monitoring plugins are disabled, regardless of the per-plugin configuration. - If `isMonitoringDisabled` is false, all of the monitoring plugins are enabled. You can optionally disable individual monitoring plugins by providing a value in the `pluginsConfig` object.
This parameter is updatable.
plugins_config
list / elements=dictionary
The configuration of plugins associated with this instance.
desired_state
string / required
    Choices:
  • ENABLED
  • DISABLED
Whether the plugin should be enabled or disabled.
To enable the monitoring and management plugins, the `isMonitoringDisabled` and `isManagementDisabled` attributes must also be set to false.
name
string / required
The plugin name. To get a list of available plugins, use the ListInstanceagentAvailablePlugins operation in the Oracle Cloud Agent API. For more information about the available plugins, see Managing Plugins with Oracle Cloud Agent.
api_user
string
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See config_file_location). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint
string
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See config_file_location). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file
string
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See config_file_location). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided.
api_user_key_pass_phrase
string
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location).
auth_purpose
string
    Choices:
  • service_principal
The auth purpose which can be used in conjunction with 'auth_type=instance_principal'. The default auth_purpose for instance_principal is None.
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
  • security_token
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
availability_config
dictionary
This parameter is updatable.
is_live_migration_preferred
boolean
    Choices:
  • no
  • yes
Whether to live migrate supported VM instances to a healthy physical VM host without disrupting running instances during infrastructure maintenance events. If null, Oracle chooses the best option for migrating the VM during infrastructure maintenance events.
This parameter is updatable.
recovery_action
string
    Choices:
  • RESTORE_INSTANCE
  • STOP_INSTANCE
The lifecycle state for an instance when it is recovered after infrastructure maintenance. * `RESTORE_INSTANCE` - The instance is restored to the lifecycle state it was in before the maintenance event. If the instance was running, it is automatically rebooted. This is the default action when a value is not set. * `STOP_INSTANCE` - The instance is recovered in the stopped state.
This parameter is updatable.
availability_domain
string
The availability domain of the instance.
Example: `Uocm:PHX-AD-1`
Required for create using state=present.
capacity_reservation_id
string
The OCID of the compute capacity reservation this instance is launched under. You can opt out of all default reservations by specifying an empty string as input for this field. For more information, see Capacity Reservations.
This parameter is updatable.
cert_bundle
string
The full path to a CA certificate bundle to be used for SSL verification. This will override the default CA certificate bundle. If not set, then the value of the OCI_ANSIBLE_CERT_BUNDLE variable, if any, is used.
compartment_id
string
The OCID of the compartment.
Required for create using state=present.
Required for update when environment variable OCI_USE_NAME_AS_IDENTIFIER is set.
Required for delete when environment variable OCI_USE_NAME_AS_IDENTIFIER is set.
compute_cluster_id
string
The OCID of the compute cluster that the instance will be created in.
config_file_location
string
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name
string
The profile to load from the config file referenced by config_file_location. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location.
create_vnic_details
dictionary
assign_private_dns_record
boolean
    Choices:
  • no
  • yes
Whether the VNIC should be assigned a DNS record. If set to false, there will be no DNS record registration for the VNIC. If set to true, the DNS record will be registered. The default value is true.
If you specify a `hostnameLabel`, then `assignPrivateDnsRecord` must be set to true.
assign_public_ip
boolean
    Choices:
  • no
  • yes
Whether the VNIC should be assigned a public IP address. Defaults to whether the subnet is public or private. If not set and the VNIC is being created in a private subnet (that is, where `prohibitPublicIpOnVnic` = true in the Subnet), then no public IP address is assigned. If not set and the subnet is public (`prohibitPublicIpOnVnic` = false), then a public IP address is assigned. If set to true and `prohibitPublicIpOnVnic` = true, an error is returned.
**Note:** This public IP address is associated with the primary private IP on the VNIC. For more information, see IP Addresses.
**Note:** There's a limit to the number of public IPs a VNIC or instance can have. If you try to create a secondary VNIC with an assigned public IP for an instance that has already reached its public IP limit, an error is returned. For information about the public IP limits, see Public IP Addresses.
Example: `false`
If you specify a `vlanId`, then `assignPublicIp` must be set to false. See Vlan.
defined_tags
dictionary
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Example: `{"Operations": {"CostCenter": "42"}}`
display_name
string
A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.

aliases: name
freeform_tags
dictionary
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags.
Example: `{"Department": "Finance"}`
hostname_label
string
The hostname for the VNIC's primary private IP. Used for DNS. The value is the hostname portion of the primary private IP's fully qualified domain name (FQDN) (for example, `bminstance1` in FQDN `bminstance1.subnet123.vcn1.oraclevcn.com`). Must be unique across all VNICs in the subnet and comply with RFC 952 and RFC 1123. The value appears in the Vnic object and also the PrivateIp object returned by ListPrivateIps and GetPrivateIp.
For more information, see DNS in Your Virtual Cloud Network.
When launching an instance, use this `hostnameLabel` instead of the deprecated `hostnameLabel` in LaunchInstanceDetails. If you provide both, the values must match.
Example: `bminstance1`
If you specify a `vlanId`, the `hostnameLabel` cannot be specified. VNICs on a VLAN can not be assigned a hostname. See Vlan.
nsg_ids
list / elements=string
A list of the OCIDs of the network security groups (NSGs) to add the VNIC to. For more information about NSGs, see NetworkSecurityGroup.
If a `vlanId` is specified, the `nsgIds` cannot be specified. The `vlanId` indicates that the VNIC will belong to a VLAN instead of a subnet. With VLANs, all VNICs in the VLAN belong to the NSGs that are associated with the VLAN. See Vlan.
private_ip
string
A private IP address of your choice to assign to the VNIC. Must be an available IP address within the subnet's CIDR. If you don't specify a value, Oracle automatically assigns a private IP address from the subnet. This is the VNIC's *primary* private IP address. The value appears in the Vnic object and also the PrivateIp object returned by ListPrivateIps and GetPrivateIp.
If you specify a `vlanId`, the `privateIp` cannot be specified. See Vlan.
Example: `10.0.3.3`
skip_source_dest_check
boolean
    Choices:
  • no
  • yes
Whether the source/destination check is disabled on the VNIC. Defaults to `false`, which means the check is performed. For information about why you would skip the source/destination check, see Using a Private IP as a Route Target.
If you specify a `vlanId`, the `skipSourceDestCheck` cannot be specified because the source/destination check is always disabled for VNICs in a VLAN. See Vlan.
Example: `true`
subnet_id
string
The OCID of the subnet to create the VNIC in. When launching an instance, use this `subnetId` instead of the deprecated `subnetId` in LaunchInstanceDetails. At least one of them is required; if you provide both, the values must match.
If you are an Oracle Cloud VMware Solution customer and creating a secondary VNIC in a VLAN instead of a subnet, provide a `vlanId` instead of a `subnetId`. If you provide both a `vlanId` and `subnetId`, the request fails.
vlan_id
string
Provide this attribute only if you are an Oracle Cloud VMware Solution customer and creating a secondary VNIC in a VLAN. The value is the OCID of the VLAN. See Vlan.
Provide a `vlanId` instead of a `subnetId`. If you provide both a `vlanId` and `subnetId`, the request fails.
dedicated_vm_host_id
string
The OCID of the dedicated virtual machine host to place the instance on.
defined_tags
dictionary
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Example: `{"Operations": {"CostCenter": "42"}}`
This parameter is updatable.
display_name
string
A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
Required for create, update, delete when environment variable OCI_USE_NAME_AS_IDENTIFIER is set.
This parameter is updatable when OCI_USE_NAME_AS_IDENTIFIER is not set.

aliases: name
extended_metadata
dictionary
Additional metadata key/value pairs that you provide. They serve the same purpose and functionality as fields in the `metadata` object.
They are distinguished from `metadata` fields in that these can be nested JSON objects (whereas `metadata` fields are string/string maps only).
The combined size of the `metadata` and `extendedMetadata` objects can be a maximum of 32,000 bytes.
This parameter is updatable.
fault_domain
string
A fault domain is a grouping of hardware and infrastructure within an availability domain. Each availability domain contains three fault domains. Fault domains let you distribute your instances so that they are not on the same physical hardware within a single availability domain. A hardware failure or Compute hardware maintenance that affects one fault domain does not affect instances in other fault domains.
If you do not specify the fault domain, the system selects one for you.
To get a list of fault domains, use the ListFaultDomains operation in the Identity and Access Management Service API.
Example: `FAULT-DOMAIN-1`
This parameter is updatable.
force_create
boolean
    Choices:
  • no ←
  • yes
Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation, and doesn't create the resource if it already exists. Setting this option to true, forcefully creates a copy of the resource, even if it already exists.This option is mutually exclusive with key_by.
freeform_tags
dictionary
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags.
Example: `{"Department": "Finance"}`
This parameter is updatable.
hostname_label
string
Deprecated. Instead use `hostnameLabel` in CreateVnicDetails. If you provide both, the values must match.
image_id
string
Deprecated. Use `sourceDetails` with InstanceSourceViaImageDetails source type instead. If you specify values for both, the values must match.
instance_configuration_id
string
The OCID of the Instance Configuration containing instance launch details. Any other fields supplied in this instance launch request will override the details stored in the Instance Configuration for this instance launch.
instance_id
string
The OCID of the instance.
Required for update using state=present when environment variable OCI_USE_NAME_AS_IDENTIFIER is not set.
Required for delete using state=absent when environment variable OCI_USE_NAME_AS_IDENTIFIER is not set.

aliases: id
instance_options
dictionary
This parameter is updatable.
are_legacy_imds_endpoints_disabled
boolean
    Choices:
  • no
  • yes
Whether to disable the legacy (/v1) instance metadata service endpoints. Customers who have migrated to /v2 should set this to true for added security. Default is false.
ipxe_script
string
This is an advanced option.
When a bare metal or virtual machine instance boots, the iPXE firmware that runs on the instance is configured to run an iPXE script to continue the boot process.
If you want more control over the boot process, you can provide your own custom iPXE script that will run when the instance boots. Be aware that the same iPXE script will run every time an instance boots, not only after the initial LaunchInstance call.
The default iPXE script connects to the instance's local boot volume over iSCSI and performs a network boot. If you use a custom iPXE script and want to network-boot from the instance's local boot volume over iSCSI the same way as the default iPXE script, use the following iSCSI IP address: 169.254.0.2, and boot volume IQN: iqn.2015-02.oracle.boot.
If your instance boot volume attachment type is paravirtualized, the boot volume is attached to the instance through virtio-scsi and no iPXE script is used. If your instance boot volume attachment type is paravirtualized and you use custom iPXE to network boot into your instance, the primary boot volume is attached as a data volume through virtio-scsi drive.
For more information about the Bring Your Own Image feature of Oracle Cloud Infrastructure, see Bring Your Own Image.
For more information about iPXE, see http://ipxe.org.
is_pv_encryption_in_transit_enabled
boolean
    Choices:
  • no
  • yes
Whether to enable in-transit encryption for the data volume's paravirtualized attachment. This field applies to both block volumes and boot volumes. The default value is false.
key_by
list / elements=string
The list of attributes of this resource which should be used to uniquely identify an instance of the resource. By default, all the attributes of a resource are used to uniquely identify a resource.
launch_options
dictionary
This parameter is updatable.
boot_volume_type
string
    Choices:
  • ISCSI
  • SCSI
  • IDE
  • VFIO
  • PARAVIRTUALIZED
Emulation type for the boot volume. * `ISCSI` - ISCSI attached block storage device. * `SCSI` - Emulated SCSI disk. * `IDE` - Emulated IDE disk. * `VFIO` - Direct attached Virtual Function storage. This is the default option for local data volumes on platform images. * `PARAVIRTUALIZED` - Paravirtualized disk. This is the default for boot volumes and remote block storage volumes on platform images.
This parameter is updatable.
firmware
string
    Choices:
  • BIOS
  • UEFI_64
Firmware used to boot VM. Select the option that matches your operating system. * `BIOS` - Boot VM using BIOS style firmware. This is compatible with both 32 bit and 64 bit operating systems that boot using MBR style bootloaders. * `UEFI_64` - Boot VM using UEFI style firmware compatible with 64 bit operating systems. This is the default for platform images.
is_consistent_volume_naming_enabled
boolean
    Choices:
  • no
  • yes
Whether to enable consistent volume naming feature. Defaults to false.
is_pv_encryption_in_transit_enabled
boolean
    Choices:
  • no
  • yes
Deprecated. Instead use `isPvEncryptionInTransitEnabled` in LaunchInstanceDetails.
This parameter is updatable.
network_type
string
    Choices:
  • E1000
  • VFIO
  • PARAVIRTUALIZED
Emulation type for the physical network interface card (NIC). * `E1000` - Emulated Gigabit ethernet controller. Compatible with Linux e1000 network driver. * `VFIO` - Direct attached Virtual Function network controller. This is the networking type when you launch an instance using hardware-assisted (SR-IOV) networking. * `PARAVIRTUALIZED` - VM instances launch with paravirtualized devices using VirtIO drivers.
This parameter is updatable.
remote_data_volume_type
string
    Choices:
  • ISCSI
  • SCSI
  • IDE
  • VFIO
  • PARAVIRTUALIZED
Emulation type for volume. * `ISCSI` - ISCSI attached block storage device. * `SCSI` - Emulated SCSI disk. * `IDE` - Emulated IDE disk. * `VFIO` - Direct attached Virtual Function storage. This is the default option for local data volumes on platform images. * `PARAVIRTUALIZED` - Paravirtualized disk. This is the default for boot volumes and remote block storage volumes on platform images.
metadata
dictionary
Custom metadata key/value pairs that you provide, such as the SSH public key required to connect to the instance.
A metadata service runs on every launched instance. The service is an HTTP endpoint listening on 169.254.169.254. You can use the service to:
* Provide information to Cloud-Init to be used for various system initialization tasks.
* Get information about the instance, including the custom metadata that you provide when you launch the instance.
**Providing Cloud-Init Metadata**
You can use the following metadata key names to provide information to Cloud-Init:
**"ssh_authorized_keys"** - Provide one or more public SSH keys to be included in the `~/.ssh/authorized_keys` file for the default user on the instance. Use a newline character to separate multiple keys. The SSH keys must be in the format necessary for the `authorized_keys` file, as shown in the example below.
**"user_data"** - Provide your own base64-encoded data to be used by Cloud-Init to run custom scripts or provide custom Cloud-Init configuration. For information about how to take advantage of user data, see the Cloud-Init Documentation.
**Metadata Example**
"metadata" : { "quake_bot_level" : "Severe", "ssh_authorized_keys" : "ssh-rsa <your_public_SSH_key>== rsa-key-20160227", "user_data" : "<your_public_SSH_key>==" } **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:
curl -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/ curl -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/metadata/ curl -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/metadata/<any-key-name>
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.
This parameter is updatable.
platform_config
dictionary
are_virtual_instructions_enabled
boolean
    Choices:
  • no
  • yes
Whether virtualization instructions are available. For example, Secure Virtual Machine for AMD shapes or VT-x for Intel shapes.
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_MILAN_BM_GPU', 'AMD_ROME_BM_GPU', 'AMD_ROME_BM']
is_access_control_service_enabled
boolean
    Choices:
  • no
  • yes
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.
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_MILAN_BM_GPU', 'AMD_ROME_BM_GPU', 'AMD_ROME_BM']
is_input_output_memory_management_unit_enabled
boolean
    Choices:
  • no
  • yes
Whether the input-output memory management unit is enabled.
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_MILAN_BM_GPU', 'AMD_ROME_BM_GPU', 'AMD_ROME_BM', 'INTEL_ICELAKE_BM']
is_measured_boot_enabled
boolean
    Choices:
  • no
  • yes
Whether the Measured Boot feature is enabled on the instance.
is_memory_encryption_enabled
boolean
    Choices:
  • no
  • yes
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
boolean
    Choices:
  • no
  • yes
Whether Secure Boot is enabled on the instance.
is_symmetric_multi_threading_enabled
boolean
    Choices:
  • no
  • yes
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.
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_MILAN_BM_GPU', 'AMD_ROME_BM_GPU', 'AMD_ROME_BM', 'INTEL_ICELAKE_BM']
is_trusted_platform_module_enabled
boolean
    Choices:
  • no
  • yes
Whether the Trusted Platform Module (TPM) is enabled on the instance.
numa_nodes_per_socket
string
    Choices:
  • NPS0
  • NPS1
  • NPS2
  • NPS4
The number of NUMA nodes per socket (NPS).
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_MILAN_BM_GPU', 'AMD_ROME_BM_GPU', 'AMD_ROME_BM', 'INTEL_ICELAKE_BM']
percentage_of_cores_enabled
integer
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.
Applicable when type is one of ['AMD_MILAN_BM', 'AMD_ROME_BM', 'INTEL_ICELAKE_BM']
type
string / required
    Choices:
  • AMD_ROME_BM_GPU
  • AMD_ROME_BM
  • INTEL_ICELAKE_BM
  • AMD_VM
  • INTEL_VM
  • INTEL_SKYLAKE_BM
  • AMD_MILAN_BM
  • AMD_MILAN_BM_GPU
The type of platform being configured.
preemptible_instance_config
dictionary
preemption_action
dictionary / required
preserve_boot_volume
boolean
    Choices:
  • no
  • yes
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
string / required
    Choices:
  • TERMINATE
The type of action to run when the instance is interrupted for eviction.
preserve_boot_volume
boolean
    Choices:
  • no
  • yes
Specifies whether to delete or preserve the boot volume when terminating an instance. When set to `true`, the boot volume is preserved. The default value is `false`.
realm_specific_endpoint_template_enabled
boolean
    Choices:
  • no
  • yes
Enable/Disable realm specific endpoint template for service client. By Default, realm specific endpoint template is disabled. If not set, then the value of the OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED variable, if any, is used.
region
string
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See config_file_location). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions.
shape
string
The shape of an instance. The shape determines the number of CPUs, amount of memory, and other resources allocated to the instance.
You can enumerate all available shapes by calling ListShapes.
This parameter is updatable.
shape_config
dictionary
This parameter is updatable.
baseline_ocpu_utilization
string
    Choices:
  • BASELINE_1_8
  • BASELINE_1_2
  • BASELINE_1_1
The baseline OCPU utilization for a subcore burstable VM instance. Leave this attribute blank for a non-burstable instance, or explicitly specify non-burstable with `BASELINE_1_1`.
The following values are supported: - `BASELINE_1_8` - baseline usage is 1/8 of an OCPU. - `BASELINE_1_2` - baseline usage is 1/2 of an OCPU. - `BASELINE_1_1` - baseline usage is an entire OCPU. This represents a non-burstable instance.
This parameter is updatable.
memory_in_gbs
float
The total amount of memory available to the instance, in gigabytes.
This parameter is updatable.
nvmes
integer
The number of NVMe drives to be used for storage. A single drive has 6.8 TB available.
This parameter is updatable.
ocpus
float
The total number of OCPUs available to the instance.
This parameter is updatable.
vcpus
integer
The total number of VCPUs available to the instance. This can be used instead of OCPUs, in which case the actual number of OCPUs will be calculated based on this value and the actual hardware. This must be a multiple of 2.
This parameter is updatable.
source_details
dictionary
boot_volume_id
string
The OCID of the boot volume used to boot the instance.
Required when source_type is 'bootVolume'
boot_volume_size_in_gbs
integer
The size of the boot volume in GBs. Minimum value is 50 GB and maximum value is 32,768 GB (32 TB).
Applicable when source_type is 'image'
boot_volume_vpus_per_gb
integer
The number of volume performance units (VPUs) that will be applied to this volume per GB, representing the Block Volume service's elastic performance options. See Block Volume Performance Levels for more information.
Allowed values:
* `10`: Represents Balanced option.
* `20`: Represents Higher Performance option.
* `30`-`120`: Represents the Ultra High Performance option.
For volumes with the auto-tuned performance feature enabled, this is set to the default (minimum) VPUs/GB.
Applicable when source_type is 'image'
image_id
string
The OCID of the image used to boot the instance.
Applicable when source_type is 'image'
instance_source_image_filter_details
dictionary
Applicable when source_type is 'image'
compartment_id
string / required
The OCID of the compartment containing images to search
Required when source_type is 'image'
defined_tags_filter
dictionary
Filter based on these defined tags. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Applicable when source_type is 'image'
operating_system
string
The image's operating system.
Example: `Oracle Linux`
Applicable when source_type is 'image'
operating_system_version
string
The image's operating system version.
Example: `7.2`
Applicable when source_type is 'image'
kms_key_id
string
The OCID of the Vault service key to assign as the master encryption key for the boot volume.
Applicable when source_type is 'image'
source_type
string / required
    Choices:
  • image
  • bootVolume
The source type for the instance. Use `image` when specifying the image OCID. Use `bootVolume` when specifying the boot volume OCID.
state
string
    Choices:
  • present ←
  • absent
The state of the Instance.
Use state=present to create or update an Instance.
Use state=absent to delete an Instance.
subnet_id
string
Deprecated. Instead use `subnetId` in CreateVnicDetails. At least one of them is required; if you provide both, the values must match.
tenancy
string
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See config_file_location). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm
time_maintenance_reboot_due
string
For a VM instance, resets the scheduled time that the instance will be reboot migrated for infrastructure maintenance, in the format defined by RFC3339. If the instance hasn't been rebooted after this date, Oracle reboots the instance within 24 hours of the time and date that maintenance is due.
To get the maximum possible date that a maintenance reboot can be extended, use GetInstanceMaintenanceReboot.
Regardless of how the instance is stopped, this flag is reset to empty as soon as the instance reaches the Stopped state.
To reboot migrate a bare metal instance, use the InstanceAction operation.
For more information, see Infrastructure Maintenance.
Example: `2018-05-25T21:10:29.600Z`
This parameter is updatable.
update_operation_constraint
string
    Choices:
  • ALLOW_DOWNTIME
  • AVOID_DOWNTIME
The parameter acts as a fail-safe to prevent unwanted downtime when updating a running instance. The default is ALLOW_DOWNTIME. * `ALLOW_DOWNTIME` - Compute might reboot the instance while updating the instance if a reboot is required. * `AVOID_DOWNTIME` - If the instance is in running state, Compute tries to update the instance without rebooting it. If the instance requires a reboot to be updated, an error is returned and the instance is not updated. If the instance is stopped, it is updated and remains in the stopped state.
This parameter is updatable.
wait
boolean
    Choices:
  • no
  • yes ←
Whether to wait for create or delete operation to complete.
wait_timeout
integer
Time, in seconds, to wait when wait=yes. Defaults to 1200 for most of the services but some services might have a longer wait timeout.

Examples

- name: Create instance
  oci_compute_instance:
    # required
    availability_domain: Uocm:PHX-AD-1
    compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"

    # optional
    create_vnic_details:
      # optional
      assign_public_ip: true
      assign_private_dns_record: true
      defined_tags: {'Operations': {'CostCenter': 'US'}}
      display_name: display_name_example
      freeform_tags: {'Department': 'Finance'}
      hostname_label: hostname_label_example
      nsg_ids: [ "nsg_ids_example" ]
      private_ip: private_ip_example
      skip_source_dest_check: true
      subnet_id: "ocid1.subnet.oc1..xxxxxxEXAMPLExxxxxx"
      vlan_id: "ocid1.vlan.oc1..xxxxxxEXAMPLExxxxxx"
    dedicated_vm_host_id: "ocid1.dedicatedvmhost.oc1..xxxxxxEXAMPLExxxxxx"
    compute_cluster_id: "ocid1.computecluster.oc1..xxxxxxEXAMPLExxxxxx"
    hostname_label: hostname_label_example
    image_id: "ocid1.image.oc1..xxxxxxEXAMPLExxxxxx"
    ipxe_script: ipxe_script_example
    preemptible_instance_config:
      # required
      preemption_action:
        # required
        type: TERMINATE

        # optional
        preserve_boot_volume: true
    source_details:
      # required
      source_type: image

      # optional
      boot_volume_size_in_gbs: 56
      image_id: "ocid1.image.oc1..xxxxxxEXAMPLExxxxxx"
      kms_key_id: "ocid1.kmskey.oc1..xxxxxxEXAMPLExxxxxx"
      boot_volume_vpus_per_gb: 56
      instance_source_image_filter_details:
        # required
        compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"

        # optional
        defined_tags_filter: null
        operating_system: operating_system_example
        operating_system_version: operating_system_version_example
    subnet_id: "ocid1.subnet.oc1..xxxxxxEXAMPLExxxxxx"
    is_pv_encryption_in_transit_enabled: true
    platform_config:
      # required
      type: AMD_ROME_BM_GPU

      # optional
      is_secure_boot_enabled: true
      is_trusted_platform_module_enabled: true
      is_measured_boot_enabled: true
      is_memory_encryption_enabled: true
      numa_nodes_per_socket: NPS0
      is_symmetric_multi_threading_enabled: true
      is_access_control_service_enabled: true
      are_virtual_instructions_enabled: true
      is_input_output_memory_management_unit_enabled: true
    instance_configuration_id: "ocid1.instanceconfiguration.oc1..xxxxxxEXAMPLExxxxxx"
    capacity_reservation_id: "ocid1.capacityreservation.oc1..xxxxxxEXAMPLExxxxxx"
    defined_tags: {'Operations': {'CostCenter': 'US'}}
    display_name: display_name_example
    freeform_tags: {'Department': 'Finance'}
    agent_config:
      # optional
      is_monitoring_disabled: true
      is_management_disabled: true
      are_all_plugins_disabled: true
      plugins_config:
      - # required
        name: name_example
        desired_state: ENABLED
    metadata: null
    extended_metadata: null
    shape: shape_example
    shape_config:
      # optional
      ocpus: 3.4
      vcpus: 56
      memory_in_gbs: 3.4
      baseline_ocpu_utilization: BASELINE_1_8
      nvmes: 56
    instance_options:
      # optional
      are_legacy_imds_endpoints_disabled: true
    fault_domain: FAULT-DOMAIN-1
    launch_options:
      # optional
      firmware: BIOS
      remote_data_volume_type: ISCSI
      is_consistent_volume_naming_enabled: true
      boot_volume_type: ISCSI
      network_type: E1000
      is_pv_encryption_in_transit_enabled: true
    availability_config:
      # optional
      is_live_migration_preferred: true
      recovery_action: RESTORE_INSTANCE

- name: Update instance
  oci_compute_instance:
    # required
    instance_id: "ocid1.instance.oc1..xxxxxxEXAMPLExxxxxx"

    # optional
    capacity_reservation_id: "ocid1.capacityreservation.oc1..xxxxxxEXAMPLExxxxxx"
    defined_tags: {'Operations': {'CostCenter': 'US'}}
    display_name: display_name_example
    freeform_tags: {'Department': 'Finance'}
    agent_config:
      # optional
      is_monitoring_disabled: true
      is_management_disabled: true
      are_all_plugins_disabled: true
      plugins_config:
      - # required
        name: name_example
        desired_state: ENABLED
    metadata: null
    extended_metadata: null
    shape: shape_example
    shape_config:
      # optional
      ocpus: 3.4
      vcpus: 56
      memory_in_gbs: 3.4
      baseline_ocpu_utilization: BASELINE_1_8
      nvmes: 56
    update_operation_constraint: ALLOW_DOWNTIME
    instance_options:
      # optional
      are_legacy_imds_endpoints_disabled: true
    fault_domain: FAULT-DOMAIN-1
    launch_options:
      # optional
      firmware: BIOS
      remote_data_volume_type: ISCSI
      is_consistent_volume_naming_enabled: true
      boot_volume_type: ISCSI
      network_type: E1000
      is_pv_encryption_in_transit_enabled: true
    availability_config:
      # optional
      is_live_migration_preferred: true
      recovery_action: RESTORE_INSTANCE
    time_maintenance_reboot_due: time_maintenance_reboot_due_example

- name: Update instance using name (when environment variable OCI_USE_NAME_AS_IDENTIFIER is set)
  oci_compute_instance:
    # required
    compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"
    display_name: display_name_example

    # optional
    capacity_reservation_id: "ocid1.capacityreservation.oc1..xxxxxxEXAMPLExxxxxx"
    defined_tags: {'Operations': {'CostCenter': 'US'}}
    freeform_tags: {'Department': 'Finance'}
    agent_config:
      # optional
      is_monitoring_disabled: true
      is_management_disabled: true
      are_all_plugins_disabled: true
      plugins_config:
      - # required
        name: name_example
        desired_state: ENABLED
    metadata: null
    extended_metadata: null
    shape: shape_example
    shape_config:
      # optional
      ocpus: 3.4
      vcpus: 56
      memory_in_gbs: 3.4
      baseline_ocpu_utilization: BASELINE_1_8
      nvmes: 56
    update_operation_constraint: ALLOW_DOWNTIME
    instance_options:
      # optional
      are_legacy_imds_endpoints_disabled: true
    fault_domain: FAULT-DOMAIN-1
    launch_options:
      # optional
      firmware: BIOS
      remote_data_volume_type: ISCSI
      is_consistent_volume_naming_enabled: true
      boot_volume_type: ISCSI
      network_type: E1000
      is_pv_encryption_in_transit_enabled: true
    availability_config:
      # optional
      is_live_migration_preferred: true
      recovery_action: RESTORE_INSTANCE
    time_maintenance_reboot_due: time_maintenance_reboot_due_example

- name: Delete instance
  oci_compute_instance:
    # required
    instance_id: "ocid1.instance.oc1..xxxxxxEXAMPLExxxxxx"
    state: absent

    # optional
    preserve_boot_volume: true

- name: Delete instance using name (when environment variable OCI_USE_NAME_AS_IDENTIFIER is set)
  oci_compute_instance:
    # required
    compartment_id: "ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx"
    display_name: display_name_example
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
instance
complex
on success
Details of the Instance resource acted upon by the current operation

Sample:
{'agent_config': {'are_all_plugins_disabled': True, 'is_management_disabled': True, 'is_monitoring_disabled': True, 'plugins_config': [{'desired_state': 'ENABLED', 'name': 'name_example'}]}, 'availability_config': {'is_live_migration_preferred': True, 'recovery_action': 'RESTORE_INSTANCE'}, 'availability_domain': 'Uocm:PHX-AD-1', 'capacity_reservation_id': 'ocid1.capacityreservation.oc1..xxxxxxEXAMPLExxxxxx', 'compartment_id': 'ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx', 'dedicated_vm_host_id': 'ocid1.dedicatedvmhost.oc1..xxxxxxEXAMPLExxxxxx', 'defined_tags': {'Operations': {'CostCenter': 'US'}}, 'display_name': 'display_name_example', 'extended_metadata': {}, 'fault_domain': 'FAULT-DOMAIN-1', 'freeform_tags': {'Department': 'Finance'}, 'id': 'ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx', 'image_id': 'ocid1.image.oc1..xxxxxxEXAMPLExxxxxx', 'instance_configuration_id': 'ocid1.instanceconfiguration.oc1..xxxxxxEXAMPLExxxxxx', 'instance_options': {'are_legacy_imds_endpoints_disabled': True}, 'ipxe_script': 'ipxe_script_example', 'is_cross_numa_node': True, 'launch_mode': 'NATIVE', 'launch_options': {'boot_volume_type': 'ISCSI', 'firmware': 'BIOS', 'is_consistent_volume_naming_enabled': True, 'is_pv_encryption_in_transit_enabled': True, 'network_type': 'E1000', 'remote_data_volume_type': 'ISCSI'}, 'lifecycle_state': 'MOVING', 'metadata': {}, 'platform_config': {'are_virtual_instructions_enabled': True, 'is_access_control_service_enabled': True, 'is_input_output_memory_management_unit_enabled': True, 'is_measured_boot_enabled': True, 'is_memory_encryption_enabled': True, 'is_secure_boot_enabled': True, 'is_symmetric_multi_threading_enabled': True, 'is_trusted_platform_module_enabled': True, 'numa_nodes_per_socket': 'NPS0', 'percentage_of_cores_enabled': 56, 'type': 'AMD_MILAN_BM'}, 'preemptible_instance_config': {'preemption_action': {'preserve_boot_volume': True, 'type': 'TERMINATE'}}, 'primary_private_ip': '10.0.0.10', 'primary_public_ip': '140.34.93.209', 'region': 'us-phoenix-1', 'shape': 'shape_example', 'shape_config': {'baseline_ocpu_utilization': 'BASELINE_1_8', 'gpu_description': 'gpu_description_example', 'gpus': 56, 'local_disk_description': 'local_disk_description_example', 'local_disks': 56, 'local_disks_total_size_in_gbs': 3.4, 'max_vnic_attachments': 56, 'memory_in_gbs': 3.4, 'networking_bandwidth_in_gbps': 3.4, 'ocpus': 3.4, 'processor_description': 'processor_description_example', 'vcpus': 56}, 'source_details': {'boot_volume_id': 'ocid1.bootvolume.oc1..xxxxxxEXAMPLExxxxxx', 'boot_volume_size_in_gbs': 56, 'boot_volume_vpus_per_gb': 56, 'image_id': 'ocid1.image.oc1..xxxxxxEXAMPLExxxxxx', 'instance_source_image_filter_details': {'compartment_id': 'ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx', 'defined_tags_filter': {}, 'operating_system': 'operating_system_example', 'operating_system_version': 'operating_system_version_example'}, 'kms_key_id': 'ocid1.kmskey.oc1..xxxxxxEXAMPLExxxxxx', 'source_type': 'bootVolume'}, 'system_tags': {}, 'time_created': '2013-10-20T19:20:30+01:00', 'time_maintenance_reboot_due': '2013-10-20T19:20:30+01:00'}
 
agent_config
complex
on success

   
are_all_plugins_disabled
boolean
on success
Whether Oracle Cloud Agent can run all of the available plugins. This includes the management and monitoring plugins.
For more information about the available plugins, see Managing Plugins with Oracle Cloud Agent.

Sample:
True
   
is_management_disabled
boolean
on success
Whether Oracle Cloud Agent can run all the available management plugins.
These are the management plugins: OS Management Service Agent and Compute Instance Run Command.
The management plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
- If `isManagementDisabled` is true, all of the management plugins are disabled, regardless of the per-plugin configuration. - If `isManagementDisabled` is false, all of the management plugins are enabled. You can optionally disable individual management plugins by providing a value in the `pluginsConfig` object.

Sample:
True
   
is_monitoring_disabled
boolean
on success
Whether Oracle Cloud Agent can gather performance metrics and monitor the instance using the monitoring plugins.
These are the monitoring plugins: Compute Instance Monitoring and Custom Logs Monitoring.
The monitoring plugins are controlled by this parameter and by the per-plugin configuration in the `pluginsConfig` object.
- If `isMonitoringDisabled` is true, all of the monitoring plugins are disabled, regardless of the per-plugin configuration. - If `isMonitoringDisabled` is false, all of the monitoring plugins are enabled. You can optionally disable individual monitoring plugins by providing a value in the `pluginsConfig` object.

Sample:
True
   
plugins_config
complex
on success
The configuration of plugins associated with this instance.
     
desired_state
string
on success
Whether the plugin should be enabled or disabled.
To enable the monitoring and management plugins, the `isMonitoringDisabled` and `isManagementDisabled` attributes must also be set to false.

Sample:
ENABLED
     
name
string
on success
The plugin name. To get a list of available plugins, use the ListInstanceagentAvailablePlugins operation in the Oracle Cloud Agent API. For more information about the available plugins, see Managing Plugins with Oracle Cloud Agent.

Sample:
name_example
 
availability_config
complex
on success

   
is_live_migration_preferred
boolean
on success
Whether to live migrate supported VM instances to a healthy physical VM host without disrupting running instances during infrastructure maintenance events. If null, Oracle chooses the best option for migrating the VM during infrastructure maintenance events.

Sample:
True
   
recovery_action
string
on success
The lifecycle state for an instance when it is recovered after infrastructure maintenance. * `RESTORE_INSTANCE` - The instance is restored to the lifecycle state it was in before the maintenance event. If the instance was running, it is automatically rebooted. This is the default action when a value is not set. * `STOP_INSTANCE` - The instance is recovered in the stopped state.

Sample:
RESTORE_INSTANCE
 
availability_domain
string
on success
The availability domain the instance is running in.
Example: `Uocm:PHX-AD-1`

Sample:
Uocm:PHX-AD-1
 
capacity_reservation_id
string
on success
The OCID of the compute capacity reservation this instance is launched under. When this field contains an empty string or is null, the instance is not currently in a capacity reservation. For more information, see Capacity Reservations.

Sample:
ocid1.capacityreservation.oc1..xxxxxxEXAMPLExxxxxx
 
compartment_id
string
on success
The OCID of the compartment that contains the instance.

Sample:
ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx
 
dedicated_vm_host_id
string
on success
The OCID of the dedicated virtual machine host that the instance is placed on.

Sample:
ocid1.dedicatedvmhost.oc1..xxxxxxEXAMPLExxxxxx
 
defined_tags
dictionary
on success
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Example: `{"Operations": {"CostCenter": "42"}}`

Sample:
{'Operations': {'CostCenter': 'US'}}
 
display_name
string
on success
A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.

Sample:
display_name_example
 
extended_metadata
dictionary
on success
Additional metadata key/value pairs that you provide. They serve the same purpose and functionality as fields in the `metadata` object.
They are distinguished from `metadata` fields in that these can be nested JSON objects (whereas `metadata` fields are string/string maps only).
 
fault_domain
string
on success
The name of the fault domain the instance is running in.
A fault domain is a grouping of hardware and infrastructure within an availability domain. Each availability domain contains three fault domains. Fault domains let you distribute your instances so that they are not on the same physical hardware within a single availability domain. A hardware failure or Compute hardware maintenance that affects one fault domain does not affect instances in other fault domains.
If you do not specify the fault domain, the system selects one for you.
Example: `FAULT-DOMAIN-1`

Sample:
FAULT-DOMAIN-1
 
freeform_tags
dictionary
on success
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags.
Example: `{"Department": "Finance"}`

Sample:
{'Department': 'Finance'}
 
id
string
on success
The OCID of the instance.

Sample:
ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx
 
image_id
string
on success
Deprecated. Use `sourceDetails` instead.

Sample:
ocid1.image.oc1..xxxxxxEXAMPLExxxxxx
 
instance_configuration_id
string
on success
The OCID of the Instance Configuration used to source launch details for this instance. Any other fields supplied in the instance launch request override the details stored in the Instance Configuration for this instance launch.

Sample:
ocid1.instanceconfiguration.oc1..xxxxxxEXAMPLExxxxxx
 
instance_options
complex
on success

   
are_legacy_imds_endpoints_disabled
boolean
on success
Whether to disable the legacy (/v1) instance metadata service endpoints. Customers who have migrated to /v2 should set this to true for added security. Default is false.

Sample:
True
 
ipxe_script
string
on success
When a bare metal or virtual machine instance boots, the iPXE firmware that runs on the instance is configured to run an iPXE script to continue the boot process.
If you want more control over the boot process, you can provide your own custom iPXE script that will run when the instance boots. Be aware that the same iPXE script will run every time an instance boots, not only after the initial LaunchInstance call.
The default iPXE script connects to the instance's local boot volume over iSCSI and performs a network boot. If you use a custom iPXE script and want to network-boot from the instance's local boot volume over iSCSI the same way as the default iPXE script, use the following iSCSI IP address: 169.254.0.2, and boot volume IQN: iqn.2015-02.oracle.boot.
If your instance boot volume attachment type is paravirtualized, the boot volume is attached to the instance through virtio-scsi and no iPXE script is used. If your instance boot volume attachment type is paravirtualized and you use custom iPXE to network boot into your instance, the primary boot volume is attached as a data volume through virtio-scsi drive.
For more information about the Bring Your Own Image feature of Oracle Cloud Infrastructure, see Bring Your Own Image.
For more information about iPXE, see http://ipxe.org.

Sample:
ipxe_script_example
 
is_cross_numa_node
boolean
on success
Whether the instance's OCPUs and memory are distributed across multiple NUMA nodes.

Sample:
True
 
launch_mode
string
on success
Specifies the configuration mode for launching virtual machine (VM) instances. The configuration modes are: * `NATIVE` - VM instances launch with iSCSI boot and VFIO devices. The default value for platform images. * `EMULATED` - VM instances launch with emulated devices, such as the E1000 network driver and emulated SCSI disk controller. * `PARAVIRTUALIZED` - VM instances launch with paravirtualized devices using VirtIO drivers. * `CUSTOM` - VM instances launch with custom configuration settings specified in the `LaunchOptions` parameter.

Sample:
NATIVE
 
launch_options
complex
on success

   
boot_volume_type
string
on success
Emulation type for the boot volume. * `ISCSI` - ISCSI attached block storage device. * `SCSI` - Emulated SCSI disk. * `IDE` - Emulated IDE disk. * `VFIO` - Direct attached Virtual Function storage. This is the default option for local data volumes on platform images. * `PARAVIRTUALIZED` - Paravirtualized disk. This is the default for boot volumes and remote block storage volumes on platform images.

Sample:
ISCSI
   
firmware
string
on success
Firmware used to boot VM. Select the option that matches your operating system. * `BIOS` - Boot VM using BIOS style firmware. This is compatible with both 32 bit and 64 bit operating systems that boot using MBR style bootloaders. * `UEFI_64` - Boot VM using UEFI style firmware compatible with 64 bit operating systems. This is the default for platform images.

Sample:
BIOS
   
is_consistent_volume_naming_enabled
boolean
on success
Whether to enable consistent volume naming feature. Defaults to false.

Sample:
True
   
is_pv_encryption_in_transit_enabled
boolean
on success
Deprecated. Instead use `isPvEncryptionInTransitEnabled` in LaunchInstanceDetails.

Sample:
True
   
network_type
string
on success
Emulation type for the physical network interface card (NIC). * `E1000` - Emulated Gigabit ethernet controller. Compatible with Linux e1000 network driver. * `VFIO` - Direct attached Virtual Function network controller. This is the networking type when you launch an instance using hardware-assisted (SR-IOV) networking. * `PARAVIRTUALIZED` - VM instances launch with paravirtualized devices using VirtIO drivers.

Sample:
E1000
   
remote_data_volume_type
string
on success
Emulation type for volume. * `ISCSI` - ISCSI attached block storage device. * `SCSI` - Emulated SCSI disk. * `IDE` - Emulated IDE disk. * `VFIO` - Direct attached Virtual Function storage. This is the default option for local data volumes on platform images. * `PARAVIRTUALIZED` - Paravirtualized disk. This is the default for boot volumes and remote block storage volumes on platform images.

Sample:
ISCSI
 
lifecycle_state
string
on success
The current state of the instance.

Sample:
MOVING
 
metadata
dictionary
on success
Custom metadata that you provide.
 
platform_config
complex
on success

   
are_virtual_instructions_enabled
boolean
on success
Whether virtualization instructions are available. For example, Secure Virtual Machine for AMD shapes or VT-x for Intel shapes.

Sample:
True
   
is_access_control_service_enabled
boolean
on success
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.

Sample:
True
   
is_input_output_memory_management_unit_enabled
boolean
on success
Whether the input-output memory management unit is enabled.

Sample:
True
   
is_measured_boot_enabled
boolean
on success
Whether the Measured Boot feature is enabled on the instance.

Sample:
True
   
is_memory_encryption_enabled
boolean
on success
Whether the instance is a confidential instance. If this value is `true`, the instance is a confidential instance. The default value is `false`.

Sample:
True
   
is_secure_boot_enabled
boolean
on success
Whether Secure Boot is enabled on the instance.

Sample:
True
   
is_symmetric_multi_threading_enabled
boolean
on success
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.

Sample:
True
   
is_trusted_platform_module_enabled
boolean
on success
Whether the Trusted Platform Module (TPM) is enabled on the instance.

Sample:
True
   
numa_nodes_per_socket
string
on success
The number of NUMA nodes per socket (NPS).

Sample:
NPS0
   
percentage_of_cores_enabled
integer
on success
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.

Sample:
56
   
type
string
on success
The type of platform being configured.

Sample:
AMD_MILAN_BM
 
preemptible_instance_config
complex
on success

   
preemption_action
complex
on success

     
preserve_boot_volume
boolean
on success
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.

Sample:
True
     
type
string
on success
The type of action to run when the instance is interrupted for eviction.

Sample:
TERMINATE
 
primary_private_ip
string
on success
The private IP of the primary VNIC attached to this instance

Sample:
10.0.0.10
 
primary_public_ip
string
on success
The public IP of the primary VNIC attached to this instance

Sample:
140.34.93.209
 
region
string
on success
The region that contains the availability domain the instance is running in.
For the us-phoenix-1 and us-ashburn-1 regions, `phx` and `iad` are returned, respectively. For all other regions, the full region name is returned.
Examples: `phx`, `eu-frankfurt-1`

Sample:
us-phoenix-1
 
shape
string
on success
The shape of the instance. The shape determines the number of CPUs and the amount of memory allocated to the instance. You can enumerate all available shapes by calling ListShapes.

Sample:
shape_example
 
shape_config
complex
on success

   
baseline_ocpu_utilization
string
on success
The baseline OCPU utilization for a subcore burstable VM instance. Leave this attribute blank for a non-burstable instance, or explicitly specify non-burstable with `BASELINE_1_1`.
The following values are supported: - `BASELINE_1_8` - baseline usage is 1/8 of an OCPU. - `BASELINE_1_2` - baseline usage is 1/2 of an OCPU. - `BASELINE_1_1` - baseline usage is the entire OCPU. This represents a non-burstable instance.

Sample:
BASELINE_1_8
   
gpu_description
string
on success
A short description of the instance's graphics processing unit (GPU).
If the instance does not have any GPUs, this field is `null`.

Sample:
gpu_description_example
   
gpus
integer
on success
The number of GPUs available to the instance.

Sample:
56
   
local_disk_description
string
on success
A short description of the local disks available to this instance.
If the instance does not have any local disks, this field is `null`.

Sample:
local_disk_description_example
   
local_disks
integer
on success
The number of local disks available to the instance.

Sample:
56
   
local_disks_total_size_in_gbs
float
on success
The aggregate size of all local disks, in gigabytes.
If the instance does not have any local disks, this field is `null`.

Sample:
3.4
   
max_vnic_attachments
integer
on success
The maximum number of VNIC attachments for the instance.

Sample:
56
   
memory_in_gbs
float
on success
The total amount of memory available to the instance, in gigabytes.

Sample:
3.4
   
networking_bandwidth_in_gbps
float
on success
The networking bandwidth available to the instance, in gigabits per second.

Sample:
3.4
   
ocpus
float
on success
The total number of OCPUs available to the instance.

Sample:
3.4
   
processor_description
string
on success
A short description of the instance's processor (CPU).

Sample:
processor_description_example
   
vcpus
integer
on success
The total number of VCPUs available to the instance. This can be used instead of OCPUs, in which case the actual number of OCPUs will be calculated based on this value and the actual hardware. This must be a multiple of 2.

Sample:
56
 
source_details
complex
on success

   
boot_volume_id
string
on success
The OCID of the boot volume used to boot the instance.

Sample:
ocid1.bootvolume.oc1..xxxxxxEXAMPLExxxxxx
   
boot_volume_size_in_gbs
integer
on success
The size of the boot volume in GBs. Minimum value is 50 GB and maximum value is 32,768 GB (32 TB).

Sample:
56
   
boot_volume_vpus_per_gb
integer
on success
The number of volume performance units (VPUs) that will be applied to this volume per GB, representing the Block Volume service's elastic performance options. See Block Volume Performance Levels for more information.
Allowed values:
* `10`: Represents Balanced option.
* `20`: Represents Higher Performance option.
* `30`-`120`: Represents the Ultra High Performance option.
For volumes with the auto-tuned performance feature enabled, this is set to the default (minimum) VPUs/GB.

Sample:
56
   
image_id
string
on success
The OCID of the image used to boot the instance.

Sample:
ocid1.image.oc1..xxxxxxEXAMPLExxxxxx
   
instance_source_image_filter_details
complex
on success

     
compartment_id
string
on success
The OCID of the compartment containing images to search

Sample:
ocid1.compartment.oc1..xxxxxxEXAMPLExxxxxx
     
defined_tags_filter
dictionary
on success
Filter based on these defined tags. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
     
operating_system
string
on success
The image's operating system.
Example: `Oracle Linux`

Sample:
operating_system_example
     
operating_system_version
string
on success
The image's operating system version.
Example: `7.2`

Sample:
operating_system_version_example
   
kms_key_id
string
on success
The OCID of the Vault service key to assign as the master encryption key for the boot volume.

Sample:
ocid1.kmskey.oc1..xxxxxxEXAMPLExxxxxx
   
source_type
string
on success
The source type for the instance. Use `image` when specifying the image OCID. Use `bootVolume` when specifying the boot volume OCID.

Sample:
bootVolume
 
system_tags
dictionary
on success
System tags for this resource. Each key is predefined and scoped to a namespace. Example: `{"foo-namespace": {"bar-key": "value"}}`
 
time_created
string
on success
The date and time the instance was created, in the format defined by RFC3339.
Example: `2016-08-25T21:10:29.600Z`

Sample:
2013-10-20T19:20:30+01:00
 
time_maintenance_reboot_due
string
on success
The date and time the instance is expected to be stopped / started, in the format defined by RFC3339. After that time if instance hasn't been rebooted, Oracle will reboot the instance within 24 hours of the due time. Regardless of how the instance was stopped, the flag will be reset to empty as soon as instance reaches Stopped state. Example: `2018-05-25T21:10:29.600Z`

Sample:
2013-10-20T19:20:30+01:00


Authors

  • Oracle (@oracle)