Working with Instances
Oracle Cloud Infrastructure Compute lets you provision and manage compute hosts, known as instances. You can create instances as needed to meet your compute and application requirements. After you create an instance, you can access it securely from your computer, restart it, attach and detach volumes, and terminate it when you're done with it.
- Creating an Instance: Follow the steps in this topic to create a bare metal or virtual machine (VM) compute instance.
- Instances launched using Oracle Linux, CentOS, or Ubuntu images use an SSH key pair instead of a password to authenticate a remote user. Therefore, to connect to an instance, you might need to create an SSH key pair.
- You can create burstable instances, shielded instances, and confidential instances.
- You can configure your instances to use different capacity types.
- You can add extended memory and cores to instances with extended memory VM instances.
- Connecting to an Instance: You can connect to a running instance by using a Secure Shell (SSH) or Remote Desktop connection.
- Editing an Instance: You can edit the properties of a compute instance without having to rebuild the instance or redeploy your applications.
- Stopping, Starting, or Restarting an Instance: You can stop and start an instance as needed to update software or resolve error conditions.
- Replacing a Boot Volume: You can automatically replace the boot volume of an instance without terminating and recreating the instance.
- Setting Up Contextual Notifications for an Instance: You can get messages when something happens with a compute instance.
- Adding Users to an Instance: You can add users to a compute instance.
- Running Commands on an Instance: You can remotely configure, manage, and troubleshoot compute instances by running scripts within the instance using the run command feature.
- Disabling Simultaneous Multithreading: You can disable simultaneous multithreading (SMT) on your instances through the console or by using CLI commands.
- Getting Instance Metadata: The instance metadata service (IMDS) provides information about a running instance, including details about the instance, its attached virtual network interface cards (VNICs), its attached multipath-enabled volume attachments, and any custom metadata that you define. IMDS also provides information to cloud-init that you can use for various system initialization tasks.
- Updating Instance Metadata: You can add and update custom metadata for a compute instance using the CLI or REST APIs.
- Moving a Compute Instance to a New Host: You can relocate instances using reboot migration or a manual process.
- Terminating an Instance: You can permanently delete (terminate) instances that you no longer need. Any attached VNICs and volumes are automatically detached when the instance terminates.
Security Zones
Security Zones ensure that your cloud resources comply with Oracle security principles. If any operation on a resource in a security zone compartment violates a policy for that security zone, then the operation is denied.
The following security zone policies affect the ability to create instances:
- The boot volume for a compute instance in a security zone must also be in the same security zone.
- A Compute instance that isn't in a security zone can't use a boot volume that is in a security zone.
- A Compute instance in a security zone must use subnets that are also in the same security zone.
- All Compute instances in a security zone must be created using platform images. You can't create a compute instance from a custom image in a security zone.
Failing to implement one of the listed security zone policies might prevent the creation of an instance.
Required IAM Policy for Working with Instances
To use Oracle Cloud Infrastructure, an administrator must be a member of a group granted security access in a policy by a tenancy administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don't have permission or are unauthorized, verify with the tenancy administrator what type of access you have and which compartment your access works in.
When you create an instance, several other resources are involved, such as an image, a cloud network, and a subnet. Those other resources can be in the same compartment with the instance or in other compartments. You must have the required level of access to each of the compartments involved in order to launch the instance. This is also true when you attach a volume to an instance; they don't have to be in the same compartment, but if they're not, you need the required level of access to each of the compartments.
For administrators: The simplest policy to let users create, edit, and terminate (delete) instances is listed in Let users launch compute instances. It gives the specified group general access to manage instances and images, along with the required level of access to attach existing block volumes to the instances. If the specified group doesn't need to launch instances or attach volumes, you could simplify that policy to include only manage instance-family, and remove the statements involving volume-family and virtual-network-family.
If the group needs to create block volumes, they'll need the ability to manage block volumes. See Let volume admins manage block volumes, backups, and volume groups.
If the group needs access to community images specifically, they'll need the ability to read community images. See Publishing Community Applications.
Some Compute tasks require additional policies, as described in the following sections.
Partner Image Catalog
If the group needs to create instances based on partner images, they'll need the manage permission for app-catalog-listing to create subscriptions to images from the Partner Image catalog. See Let users list and subscribe to images from the Partner Image catalog .
SSH and Remote Desktop Access
For users: To connect to a running instance with a Secure Shell (SSH) or Remote Desktop connection, you don't need an IAM policy to grant you access. However, you do need the public IP address of the instance.
For administrators: If there's a policy that lets users launch an instance, that policy probably also lets users get the instance's IP address. The simplest policy that does both is listed in Let users launch compute instances.
Here's a more restrictive policy that lets the specified group get the IP address of existing instances and use power actions on the instances (for example, stop or start the instance), but not launch or terminate instances. The policy assumes the instances and the cloud network are together in a single compartment (XYZ).
Allow group InstanceUsers to read virtual-network-family in compartment XYZ
Allow group InstanceUsers to use instance-family in compartment XYZInstance Metadata Service (IMDS)
For users: No IAM policy is required if you're logged in to the instance and using cURL to get the instance metadata.
For administrators: Users can also get instance metadata through the Compute API (for example, with GetInstance). The policy in Let users launch compute instances covers that ability.
To require that legacy IMDSv1 endpoints are disabled on any new instances that are created, use the following policy:
Allow group InstanceLaunchers to manage instances in compartment ABC
where request.instanceOptions.areLegacyEndpointsDisabled= 'true'Capacity Reservations
For administrators: The following examples show typical policies that give access to capacity reservations. Create the policy in the tenancy so that the access is easily granted to all compartments by way of policy inheritance. To reduce the scope of access to just the capacity reservations in a particular compartment, specify that compartment instead of the tenancy.
Type of access: Ability to launch an instance in a reservation.
Allow group InstanceLaunchers to use compute-capacity-reservations in tenancy
Type of access: Ability to manage capacity reservations.
Allow group InstanceLaunchers to manage compute-capacity-reservations in tenancy
Run Command
For administrators: To write policy for the run command feature, do the following:
-
Create a group that includes the users who you want to allow to issue commands, cancel commands, and view the command output for the instances in a compartment. Then, write the following policy to grant access for the group:
Allow group RunCommandUsers to manage instance-agent-command-family in compartment ABC -
Create a dynamic group that includes the instances that you want to allow commands to run on. For example, a rule inside the dynamic group can state:
any { instance.id = 'ocid1.instance.oc1.phx.<unique_ID_1>', 'ocid1.instance.oc1.phx.<unique_ID_2>' } -
Write the following policy to grant access for the dynamic group:Note
If you create an instance and then add it to a dynamic group, it takes up to 30 minutes for the instance to start to poll for commands. If you create the dynamic group first and then create the instance, the instance starts to poll for commands as soon as the instance is created.Allow dynamic-group RunCommandDynamicGroup to use instance-agent-command-execution-family in compartment ABC where request.instance.id=target.instance.id -
To allow the dynamic group to access the script file from an Object Storage bucket and save the response to an Object Storage bucket, write the following policies:
Allow dynamic-group RunCommandDynamicGroup to read objects in compartment ABC where all {target.bucket.name = '<bucket_with_script_file>'} Allow dynamic-group RunCommandDynamicGroup to manage objects in compartment ABC where all {target.bucket.name = '<bucket_for_command_output>'}
Recommended Networking Launch Types for Compute Instances
When you create a VM instance, by default, Oracle Cloud Infrastructure chooses a recommended networking type for the VNIC based on the instance shape and OS image. The networking interface handles functions such as disk input/output and network communication.
The following networking types are available:
- Paravirtualized networking: For general purpose workloads such as enterprise applications, microservices, and small databases. Paravirtualized networking also provides increased flexibility to use the same image across different hardware platforms. Linux images with paravirtualized networking support live migration during infrastructure maintenance.
- Hardware-assisted (SR-IOV) networking: Single root input/output virtualization. For low-latency workloads such as video streaming, real-time applications, and large or clustered databases. Hardware-assisted (SR-IOV) networking uses the VFIO driver framework.
To use a particular networking type, both the shape and the image must support that networking type.
Shapes: The following table lists the default and supported networking types for VM shapes.
| Shape | Default Networking Type | Supported Networking Types |
|---|---|---|
| VM.Standard1 series | SR-IOV | Paravirtualized, SR-IOV |
| VM.Standard2 series | Paravirtualized | Paravirtualized, SR-IOV |
| VM.Standard3.Flex | Paravirtualized | Paravirtualized, SR-IOV |
| VM.Standard.E2 series | Paravirtualized | Paravirtualized only |
| VM.Standard.E3.Flex |
Paravirtualized |
Paravirtualized, SR-IOV |
| VM.Standard.E4.Flex |
Paravirtualized |
Paravirtualized, SR-IOV |
| VM.Standard.E5.Flex |
Paravirtualized |
Paravirtualized, SR-IOV |
| VM.Standard.E6.Flex |
Paravirtualized |
Paravirtualized, SR-IOV |
| VM.Standard.A1.Flex1 | Paravirtualized | Paravirtualized, SR-IOV |
| VM.DenseIO1 series | SR-IOV | Paravirtualized, SR-IOV |
| VM.DenseIO2 series | Paravirtualized | Paravirtualized, SR-IOV |
| VM.DenseIO.E4.Flex | Paravirtualized | Paravirtualized, SR-IOV |
| VM.GPU2 series | SR-IOV | Paravirtualized, SR-IOV |
| VM.GPU3 series | SR-IOV | Paravirtualized, SR-IOV |
| VM.GPU.A10 series | SR-IOV | Paravirtualized, SR-IOV |
| VM.Optimized3.Flex |
Paravirtualized |
Paravirtualized, SR-IOV |
Images: Paravirtualized networking is supported on these platform images:
- Oracle Linux 9, Oracle Linux 8, Oracle Autonomous Linux 8.x, Oracle Autonomous Linux 7.x, Oracle Linux Cloud Developer 8: All images.
- Oracle Linux 7: Images published in March 2019 or later.
- CentOS Stream 8, CentOS 7: Images published in July 2019 or later.
- Ubuntu 22.04, Ubuntu 20.04: All images.
- Ubuntu 18.04: Images published in March 2019 or later.
- Windows Server 2022, Windows Server 2019: All images.
- Windows Server 2016, Windows Server 2012 R2: Images published in August 2019 or later.
SR-IOV networking is supported on all platform images, with the following exceptions:
- Images for Arm-based shapes do not support SR-IOV networking.
- On Windows Server 2019 and Windows Server 2022, when launched using a shape in the VM.Standard2 series, SR-IOV networking is not supported.
- On Windows Server 2012 R2, SR-IOV networking is supported on platform images released in April 2021 or later.
- The Server Core installation option for Windows Server does not support SR-IOV networking.
Troubleshooting Creation Errors by Using Work Requests
Work requests help you monitor long-running operations such as database backups or the provisioning of compute instances.
If an operation such as the create instance operation fails, or if the instance state moves directly from provisioning to terminating, use work requests to determine where in the workflow the error occurred. Errors can occur because of problems with the configuration or problems with the user data. Synchronous errors occur during the initial call to the Compute API to create the instance. Asynchronous errors occur during the create instance workflow that occurs after the initial API call. Work requests capture asynchronous validation failures. A successful create instance API call that returns an HTTP 200 response might be followed by an asynchronous error during the subsequent create instance workflow.
The response to the REST API call contains the OCID of the work request in the opc-work-request-id header. You can monitor the status of the work request at any time by calling GetWorkRequest in the Work Requests API and passing in the work request ID found in the opc-work-request-id header. If an error occurs during the workflow, you can call ListWorkRequestErrors in the Work Requests API and pass in the work request ID to retrieve a list of errors.
For information about using work requests to troubleshoot errors, see Work Requests. For detailed information about asynchronous work requests, including how to filter the request response and a sample request and response, see Asynchronous Work Requests.
Managing Tags for an Instance
Apply tags to resources to help organize them according to your business needs. You can apply tags when you create a resource, and you can update a resource later to add, revise, or remove tags. For general information about applying tags, see Resource Tags.
To manage tags for an instance:
- Open the navigation menu and select Compute. Under Compute, select Instances.
-
Select the instance that you're interested in.
-
Select the Tags tab to view or edit the existing tags. Or click More Actions, and then click Add tags to add new ones.