Compute Instance Deployment

6 Compute Instance Deployment

Tutorial – Launching Your First Instance

In this tutorial you'll learn the basic features of Oracle Private Cloud Appliance by performing some guided steps to launch and connect to an instance. After your instance is up and running, this tutorial steps you through creating and attaching a block volume to your instance.

This tutorial also includes optional instructions for deleting all the resources you create.

Task Flow to Launch an Instance

No.	Task	Links
1.	Review the prerequisites.	Prerequisites
2.	Log into the appliance.	Log into Oracle Private Cloud Appliance
3.	Create a compartment for your resources.	Create a Compartment
4.	Create a Virtual Cloud Network (VCN).	Create a Virtual Cloud Network (VCN)
5.	Create a subnet in the VCN.	Create a Subnet
6.	Configure additional network parameters to enable instance connectivity.	Create an Internet Gateway and Configure Route Rules
7.	Launch an instance	Launch an Instance
8.	Get the instance IP address.	Get the Instance IP Address
9.	Connect to your instance.	Connect to Your Instance
10.	Add Storage to your instance.	Add a Block Volume Attach the Block Volume to an Instance
11.	(Optional) Clean up your resources.	(Optional) Clean Up Resources

Prerequisites

To perform this tutorial, ensure that you have the following items.

The URL for your Private Cloud Appliance.

For example, https://console.pca_name.example.com where pca_name is the name of your Private Cloud Appliance and example.com is your domain.
A Private Cloud Appliance user account and password.
The name of your tenancy.
An SSH-2 RSA key pair. If you want to create a key pair for this tutorial, see Managing Key Pairs.
The virtual IP address (VIP) or hostname of the Private Cloud Appliance management nodes.

If you don't have these items, ask your Service Enclave administrator.

In a browser, enter the URL for your Private Cloud Appliance.
If necessary, click Change Tenant, enter the name of your tenancy, and click Continue.
Enter your user name and password, and then click Sign In.

If this is the first time you've logged in, you are prompted to change your password.

For more information about using the Compute Web UI, see Using the Compute Web UI.

What's Next

Continue to Create a Compartment.

Create a Compartment

Compartments help you organize and control access to your resources. A compartment is a collection of resources (such as cloud networks, compute instances, and block volumes) that can be accessed only by those groups that have been given permission by an administrator in your organization.

In a production environment, the compartment for the instance you plan to create might already exist, and you could use it instead of creating a new compartment. However, in this tutorial, you create a new compartment to learn how to do it, and to provide an empty compartment from which you can create your cloud network.

In this tutorial, you use one compartment for all of your resources. However, when you are ready to create a production environment you can separate resources into different compartments. For example, you might place all instances in one compartment and all networking resources in another compartment.

For more information about compartments, refer to these resources:

For conceptual information, see "Organizing Resources in Compartments" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.
For step-by-step instructions to manage compartments, see Creating and Managing Compartments.

Using the Compute Web UI

In the Navigation Menu, click Identity and then click Compartments.
On the Compartments page, click the Create Compartment button.
In the Create Compartment dialog, enter the following details:
- Name: Enter Sandbox.
- Description: Enter a description for the compartment.
- Create in Compartment: Select the compartment in which to create this new compartment.
Click the Create Compartment button in the dialog.

The new compartment is displayed on the Compartments page.

What's Next

Continue to Create a Virtual Cloud Network (VCN).

Create a Virtual Cloud Network (VCN)

Before you can launch an instance, you need a virtual cloud network (VCN) and a subnet.

A VCN is a software-defined equivalent of a traditional network, with firewall rules and various types of communication gateways.

In a production environment, a VCN that you can use for the instance might already exist, and you could use it instead of creating a new VCN. However, in this tutorial, you create a new VCN to learn how to do it.

Important:

This tutorial creates a simple cloud network to make it easy to launch an instance for learning purposes. When you create your production instances, ensure that you create appropriate security lists and route table rules to restrict network traffic to your instances.

For more information about VCNs, refer to these resources:

For conceptual information, see "Virtual Cloud Network" in the Virtual Networking Overview in the Oracle Private Cloud Appliance Concepts Guide.
For step-by-step instructions to manage VCNs, see Managing VCNs and Subnets.

Using the Compute Web UI

Click Dashboard, and click the Networking/View Virtual Cloud Networks button.
On the VCNs page, click the Create Virtual Cloud Network button.
In the Create Virtual Cloud Network dialog, enter the following information:
- Name: Enter a descriptive name for the cloud network.
- Create in Compartment: Select the Sandbox compartment.
- CIDR Block: Enter a valid CIDR block for the VCN. For example 10.0.0.0/16.
- Use DNS hostnames in this VCN: Indicate whether you want to use DNS host names in the VCN.
- DNS Label: If you selected to use DNS, enter a DNS label or leave the field blank to let the system generate a DNS name for you.
- Tagging: Leave blank. This tutorial does not use tags.
Click the Create Virtual Cloud Network button in the dialog.

What's Next

Continue to Create a Subnet.

Create a Subnet

A subnet is a subdivision of your VCN. The subnet directs traffic according to a route table.

For this tutorial, you'll access the instance over the internet using its public IP address, so your route table will direct traffic to an internet gateway. The subnet also uses a security list to control traffic in and out of the instance.

Using the Compute Web UI

Return to the Virtual Cloud Networks page.

A quick way to do this is to click the name of page in the breadcrumb that is in the top banner. For example:

If the VCNs page is not in your breadcrumb, Click Dashboard, and click the Networking/View Virtual Cloud Networks button.
On the VCNs list, click the name of the VCN you just created.

The details page for that VCN is displayed.
Scroll down to the Resources panel, click Subnets, and click the Create Subnet button.
In the Create Subnet dialog, enter the following information:
- Name: Enter a descriptive name for your subnet.
- Create in Compartment: Select the Sandbox compartment.
- CIDR Block: Enter a valid CIDR block for the subnet. The value must be within the VCN's CIDR block. For example, 10.0.0.0/24.
- Route Table: For this tutorial, select the default route table.
- Subnet Access: For this tutorial, select Public Subnet to allow public IP addresses for instances in the subnet.
- Use DNS Hostnames in this Subnet: For this tutorial, leave this unselected.
- DHCP Options: Leave this unselected.
- Security Lists: Click Add Security List and select the default security list.
- Tagging: Leave blank. This tutorial does not use tags.
Click the Create Subnet button in the dialog.

What's Next

Continue to Create an Internet Gateway and Configure Route Rules.

Create an Internet Gateway and Configure Route Rules

An internet gateway is an optional virtual router you can add to your VCN to enable access to your data center network.

The gateway supports connections initiated from within the VCN (egress) and connections initiated from the internet (ingress).

Security list rules control the types of traffic allowed in and out of resources in that subnet. Make sure to allow only the desired types of internet traffic.

Each public subnet that needs to use the internet gateway must have a route table rule that specifies the gateway as the target.

Using the Compute Web UI

Navigate to your VCN's details page.
In the Resources panel, select Internet Gateways.
Click Create Internet Gateway.
Enter the required information:
- Name: Enter a descriptive name for your internet gateway.
- Create in Compartment: Select the Sandbox compartment.
- Enabled: Select whether you want this internet gateway to be enabled upon creation.
- Tagging: Leave blank. This tutorial does not use tags.
Click the Create button on the Create Internet Gateway dialog.
Under Resources, click Route Tables.
Click the name of the default route table.
Scroll down to the Resources panel and click the Add Route Rules button.
On the Create Route Table Rule dialog, enter the required information:
- Target Type: From the drop-down menu, select Internet Gateway.
- CIDR Block: Enter: 0.0.0.0/0 (which means that all non-intra-VCN traffic that is not already covered by other rules in the route table will go to the target specified in this rule).
- Internet Gateway: From the drop-down menu, select the name of the Internet Gateway that you created.
- Description: An optional description of the rule.
Click the Create Route Table Rule button.

What's Next

Continue to Launch an Instance.

Launch an Instance

In this task, launch an instance with an image and a basic shape.

A compute instance is a virtual machine (VM), which is an independent computing environment that runs on top of physical hardware. The virtualization makes it possible to run multiple compute instances that are isolated from each other.

A shape describes the instance resources such as the number of CPUs, amount of memory, and network resources. In a production environment, you would select a shape that best suits workload and application requirements for the instance.

For more information about instances, refer to these resources:

For conceptual information, including descriptions of standard and flexible shapes, see Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.
For step-by-step instructions to manage instances, see Working with Instances.

Before You Begin

Ensure that you have performed these tasks:

Using the Compute Web UI

Click Dashboard, and click the Compute/View Instances button.
On the Instances page, click the Create Instance button.
In the Launch Instance dialog, enter the following information:
- Name: Enter a descriptive name for your compute instance.
- Create in Compartment: Select the Sandbox compartment.
- Fault Domain: Leave the default set to "Automatically select the best fault domain."
- Source Image:
  - Source Type: Select Platform Image.
  - List of images: Select the Oracle Linux 8 image.
- Shape: Select one of the smaller shapes such as VM.PCAStandard1.1.
- Boot Volume: Leave the check box empty so that the default boot volume size is created.
- Subnet:
  - VCN: Select the VCN you created.
  - Subnet: Select the subnet you created.
- Public IP Address: Ensure the check box is checked so that a public IP address is assigned to the instance.
- Private IP Address: Leave the field blank.
- Hostname: You can leave this field blank or enter a hostname.
- SSH Keys: Do one of the following to provide your public SSH key (.pub):
  - Click inside the Drag and Drop box to open a file browser and select the file.
  - Drag the file from your file browser listing and drop the file on the Drag and Drop box.
  - Select the Paste the public key(s) button, copy your public SSH key text, and paste the text into the field.
- Initialization Script: Leave this area as is.
- Network Security Group: Leave the check box unchecked.
- Tagging: Leave blank. This tutorial does not use tags.
Click the Launch Instance button in the dialog.
Monitor the state of the instance.

The state is displayed above the icon of the object. For example:

Your instance begins in the Provisioning state. Once the instance is in the Running state, you can connect to it.

What's Next

Continue to Get the Instance IP Address.

Get the Instance IP Address

You can connect to the instance using SSH with the instance IP address.

Using the Compute Web UI

Navigate to the details page of your instance.

Click Dashboard, and click the Compute/View Instances button. In the Instances list, click the name of your instance.
Select the Networking tab.

The tabs are displayed at the top of the details panel:
Under Instance Access on the Networking tab, note the Public IP Address.

What's Next

Continue to Connect to Your Instance.

Connect to Your Instance

In most cases, you connect to a running instance using a Secure Shell (SSH) connection. Some instances support authenticating your connection with a password. This tutorial assumes you used one of the images provided on the appliance, which creates an instance that authenticates your SSH connection with an SSH key pair.

For the system that you will be connecting from, most Linux and other UNIX operating systems include an SSH client by default.

Microsoft Windows 10 and Microsoft Windows Server 2019 systems should include the OpenSSH client, which you'll need if you created your instance using the SSH keys generated by Oracle Cloud Infrastructure.

For other Microsoft Windows versions, you can download a free SSH client called PuTTY from http://www.putty.org.

Before You Begin

Get the public IP address of your instance, as described in Get the Instance IP Address.
Get the path to your private key file.
Get the valid user name.

The user name is configured in the image used to launch the instance. If you launched an instance using one of the platform images that is provided on the appliance, the default user is opc. See Initial User Account for Platform Images.

Perform one of the following tasks based on the type of system you are connecting from:

Connect from a UNIX System

Perform this procedure on your UNIX system.

Open a terminal window.
Use the ssh command to connect to your instance.

Syntax:
```
ssh –i private_key_pathname username@public-ip-address
```
- private_key_pathname is the full path name of the file that contains the private key associated with the instance you want to access.
- username is the default user name for the instance. For this tutorial, opc is the user name.
- public-ip-address is your instance IP address.
Example:
```
$ ssh -i /home/flast/.ssh/id_rsa opc@192.0.2.1
```
If asked whether you want to continue connecting, type yes.

You are now logged in to your instance.

What's Next

Continue to Add a Block Volume.

Connect Using PuTTY

This connection method is commonly performed from Microsoft Windows systems.

Use this procedure if the instance uses a key pair that you created using the PuTTY Key Generator. See Creating an SSH Key Pair Using PuTTY Key Generator.

Open PuTTY.
In the Category pane (on the left), select Session and enter the following:
- Host Name (or IP address): username@public-ip-address
  - username is the default username for the instance. For this tutorial, the user name is opc.
  - public-ip-address is your instance IP address.
- Port: 22
- Connection type: SSH
In the Category pane, expand Window, and then select Translation.
In the Remote character set drop-down list, select UTF-8. The default locale setting on Linux-based instances is UTF-8, and this setting configures PuTTY to use the same locale.
In the Category pane, expand Connection, expand SSH, and then click Auth.
Click Browse, and then select your .ppk private key file.
Click Open to start the session.

If this is your first time connecting to the instance, you might see a message that the server's host key is not cached in the registry. Click Yes or Accept to continue the connection.

Tip:

If the connection fails, you might need to update your PuTTY proxy configuration.

What's Next

Continue to Add a Block Volume.

Add a Block Volume

You can use block volumes to expand the storage capacity of your compute instances.

After a block volume is created, you attach the volume to one or more instances. You can use the volume like a regular hard drive.

Using the Compute Web UI

Click Dashboard, and click the Block Storage/View Block Volumes button.
Click the Create Block Volume button.
In the Create Block Volume dialog, enter the following information:
- Name: Enter a descriptive name for your block volume.
- Create in Compartment: Select the Sandbox compartment.
- Size: Leave the default size (1024 GB).
- Backup Policy: Do not select a backup policy.
- Tags: Leave blank. This tutorial does not use tags.
Click Create Block Volume button in the dialog.
Monitor the state of the new block volume.

The state is displayed above the icon for the object. You can also scroll down to the Resources section and check the Work Request.

Initially, the block volume is in the Provisioning state. When the volume changes to the Available state, you can attach it to your instance.

What's Next

Continue to Attach the Block Volume to an Instance.

Attach the Block Volume to an Instance

Using the Compute Web UI

Click Dashboard, and click the Compute/View Instances button.
Ensure that the Sandbox compartment is selected at the top of the page.
In the Instances list, click the name of your instance to view its details.
Scroll down to the Resources panel, and click Attached Block Volumes.
Click the Attach Block Volume button.
In the Attach Block Volume dialog, enter the following information:
- Select from Compartment: Select the Sandbox compartment.
- Block Volume: Select the block volume you created.
- Access: Select Read/Write.
Click the Attach to Instance button in the dialog.

The attachment process takes about a minute. The volume is ready when the Attachment State for the volume is Attached.

If your block volume isn't displayed, reload the web page.

When a block volume is initially attached to an instance, the instance sees the volume as a new disk. To make the volume available to the instance OS, you need to give the volume a file system and mount it to the OS.

To learn about the block volume and how to make it available to the instance OS, refer to these sections outside of this tutorial:

What's Next

Continue to (Optional) Clean Up Resources.

(Optional) Clean Up Resources

After you've finished with the resources you created for this tutorial, you can delete and release the resources you don't intend to continue working with.

Detach and Delete the Block Volume

Caution:

You cannot undo a termination. Any data on a volume will be permanently deleted once the volume is terminated.

Using the Compute Web UI

Click Dashboard, and click the Compute/View Instances button.
Select the Sandbox compartment.
Click the name of your instance.
In the Resources panel, click Attached Block Volumes.
Find your volume, click the Actions menu, and then click Detach. Confirm the detachment in the dialog box.

You might need to refresh the web page to see that the block volume is no longer attached.
Click Dashboard, and click the Block Storage/View Block Volumes button.
Select the Sandbox compartment.
Find your volume, click the Actions menu, and then click Terminate. Confirm the termination in the dialog box.

What's Next

Continue to Terminate the Instance.

Terminate the Instance

You can permanently terminate (delete) instances that you no longer need. Any attached VNICs and volumes are automatically detached when the instance terminates. Eventually, the instance's public and private IP addresses are released and become available for other instances.

Using the Compute Web UI

Click Dashboard, and click the Compute/View Instances button.
Select the Sandbox compartment.
Find the instance you created, click the Actions menu, and click Terminate.
In the Confirm Instances termination dialog box, move the "Permanently delete the attached boot volume" selector to the right. Click the Confirm button.

Moving the selector to the right results in the boot volume being permanently deleted, which is appropriate for this tutorial.

In production, you can leave the selector in the left position to preserve the boot volume for use with another instance. This is convenient when you want to reuse a configured OS or data on the boot volume.

What's Next

Continue to Delete the Subnet, Internet Gateway, and VCN.

Delete the Subnet, Internet Gateway, and VCN

Using the Compute Web UI

Click Dashboard, and click the Networking/View Virtual Cloud Networks button.
Select the Sandbox compartment.
Click the name of your VCN.
Under Resources, click Route Tables.
Click the name of the route table.
For the route rule you created, click the Actions menu, click Delete, and confirm the deletion.

The route rule is deleted.
In the breadcrumb path at the top of the page, click the name of your VCN.

The VCN details page is displayed.
Under Resources, click Internet Gateways.
For the internet gateway that you created, click the Actions menu, click Delete, and confirm the deletion.

The internet gateway is deleted.
Under Resources, click Subnets.
For the subnet you created, click the Actions menu, click Delete, and confirm the deletion.

The subnet is deleted.
At the top of the VCN details page, click the Terminate button and confirm the termination.

The VCN is deleted.

What's Next

Continue to Delete the Compartment.

Delete the Compartment

You must remove all resources from a compartment before you can delete it, otherwise, the delete action fails and the compartment returns to an Active state.

Using the Compute Web UI

In the navigation menu, click Identity, then click Compartments.
For the Sandbox compartment, click the Actions menu, and then click Delete.
Confirm the deletion in the dialog box.

Working with Instances

You can create compute 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.

For general information about instances, see Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.

Creating an Instance

See Compute Images and Tutorial – Launching Your First Instance for information about input you need to create an instance.

The following is the minimum information that you must provide to create an instance using the Compute Web UI:

A name for the instance
The compartment where you want to create the instance
An image or boot volume
A shape
A subnet
A public SSH key

To log in to the instance, users need either an SSH key or a password, depending on how the image was built. If the instance will require SSH keys for authentication, you must provide the public key when you create the instance. You cannot provide the public SSH key after the instance is created.

To create an instance using the OCI CLI, you need the same information as listed above for the Compute Web UI with the following differences:

You need the name of the availability domain where you want to create the instance.
You do not need an instance name. If you do not provide a name for the instance, the default name will be instanceYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

To modify launch options, see "Using the OCI CLI."

An alternative way to create an instance is to create an instance configuration and use that configuration to launch an instance, as described in Working with Instance Configurations and Instance Pools. When you use an instance configuration to create an instance, you can specify blockVolumes and secondaryVnics.

Using the Compute Web UI

Create or get the following resources and information:
- An image or boot volume and the compartment where the image or boot volume is located
- A virtual cloud network (VCN) and subnet and the compartment where the VCN and subnet are located
- A public Secure Shell (SSH) key if users will connect to the instance using SSH
On the Dashboard, click the Compute/Create Virtual Machine Instance button.
In the Create Instance dialog, enter the following information:
- Name: Enter a name for the instance. Instance names have the following characteristics:
  - Can be changed after the instance is created.
  - Do not need to be unique.
  - Can contain only alphanumeric characters and the hyphen (-) character.
  - Can be a maximum of 63 characters.
- Create in Compartment: Select the compartment where you want to create the instance.
- Fault Domain: (Optional) Select a fault domain. By default, the system automatically selects the best fault domain for the instance when the instance is created. If you specify a fault domain, and the requested fault domain cannot accommodate the instance, instance launch fails. The fault domain can be changed after the instance is created.
- Source Image: Select an image or boot volume.
  1. Select the Source Type: Platform Image, Custom Image, or Boot Volume.
  2. If you selected Custom Image or Boot Volume, select the compartment where the image or boot volume that you want to use is located.
  3. Select an image or boot volume from the list.
    
    If you selected Platform Image, you see a tabular list with columns Operating System, OS Version, and Image Build (the date the image was built). You can use the dropdown menu arrow to the right of the OS Version to select a different version. For example, for the Oracle Linux operating system, you can use the dropdown menu to select 8 or 7.9.
    
    If you selected Custom Image, you see a tabular list with columns Name, Operating System, and OS Version. You can use the arrows in the column headings to sort the list. You can filter the list by using the Operating System dropdown menu above the list of images.
    
    If you selected Boot Volume, you see a tabular list with columns Name, Size (GB), and Created (the date the boot volume was created). You can use the arrows in the column headings to sort the list. In the Boot Volume section (after the Shape section), you can customize the boot volume size.
    
    If the list is too long to fit in one view, use the arrow buttons to view another page of the list.
    
    To use a platform image that was previously available but is no longer listed, use the OCI CLI to create the instance and specify the OCID of the image.
  The source image cannot be changed after the instance is created.
- Shape: Select a shape. For a description of each compute instance shape, see "Compute Shapes" in Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.
  
  If you select a standard shape, the amount of memory and number of OCPUs are displayed. These numbers match the numbers shown for this shape in the table in the Oracle Private Cloud Appliance Concepts Guide.
  
  If you select the flexible shape, VM.PCAStandard1.Flex, you must specify the number of OCPUs you want and you can specify the total amount of memory you want. The default value for GBs of memory is 16 times the number you specify for OCPUs. Click inside each value field to see the minimum and maximum allowed values.
  
  The shape and shape configuration can be changed after the instance is created.
- Boot Volume: (Optional) Check the "Specify a custom boot volume size" box if you want to specify a custom boot volume size. The default value is 50 GB.
- Subnet: Select a subnet.
  1. Select a VCN from the list. You might need to change the compartment to the compartment where the VCN is located.
  2. Select a subnet.
- Public IP Address: To connect to the instance using SSH, check the Assign Public IP box to have a public IP address assigned to the instance. This box is checked by default if you specified a public subnet. If you do not check this box, or if you uncheck this box, and then want to assign a public IP address later, see Assigning an Ephemeral Public IP Address to an Instance for instructions.
- Private IP Address: (Optional) Specify an available private IP address from the subnet's CIDR. By default, a private IP address is automatically assigned.
- Hostname: (Optional) Enter a hostname if you are using DNS within the cloud network. The hostname must be unique across all VNICs in the subnet.
  
  By default, the instance name is used for the hostname. The hostname can also be configured in the OS after the instance is created.
  
  If this is a UNIX instance, see Creating a Mount Target and Mounting File Systems on UNIX-Based Instances for more information about setting the host name correctly for mounting file systems.
- SSH Keys: To connect to the instance using SSH, provide a public SSH key.
  
  Note:
  
  You cannot provide this SSH key after the instance is created.
- Initialization Script: (Optional) Provide an initialization script. This is a file of data to be used for custom instance initialization.
- Network Security Group: (Optional) By default, the new instance is not attached to any NSG. Check the box labeled Enable Network Security Group to add the primary VNIC for this instance to one or more NSGs.
  1. Select an NSG from the dropdown list. You might need to change the compartment to find the NSG you want.
  2. Click the Add Another NSG button if you want to attach to another NSG.
  3. To remove an NSG from the list, click the trash can to the right of that NSG. To remove the last NSG or all NSGs, uncheck the Enable Network Security Groups box.
  To update NSG attachments for this instance later, see Updating a VNIC.
  
  See Controlling Traffic with Network Security Groups for information about NSGs.
- Tagging: (Optional) Add defined or free-form tags for this instance as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click the Create Instance button in the dialog.

On success, the instance details page is displayed. On the Configuration tab, the Shape Configuration column shows the shape, the number of OCPUs, the network bandwidth, and the total memory. On the Networking tab, the VNIC column shows the VCN and subnet, and the Instance Access column shows the primary private IP address and any assigned public IP address.

To check the status of the instance launch, scroll to the Resources section and click Work Request(s).

If instance launch fails because of resource constraints, try remedies such as the following:
- Specify a different fault domain or do not specify any fault domain and allow the system to choose.
- Specify a less resource-intensive shape.
- Stop an instance that you do not need currently.
- Terminate an instance that you no longer need.
If the status of the work request is Failed, and no reason is given for the failure, the cause of the failure might be temporary. If no reason is given for the failure, wait a short time and then retry the instance create.

Using the OCI CLI

Create or get the following resources and information:
- The name of the availability domain that you want to use: oci iam availability-domain list
- The OCID of the compartment where you want to create the instance: oci iam compartment list
- The name of the shape for this instance. Use the following command to list the available shapes and their characteristics. Use the OCID of the compartment where you want to create the instance. To list only shapes that are compatible with the image that you plan to use, specify the image OCID. See also "Compute Shapes" in Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.
```
$ oci compute shape list --compartment-id compartment_OCID --image-id image_OCID
```
  If you specify the flexible shape, VM.PCAStandard1.Flex, then you must also specify the shape configuration, as shown in the following example. You must provide a value for ocpus. The memoryInGBs property is optional; the default value in GBs is 16 times the number of ocpus.
```
--shape-config '{"ocpus": 32, "memoryInGBs": 512}'
```
  If you specify a standard shape, do not specify --shape-config. The number of OCPUs and amount of memory are set to the values shown for this shape in "Standard Shapes" in "Compute Shapes" in Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.
  
  The shape and shape configuration can be changed after the instance is created.
- The OCID of the subnet where the VNIC that is attached to this instance will be created: oci compute vnic-attachment list
- If you provide a value for the --hostname-label option, see the description of Hostname in the preceding Compute Web UI procedure.
- One of the following to specify either an image or a boot volume.
  - The OCID of the image used to boot the instance: oci compute image list
  - The OCID of the boot volume used to boot the instance: oci compute boot-volume-attachment list
- A public Secure Shell (SSH) key to connect to the instance using SSH.
  
  Note:
  
  You cannot provide this SSH key after the instance is created.
For a complete list of required and optional parameters, use the following command:
```
$ oci compute instance launch -h
```
See the Compute Web UI procedure for characteristics of the --display-name and --hostname-label values. See Adding Tags at Resource Creation to add defined and free-form tags.

Construct an argument for the --source-details option.

The --source-details argument can be a JSON file or a command-line string. Use the following command to show the correct format of the JSON properties and values:

$ oci compute instance launch --generate-param-json-input source-details
[
  "This parameter should actually be a JSON object rather than an array - pick one of the
  following object variants to use",
  {
    "bootVolumeId": "string",
    "sourceType": "bootVolume"
  },
  {
    "bootVolumeSizeInGBs": 0,
    "imageId": "string",
    "kmsKeyId": "string",
    "sourceType": "image"
  }
]

(Optional) Construct an argument for the --launch-options option.

Only the firmware property can be changed. The default value is BIOS. You can alternatively specify UEFI_64. If you do not provide a correct value for firmware, the instance might not launch properly. You cannot update the value of the firmware property with the instance update command.

The following shows the default values:
```
{
  "bootVolumeType": "PARAVIRTUALIZED",
  "firmware": "BIOS",
  "isConsistentVolumeNamingEnabled": false,
  "is-pv-encryption-in-transit-enabled": false,
  "networkType": "PARAVIRTUALIZED",
  "remoteDataVolumeType": "PARAVIRTUALIZED"
}
```
To change the value of the firmware property, specify the following option:
```
--launch-options file://launch_options.json
```
Where the following is the content of the launch_options.json file:
```
{
  "bootVolumeType": "PARAVIRTUALIZED",
  "firmware": "UEFI_64",
  "isConsistentVolumeNamingEnabled": false,
  "is-pv-encryption-in-transit-enabled": false,
  "networkType": "PARAVIRTUALIZED",
  "remoteDataVolumeType": "PARAVIRTUALIZED"
}
```
(Optional) Construct an argument for the --metadata or --extended-metadata option.

Custom user data can be attached to the instance by using the --metadata and --extended-metadata options. Metadata key/value pairs are string/string maps in JSON format. Extended metadata can be nested JSON objects. Metadata and extended metadata have the following restrictions:
- Keys are limited to 255 characters.
- Most key values are limited to 255 characters.
  - The value of the ssh_authorized_keys key can be more than 255 characters. This value must be a valid public key in OpenSSH format.
  - The value of user_data can be a maximum of 16KB. This value is data that Cloud-Init can use to run custom scripts or provide custom Cloud-Init configuration.
- Metadata can have a maximum of 128 keys.
- The combined size of the metadata and extended metadata can be a maximum of 32,000 bytes.
SSH keys can alternatively be provided in the file argument of the --ssh-authorized-keys-file option, and user data can alternatively be provided in the file argument of the --user-data-file option. Use the -h option for more information.

In the example in the next step, the authorized keys file contains one or more public SSH keys in the format required by the SSH authorized_keys file. Use a newline character to separate multiple keys. SSH public keys can be provided as the value of the ssh_authorized_keys key in the --metadata option, or in the file argument of the --ssh-authorized-keys-file option. Use -h for more information.

Run the instance launch command.

Syntax:

oci compute instance launch --availability-domain availability_domain \
--compartment-id compartment_OCID --shape shape --subnet-id subnet_OCID \
--source-details file://image_info.json

Example:

If you are using a public subnet, a public IP address is assigned by default, or you can set the --assign-public-ip option value to true. If you need to assign a public IP address later, see Assigning an Ephemeral Public IP Address to an Instance for instructions.

$ oci compute instance launch --availability-domain ad1 \
--compartment-id ocid1.compartment.unique_ID --display-name ops1 \
--shape VM.PCAStandard1.16 --subnet-id ocid1.subnet.unique_ID --source-details \
'{"bootVolumeSizeInGBs":100,"imageId":"ocid1.image.unique_ID","sourceType":"image"}' \
--assign-public-ip true --ssh-authorized-keys-file ./.ssh/id_rsa.pub
{
  "data": {
    "agent-config": null,
    "availability-config": null,
    "availability-domain": "ad1",
    "capacity-reservation-id": null,
    "compartment-id": "ocid1.compartment.unique_ID",
    "dedicated-vm-host-id": null,
    "defined-tags": {},
    "display-name": "ops1",
    "extended-metadata": null,
    "fault-domain": "FAULT-DOMAIN-1",
    "freeform-tags": {},
    "id": "ocid1.instance.unique_ID",
    "image-id": "ocid1.image.unique_ID",
    "instance-options": null,
    "ipxe-script": null,
    "launch-mode": "PARAVIRTUALIZED",
    "launch-options": {
      "boot-volume-type": "PARAVIRTUALIZED",
      "firmware": "BIOS",
      "is-consistent-volume-naming-enabled": false,
      "is-pv-encryption-in-transit-enabled": false,
      "network-type": "PARAVIRTUALIZED",
      "remote-data-volume-type": "PARAVIRTUALIZED"
    },
    "lifecycle-state": "PROVISIONING",
    "metadata": {
      "ssh_authorized_keys": "ssh-rsa public_RSA_key"
    },
    "platform-config": null,
    "preemptible-instance-config": null,
    "region": "region_name",
    "shape": "VM.PCAStandard1.16",
    "shape-config": {
      "baseline-ocpu-utilization": null,
      "gpu-description": null,
      "gpus": null,
      "local-disk-description": null,
      "local-disks": null,
      "local-disks-total-size-in-gbs": null,
      "max-vnic-attachments": 16,
      "memory-in-gbs": 256.0,
      "networking-bandwidth-in-gbps": 24.6,
      "ocpus": 16.0,
      "processor-description": null
    },
    "source-details": {
      "boot-volume-size-in-gbs": 100,
      "image-id": "ocid1.image.unique_ID",
      "kms-key-id": null,
      "source-type": "image"
    },
    "system-tags": null,
    "time-created": "2021-09-22T20:20:04.715304+00:00",
    "time-maintenance-reboot-due": null
  },
  "etag": "92180faa-3660-446c-9559-c12a6e6111f9",
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

Use the work-requests work-request get command to monitor the status of the instance launch:

$ oci work-requests work-request get --work-request-id ocid1.workrequest.unique_ID

If the status of the work request is Failed, and no reason is given for the failure, the cause of the failure might be temporary. If no reason is given for the failure, wait a short time and then retry the instance create.

Retrieving Instance Metadata from Within the Instance

The instance metadata service (IMDS) serves information about a running instance to users who are logged in to that instance. IMDS also provides information to Cloud-Init that you can use for various system initialization tasks.

Note:

To access IMDS metadata, use an instance image that is provided by Oracle.

The IMDS metadata includes instance information such as the following:

The SSH public key that enables users to log in to the instance
Instance attached VNICs, VNIC IDs
Instance CIDR blocks

In general, the IMDS instance metadata includes the following:

The same information that you see on the details page of an instance in the Compute Web UI and in the output of the instance get command in the OCI CLI.
Custom information that you add to an instance by using the --metadata, --extended-metadata, --ssh-authorized-keys-file, and --user-data-file options of the instance launch command. This metadata cannot be updated after instance launch. For a user logged into the instance, the instance metadata is read-only.

To retrieve the IMDS instance metadata, follow these steps:

Use a cURL command to retrieve the metadata information from the HTTP endpoint.

Information is provided through an HTTP endpoint that listens on 169.254.169.254. If an instance has multiple VNICs, you must send the request using the primary VNIC.

Use the instance command to retrieve the instance metadata. Use the vnics command to retrieve the VNIC data.

Example: Instance Metadata

$ curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/instance/
{
    "availabilityDomain": "PCA",
    "faultDomain": "FAULT-DOMAIN-1",
    "compartmentId": "ocid1.compartment.unique_ID",
    "displayName": "dev1",
    "hostname": "hostname",
    "id": "ocid1.instance.unique_ID",
    "image": "ocid1.image.unique_ID",
    "metadata": {
        "ssh_authorized_keys": "public_RSA_key"
    },
    "region": "PCA",
    "canonicalRegionName": "PCA",
    "ociAdName": "PCA",
    "regionInfo": null,
    "shape": "VM.PCAStandard1.1",
    "state": "RUNNING",
    "timeCreated": 1634943279000,
    "agentConfig": null
}

To retrieve a single value, specify the key name as shown in the following example.

Example: VNIC Metadata

$ curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/vnics/
[
    {
        "vnicId": "ocid1.vnic.unique_ID",
        "privateIp": "privateIp",
        "vlanTag": 0,
        "macAddr": "00:13:97:9f:16:32",
        "virtualRouterIp": "virtualRouterIp",
        "subnetCidrBlock": "subnetCidrBlock"
    }
]

You can view all of the data for one of multiple VNICs by specifying the array index for that VNIC data, or you can retrieve a single value for that specified VNIC:

$ curl -H "Authorization: Bearer Oracle" -L http://169.254.169.254/opc/v2/vnics/0/privateIp
privateIp

Updating an Instance

In addition to updating the properties of an instance, you might want to attach additional block volumes or secondary VNICs. See Creating and Attaching Block Volumes and Creating and Attaching a Secondary VNIC. You can also specify blockVolumes and secondaryVnics when you use an instance configuration to create an instance.

If you did not add a public IP address when you created the instance, and you want to assign a public IP address now, see Assigning an Ephemeral Public IP Address to an Instance for instructions.

If the updated instance cannot run because of resource constraints, see the suggested remedies in Creating an Instance.

Using the Compute Web UI

On the Dashboard, click the Compute/View Instances button.
If the instance that you want to update is not listed, use the Compartment drop-down menu above the instances list to select the correct compartment.
For the instance that you want to update, click the Actions menu, and click the Edit option.
In the Edit instance_name dialog, make the changes.

When you update an instance by using the Compute Web UI, you can change the following:
- The name of the instance
- The fault domain
  
  When you change the fault domain of a stopped instance, the new fault domain is set in the instance properties. When you change the fault domain of a running instance, the instance is stopped, moved, and started on a new compute node in the new fault domain. See Stopping, Starting, and Resetting an Instance for how to prepare for an instance to stop. Stopping and starting an instance can take up to five minutes.
  
  If you specify a fault domain, and the requested fault domain cannot accommodate the instance, instance restart fails; the instance remains stopped. The new fault domain specification remains in the instance properties.
- The shape
  
  When you change the shape of a stopped instance, the new shape and shape configuration are set in the instance properties. When you change the shape of a running instance, the instance is stopped, reconfigured, and restarted. See Stopping, Starting, and Resetting an Instance for how to prepare for an instance to stop. Stopping and starting an instance can take up to five minutes.
  
  If you select the flexible shape, VM.PCAStandard1.Flex, you must specify the number of OCPUs you want and you can specify the total amount of memory you want. The default value for GBs of memory is 16 times the number you specify for OCPUs. Click inside each value field to see the minimum and maximum allowed values.
  
  If the specified shape and shape configuration cannot be accommodated in the fault domain, instance restart fails; the instance remains stopped. The new shape and shape configuration remain in the instance properties.
- Tags
Click the Save Changes button.

If you changed the fault domain, shape, or shape configuration of a running instance, you must confirm that you understand that the instance will be rebooted. For those changes, the instance will be stopped, reconfigured, and restarted.

Using the OCI CLI

Get the OCID of the instance that you want to update: oci compute instance list

If you want to change the fault domain of the instance, get the OCID of the fault domain:
```
$ oci iam fault-domain list --compartment-id compartment_OCID \
--availability-domain ad1
```
If you want to change the shape of the instance, get the name of the shape:
```
$ oci compute shape list --compartment-id compartment_OCID --image-id image_OCID
```
Run the instance update command.

Syntax:
```
oci compute instance update --instance-id instance_OCID \
options_with_values_to_update
```
For descriptions of instance properties that you can change, enter the following command and scroll to Optional Parameters:
```
$ oci compute instance update -h
```
See the Compute Web UI procedure for more information about changing the fault domain or shape.

If you specify the flexible shape, VM.PCAStandard1.Flex, then you must also specify --shape-config You must provide a value for ocpus. The memoryInGBs property is optional; the default value in GBs is 16 times the number of ocpus.

If you specify a standard shape, do not specify --shape-config. The number of OCPUs and amount of memory are set to the values shown for this shape in "Standard Shapes" in "Compute Shapes" in Compute Instance Concepts in the Oracle Private Cloud Appliance Concepts Guide.

Example:
```
$ oci compute instance update --instance-id ocid1.instance.unique_ID \
--shape VM.PCAStandard1.Flex --shape-config '{"ocpus": 16, "memoryInGBs": 512}'
```

Stopping, Starting, and Resetting an Instance

You can perform the following power actions on an instance:

STOP. Power off the instance. Compute resources are released and the instance is disconnected and unassigned from the compute node.

An instance that is Stopped cannot be migrated to a different compute node.
START. Power on the instance. The Compute service attempts to restart the instance in the same fault domain that it was in when it was stopped, or in the currently specified fault domain if the fault domain was updated while the instance was stopped. If the instance start operation fails, the instance remains stopped.

If the start operation fails because of resource constraints, you could specify a different fault domain for the instance (see Updating an Instance), change the configuration of the instance, or stop, reconfigure, or terminate other instances.

If the start operation fails, and no reason is given for the failure, the cause of the failure might be temporary. If no reason is given for the failure, wait a short time and then retry the instance start.

Stopping and starting an instance can take up to five minutes.
RESET. Power off the instance and then power it back on. See the descriptions of STOP and START.
SOFTSTOP. Gracefully shut down the instance by sending a shutdown command to the operating system. After waiting 15 minutes for the OS to shut down, the instance is powered off. If the applications that run on the instance take more than 15 minutes to shut down, they could be improperly stopped, resulting in data corruption. To avoid this, manually shut down the instance using the commands available in the OS before you softstop the instance. See also the description of STOP.
SOFTRESET. Gracefully reboot the instance by sending a shutdown command to the operating system. After waiting 15 minutes for the OS to shut down, the instance is powered off and then powered back on.

Before you stop or reset an instance, use operating system commands on the instance to shut down the instance to avoid issues with abruptly stopping applications that are running on the instance. You might want to do this for softstop and softreset as well, in case any application takes longer than 15 minutes to shut down.

Using the Compute Web UI

On the Dashboard, click the Compute/View Instances button.
If the instance that you want to manage is not listed, use the Compartment drop-down menu above the instances list to select the correct compartment.
For the instance that you want to manage, click the Actions menu, and click the Start, Stop, or Reset option.

Using the OCI CLI

Get the OCID of the instance that you want to stop, start, or reset: oci compute instance list
Run the stop, start, or reset command.

Syntax:
```
oci compute instance action --instance-id instance_OCID \
--action {START | STOP | RESET | SOFTSTOP | SOFTRESET}
```
For descriptions of these actions, enter:
```
$ oci compute instance action -h
```
Example:
```
$ oci compute instance action --instance-id ocid1.instance.unique_ID --action RESET
```
If you need more information about the instance state change, see the logs as described in "Accessing System Logs" in Status and Health Monitoring in the Oracle Private Cloud Appliance Administrator Guide.

Terminating an Instance

By default, the boot volume of the instance is preserved when you terminate the instance. You can attach the boot volume to a different instance as a data volume, or use it to launch a new instance. If you no longer need the boot volume, you can permanently delete it as described in Deleting a Boot Volume.

Using the Compute Web UI

On the Dashboard, click the Compute/View Instances button.
If the instance that you want to terminate is not listed, use the Compartment drop-down menu above the instances list to select the correct compartment.
Click the instance that you want to terminate.
On the instance details page, click the Controls menu and click the Terminate option.

Click Work Request(s) in the Resources box to check the status of the instance terminate.

Using the OCI CLI

Get the OCID of the instance that you want to terminate: oci compute instance list
Run the instance terminate command.

Example:
```
$ oci compute instance terminate --instance-id ocid1.instance.unique_ID
```
Use the work-requests work-request get command to check the status of the instance terminate.

Working with Instance Configurations and Instance Pools

Instance configurations and instance pools simplify the management of compute instances. An instance configuration contains settings that are used to create a compute instance. An instance pool defines a set of compute instances that is managed as a group.

Creating an Instance Configuration

An instance configuration contains settings that are used to create a compute instance.

To create an instance configuration, you must use the OCI CLI.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to create this instance configuration.
- The OCID of the compartment where you want instances that use this instance configuration to be created.
- The OCID of the subnet for instances that use this instance configuration.
- The OCID of the image or boot volume for instances that use this instance configuration.
- The name of the availability domain for instances that use this instance configuration.
- The name of the shape for instances that use this instance configuration.
- If you provide a value for the hostnameLabel property, see the description of Hostname in the Compute Web UI procedure in Creating an Instance.
Create the configuration file that is input to the configuration create command.

The configuration file is a JSON file of property/value pairs.
- The following command shows the correct syntax of the configuration file and names of properties:
```
$ oci compute-management instance-configuration create \
--generate-param-json-input instance-details > instance_details.json
```
  You do not need all of the data that is output by this command. Copy just the information you need, being careful to keep each property in its correct context.
  
  You can specify secondary VNICs and subnets.
  
  If you omit the fault domain specification, the system automatically selects the best fault domain. If you specify only a single fault domain, all instances will be placed in only that fault domain.
  
  If a fault domain that you specify does not have enough resources, instances could fail to launch:
  - When you use the launch-compute-instance command as described in Using an Instance Configuration to Launch an Instance, and you specify a fault domain in the instance configuration, only that specified fault domain will be used to launch the instance. Resource constraints could cause the instance launch to fail.
  - When you create instances in a pool, fault domains specified in the placement configuration override fault domains specified in the instance configuration. See Creating an Instance Pool for more information.
  If you omit the assignPublicIp property, a public IP address is assigned by default if you specify a public subnet. If you set this property to false and then decide to assign a public IP address later, see Assigning an Ephemeral Public IP Address to an Instance for instructions.
  
  If users will use ssh to connect to the instance, specify the SSH public key as the value of the ssh_authorized_keys property in the metadata block. You cannot add the SSH public key after the instance is created.
  
  The displayName property is used for the instance name when you use the launch-compute-instance command as described in Using an Instance Configuration to Launch an Instance. If you do not provide a value for the displayName property, the default name of instances will be instanceYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.
  
  The displayName property is ignored when you create instances in a pool as described in Creating an Instance Pool.
- The following command shows which properties are required to create an instance:
```
$ oci compute instance launch -h
```
  Scroll to the Required Parameters section. Optional parameters are described below the required parameters.
The names of the properties in the configuration file are similar to, but different from, the names of the instance launch options. Also, some of the properties are organized into groups of properties, such as createVnicDetails, shapeConfig, and sourceDetails, as shown in the following example configuration file:
```
{
  "instanceType": "compute",
  "launchDetails": {
    "availabilityDomain": "availability_domain",
    "compartmentId": "compartment_OCID",
    "createVnicDetails": {
      "assignPublicIp": true,
      "freeformTags": {
        "ConfigType": "Configuration for an XYZ instance."
      },
      "subnetId": "subnet_OCID"
    },
    "displayName": "instance_name",
    "metadata": {
      "ssh_authorized_keys": "ssh-rsa public_RSA_key"
    },
    "shape": "shape_name",
    "shapeConfig": {
      "memoryInGBs": 512,
      "ocpus": 32
    },
    "sourceDetails": {
      "bootVolumeSizeInGBs": 100,
      "imageId": "image_OCID",
      "sourceType": "image"
    }
  }
}
```
If you specify the flexible shape, VM.PCAStandard1.Flex, then you must also specify the shape configuration, as shown in the preceding example. You must provide a value for ocpus. The memoryInGBs property is optional; the default value in GBs is 16 times the number of ocpus.

If you specify a standard shape, do not specify shapeConfig.

To change the value of the firmware property, provide a value for the launchOptions property. The default value is BIOS. You can alternatively specify UEFI_64. Other properties in launchOptions cannot be changed.
```
"launchOptions": {
  "bootVolumeType": "PARAVIRTUALIZED",
  "firmware": "UEFI_64",
  "isConsistentVolumeNamingEnabled": false,
  "isPvEncryptionInTransitEnabled": false,
  "networkType": "PARAVIRTUALIZED",
  "remoteDataVolumeType": "PARAVIRTUALIZED"
}
```
Run the instance configuration create command.

Syntax:
```
oci compute-management instance-configuration create -c compartment_OCID \
--display-name IC_name --instance-details file://custom_config_file.json
```
The specified compartment is where this instance configuration will be created. This compartment could be different from the compartment specified in the instance details JSON file, which is where the instances will be created.

The specified display name is the name of the instance configuration. If you do not provide a value for the --display-name option, the default name of the instance configuration is instanceconfigurationYYYYMMDDhhmmss, where instanceconfigurationYYYYMMDDhhmmss is the creation date and time. (See Step 2 for a description of the display name specified in the instance details JSON file. )

The output of this command is the same as the output of the instance-configuration get command.

Updating an Instance Configuration

You can change the name of the instance configuration and change the tags. To change configuration such as the compartment, subnet, or image, create a new instance configuration.

Using the OCI CLI

Get the OCID of the instance configuration that you want to update: oci compute-management instance-configuration list

Run the instance configuration update command.

Example:

$ oci compute-management instance-configuration update \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID \
--defined-tags file://instcfgdeftags.json

Moving an Instance Configuration to a Different Compartment

You can move an instance configuration to a different compartment within the same tenancy. When you move an instance configuration to a different compartment, instances and instance pools created by using this instance configuration are not moved.

New instances and instance pools that are created using this instance configuration are created in the compartment specified in the instance configuration, not in the compartment to which the instance configuration has been moved.

To move an instance configuration, you must use the OCI CLI.

Using the OCI CLI

Get the following information:
- The OCID of the current compartment, and the OCID of the destination compartment: oci iam compartment list
- The OCID of the instance configuration: oci compute-management instance-configuration list

Run the instance configuration change compartment command.

Syntax:

oci compute-management instance-configuration change-compartment \
--compartment-id destination_compartment_OCID \
--instance-configuration-id instance_configuration_OCID

Deleting an Instance Configuration

An instance configuration that is being used by any pool cannot be deleted.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Configurations.
If the instance configuration that you want to delete is not listed, use the Compartment drop-down menu above the instance configurations list to select the correct compartment.
Click the name of the instance configuration that you want to delete.
On the instance configuration details page, click the Delete button.
Click the Confirm button.

Using the OCI CLI

Get the OCID of the instance configuration that you want to delete: oci compute-management instance-configuration list

Run the instance configuration delete command.

Example:

$ oci compute-management instance-configuration delete \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID
Are you sure you want to delete this resource? [y/N]: y

Using an Instance Configuration to Launch an Instance

This section shows how to use the instance configuration that you created in Creating an Instance Configuration to launch a compute instance.

This method of launching a compute instance is an alternative to the method described in Creating an Instance.

The name of the instance will be one of the following:

If the instance configuration specifies a value for the displayName property, the name of the instance will be displayName. If you use the same instance configuration with multiple launch-compute-instance commands, all instances will have the same name. Instance names are not required to be unique.
If the instance configuration does not specify a value for the displayName property, the default name of the instance will be instanceYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

Using the OCI CLI

Get the OCID of the instance configuration that you want to use to launch the instance: oci compute-management instance-configuration list
Run the instance configuration launch instance command.

Example:
```
$ oci compute-management instance-configuration launch-compute-instance \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID
```
The output of this command is the same as the output of the compute instance get command with the addition of a work request OCID. Use the work-requests work-request get command to check the status of the instance launch.

If the launch operation fails because of resource constraints, see the suggested remedies in Creating an Instance.

Creating an Instance Pool

An instance pool is a group of compute instances within the same region.

Performing operations such as reset or terminate on the pool object performs that operation on all instances that are members of the pool. Performing these operations on an individual instance that is a member of the pool does not affect any other member instances.

Creating an instance pool requires an instance configuration and a placement configuration. Instances that are added to the pool in a pool update can be created with different instance and placement configurations.

For instances in a pool, the value of the displayName property in the instance configuration is ignored. Instances in a pool are named inst-aaaaa-pool_name, where aaaaa is five random alphanumeric characters.

Placement Configuration

In addition to an instance configuration, pool creation requires a placement configuration. Values specified in a placement configuration override values specified in the instance configuration.

A placement configuration can specify fault domains, primary subnet, and secondary VNIC subnets.

Fault Domains

If you do not specify a fault domain in either the instance configuration or the placement configuration, the system automatically selects the best fault domains for the pool instances. If you specify only a single fault domain, all instances will be placed in only that fault domain. If you specify more than one fault domain, pool instances are placed in those fault domains evenly, providing better High Availability for the pool. If one fault domain cannot accommodate additional instances, instance creation stops. The system will not place more instances in one fault domain than in another fault domain.

If some instances cannot launch because of resource constraints, those instances remain in the Provisioning state and the pool remains in the Scaling state. Once size instances are launched, the pool can transition to the Running state. While the pool is in the Scaling state, pool instances that are in the Running state are available to use.

The following are examples of actions you can take if a pool instance fails to launch because of resource constraints:

Update the pool and reduce the "Number of instances" or size value.
Update the pool and change the Fault Domains specification in the Compute Web UI or in a new instance or placement configuration.
Update the pool to specify a new instance configuration that creates instances that require fewer resources.
Stop an instance that is not a member of a pool in the same fault domain where the pool instance is failing to launch because of resource constraints.
Terminate an instance that is not a member of a pool in the same fault domain where the pool instance is failing to launch because of resource constraints.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Configurations.
If the instance configuration that you want to use to create this pool is not listed, use the Compartment drop-down menu above the instance configurations list to select the correct compartment.
Click the instance configuration that you want to use for the instances in this pool.
In the Resources box, click Attached Instance Pools, and then click the Create Instance Pool button.

In the Attach Instance Pool to instance_configuration_name dialog, enter the following information:
- Name: Enter a name for the instance pool. The name does not need to be unique. This name is used in the names of the created instances.
- Create in Compartment: Select a compartment for this instance pool definition. Note that the instances in the pool will be created in the compartment that is specified in the instance configuration.
- Number of instances: Specify the number of instances to create in this instance pool.
- Pool Placement: Select the Fault Domains, VCN, and Subnet for instances in this instance pool. You can select a different compartment from which to choose the VCN and Subnet. See the descriptions of Placement Configuration and Fault Domains at the beginning of this section.
- Tagging: (Optional) Add defined or free-form tags for this instance pool as described in Adding Tags at Resource Creation. Tags can also be applied later.
  
  These tags are applied to the pool definition, not to the member instances.
Click the Create Instance Pool button.

Click Work Request(s) in the Resources box to check the status of the instance pool create.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to create the instance pool definition: oci iam compartment list
  
  Note that the instances in the pool will be created in the compartment that is specified in the instance configuration.
- The OCID of the instance configuration that you want to use: oci compute-management instance-configuration list
- The size of the instance pool. This is the number of compute instances in the instance pool.
Construct an argument for the --placement-configurations option.

See the descriptions of Placement Configuration and Fault Domains at the beginning of this section.

Use the following command to show the content of the placement configurations argument:
```
$ oci compute-management instance-pool create \
--generate-param-json-input placement-configurations > placement_configurations.json
```
Run the instance pool create command.

Syntax:
```
oci compute-management instance-pool create -c compartment_OCID \
--instance-configuration-id instance_configuration_OCID \
--placement-configurations file://placement_configuration.json \
--size number_of_instances
```
Example:
```
$ oci compute-management instance-pool create \
--compartment-id ocid1.compartment.unique_ID \
--display-name pool_name \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID \
--placement-configurations file://placement_configurations.json \
--size 10
```
The value of the --display-name option is the name of the pool. The pool name is not required to be unique. The pool name is used in the names of the instances. Instances in a pool are named inst-aaaaa-pool_name, where aaaaa is five random alphanumeric characters.

If you do not provide a value for the --display-name option, the default name of the instance pool is instancepoolYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

The output of this command is the same as the output of the instance-pool get command.

Updating an Instance Pool

When you update an instance pool, you can change anything that you set when you created the instance pool, including the name of the pool. Configuration changes do not affect existing instances; configuration changes only affect new instances. New instances will be provisioned using the new instance configuration and placement configuration.

If you increase the size of the pool, new instances are provisioned. The new instances are launched evenly across the fault domains specified by the instance configuration or the placement configuration.

If you decrease the size of the pool, instances are terminated evenly across the fault domains specified by the instance configuration or the placement configuration. In each fault domain, instances are terminated in creation date order, oldest first.

You cannot select which instances to terminate when you decrease the size of a pool. If you terminate an individual instance that is a member of a pool, as described in Terminating an Instance, a new instance is automatically provisioned to keep the pool at the specified pool size.

If you increase the size of the pool, and some new instances cannot be provisioned because of resource constraints, those instances remain in Provisioning state and the pool remains in Scaling state until all instances are provisioned. See the suggested remedies in Creating an Instance Pool.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Pools.
If the instance pool that you want to update is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.
Click the name of the instance pool that you want to update.
On the instance pool details page, click the Controls menu and click the Edit option.
When you are finished editing, click the Update Instance Pool button.

Using the OCI CLI

Get the OCID of the instance pool that you want to update: oci compute-management instance-pool list

Run the instance pool update command.

Syntax:

oci compute-management instance-pool update \
--instance-pool-id instance_pool_OCID \
options_with_values_to_update

Example:

$ oci compute-management instance-pool update \
--instance-pool-id ocid1.instancePool.unique_ID \
--instance-configuration-id new_instance_configuration_OCID --size 20

The output of this command is the same as the output of the instance-pool get command.

Stopping and Starting Instances in an Instance Pool

Performing operations such as reset or stop on the pool object performs that operation on all instances that are members of the pool. Performing these operations on an individual instance that is a member of the pool does not affect any other member instances.

When instances are stopped, compute resources are released and the instances are disconnected and unassigned from their compute nodes. When instances are started, the Compute service restarts the instances in the same fault domain that they were in when they were stopped.

Instances continue to count toward the pool size while they are stopped, and configuration of stopped pool instances is preserved. Configuration changes such as fault domain changes do not apply to pool instances that are restarted or reset.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Pools.
If the instance pool that you want to manage is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.
Click the name of the pool that you want to manage.
On the instance pool details page, click the Controls menu and click the Start, Stop, or Reboot option.

All of the instances in the pool are stopped, started, or rebooted. See Stopping, Starting, and Resetting an Instance for how to prepare for an instance to stop. Stopping and starting an instance can take up to five minutes.

In the Resources section of the pool details page, click Work Request(s) to check the status of the instance pool stop, start, or reboot. Click Attached Instances to view the status of the instances.

Using the OCI CLI

Get the OCID of the instance pool that you want to manage: oci compute-management instance-pool list

Run the instance pool stop, start, or reset command.

Syntax:

oci compute-management instance-pool {start | stop | reset | softreset} \
--instance-pool-id instance_pool_OCID

For descriptions of these commands, enter:

$ oci compute-management instance-pool -h

Example:

$ oci compute-management instance-pool reset --instance-pool-id ocid1.instancePool.unique_ID

Use the work-requests work-request get command to check the status of the instance pool management change.

Deleting an Instance Pool

When you delete an instance pool, the resources that were created by the pool are permanently deleted, including associated instances, attached boot volumes, and block volumes.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Pools.
If the instance pool that you want to delete is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.
Click the name of the pool that you want to delete.
On the instance pool details page, click the Controls menu and click the Delete option.
On the confirmation dialog, click the Confirm button.

All of the instances in the pool are terminated. Terminated instances are not attached and therefore are not listed in Attached Instances in the Resources box on the pool details page.

Click Work Request(s) in the Resources box to check the status of the instance pool delete.

Using the OCI CLI

Get the OCID of the instance pool that you want to terminate: oci compute-management instance-pool list

Run the instance pool terminate command.

Example:

$ oci compute-management instance-pool terminate \
--instance-pool-id ocid1.instancePool.unique_ID
Are you sure you want to delete this resource? [y/N]: y
{
  "etag": "34153f54-0cc9-4e6b-bc02-328166efbb4a",
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

Use the work-requests work-request get command to check the status of the instance pool terminate.

Connecting to a Compute Instance

The image that was used to create the instance might not be the most up-to-date version that is available. Best practice is to check for and install operating system updates whenever you log in to an instance, especially when you log in for the first time.

Prerequisites

You need the following information to connect to an instance:

The public IP address of the instance.

You can get the address from the Instance Details page in the Compute Web UI. Click Dashboard, and click the Compute/View Instances button. Click the name of your instance. On the instance details page, click the Networking tab. The Public IP Address is in the Instance Access section.
For UNIX instances: The full path to the private key portion of the SSH key pair that you used when you launched the instance.

For more information about key pairs, see Managing Key Pairs.
The initial user name for the instance.

The initial user name for an instance is determined by the image that was used to create the instance. Images fall into these categories:
- Images provided with Private Cloud Appliance:
  
  If you used an image that is provided with the appliance such as Oracle Linux or Oracle Solaris to launch the instance, the user name is opc.
- Custom images:
  
  The initial user depends on how the image was configured before it was imported as a custom image.
(In some circumstances) The initial user password.

The initial user password for an instance is determined by the image that was used to create the instance. Images fall into these categories:
- Images provided with Private Cloud Appliance:
  
  Instances launched using an Oracle Linux or Oracle Solaris image that was provided by Oracle use SSH to authenticate a user, and there is no initial password required.
- Custom images:
  
  The initial password depends on how the image was configured before it was imported as a custom image.

Managing Key Pairs

The method you use to log into an instance depends on how the image that was used to launch the instance was configured.

Images provided with Private Cloud Appliance launch instances that use an SSH key pair instead of a password to authenticate a remote user. These images also include the cloud-init toolkit (required for SSH authentication) in launched instances.
Custom images might be configured with the cloud-init toolkit and use SSH for authentication, or the image might be configured to use its own set of credentials to authenticate a user. For example, the image might require a password. If the image requires a password, you don't need to create an SSH key pair.

Note:

Only instances that were created with the cloud-init toolkit can use SSH key pairs.

A key pair consists of a private key and public key. You keep the private key on your computer and provide the public key when you create an instance. When you connect to the instance using SSH, you provide the path to the private key in the SSH command.

You can have as many key pairs as you want, or you can keep it simple and use one key pair for all or several of your instances.

To create your own key pairs, you can use a third-party tool such as OpenSSH on UNIX systems (including Linux, Oracle Solaris, BSD, and macOS) or PuTTY Key Generator on Microsoft Windows.

Required SSH Public Key Format

If you provide your own key pair, it must use the OpenSSH format.

A public key has the following format:

      
        key_type> <public_key> <optional_comment

For example, an RSA public key looks like this:

ssh-rsa AAAAB3BzaC1yc2EAAAADAQABAAABAQD9BRwrUiLDki6P0+jZhwsjS2muM
...
yXDus/5DQ== rsa-key-20201202

For images provided with the appliance, these SSH key types are supported: RSA, DSA, DSS, ECDSA, and Ed25519.

If you bring your own image, you're responsible for managing the SSH key types that are supported.

For RSA, DSS, and DSA keys, a minimum of 2048 bits is recommended. For ECDSA keys, a minimum of 256 bits is recommended.

Prerequisites

If you're using a UNIX system, you probably already have the ssh-keygen utility installed. To determine whether it's installed, type ssh-keygen on the command line. If it's not installed, you can download OpenSSH for UNIX from http://www.openssh.com/portable.html and install it.
If you're using a Microsoft Windows operating system, you will need PuTTY and the PuTTY Key Generator. Download PuTTY and PuTTYgen from https://www.putty.org and install them.

Creating an SSH Key Pair on the Command Line

Open a shell or terminal for entering the commands.
At the prompt, enter ssh-keygen and provide a name for the key when prompted. Optionally, include a passphrase.

The keys will be created with the default values: RSA keys of 2048 bits.
Do one of the following:
- On UNIX systems:
  
  Use this command to set the file permissions so that only you can read the private key file:
```
chmod 400 private_key_file
```
  private_key_file is the full path and name of the file that contains the private key associated with the instance you want to access.
- On a Microsoft Windows system using OpenSSH:
  1. In Windows Explorer, navigate to the private key file, right-click the file, and then click Properties.
  2. On the Security tab, click Advanced.
  3. Ensure that the Owner is your user account.
  4. Click Disable Inheritance, and then select Convert inherited permissions into explicit permissions on this object.
  5. Select each permission entry that is not your user account and click Remove.
  6. Ensure that the access permission for your user account is Full control.
  7. Save your changes.

Creating an SSH Key Pair Using PuTTY Key Generator

Perform this procedure on your Microsoft Windows system.

Open puttygen.exe.

For example, navigate to C:\Program Files\PuTTY and double-click puttygen.exe.

The PuTTY Key Generator window opens.
Specify a key type of SSH-2 RSA and a key size of 2048 bits.
- Click the Key menu at the top of the window, and confirm that the default value of SSH-2 RSA key is selected.
- In the Parameters area at the bottom of the window, enter 2048 in the field for the Number of bits in a generated key.
Click the Generate button.
Move your mouse around the blank area in the PuTTY window to generate random data in the key.

As you move your mouse, you should see the green progress bar advance.

When the progress bar is full, the key is generated. Generating the key can take several seconds to several minutes.

When the key generation is complete, the public key appears in the window under Public key for pasting into OpenSSH authorized_keys file.
Leave the Key passphrase field blank.
Click the Conversions menu at the top of the window, and then click Export OpenSSH key.

When prompted to save this key without a passphrase, click Yes.
When prompted to save the private key, select a location and name of your choice.
Select all of the generated key that appears under Public key for pasting into OpenSSH authorized_keys file, copy it using Ctrl+C, paste it into a text file, and then save the file in the same location as the private key. (Do not use Save public key because it does not save the key in the OpenSSH format.)

You can name the key anything you want, but for consistency, use the same name as the private key and a file extension of .pub. For example, mykey.pub.
Do one of the following:
- On a UNIX systems:
  
  Use the following command to set the file permissions so that only you can read the private key file:
```
chmod 400 private_key_file
```
  private_key_file is the full path and name of the file that contains the private key associated with the instance you want to access.
- On a Microsoft Windows system:
  1. Navigate to the private key file, right-click on the file, and then click Properties.
  2. On the Security tab, click Advanced.
  3. Ensure that the Owner is your user account.
  4. Click Disable Inheritance, and then select Convert inherited permissions into explicit permissions on this object.
  5. Select each permission entry that is not your user account and click Remove.
  6. Ensure that the access permission for your user account is Full control.
  7. Save your changes.
Note the names and location of your public and private key files. You will need the public key when launching an instance. You will need the private key to access the instance via SSH.

Connecting to a Linux or Oracle Solaris Instance

You can connect to a running instance by using a Secure Shell (SSH) or Remote Desktop connection. Most UNIX systems include an SSH client by default.

Note:

If you created an instance without an SSH key, you can stop the instance, attach the boot volume to a new instance, and configure SSH on the new instance.

Connecting from a UNIX System

Open a terminal window or shell.
Use this command to connect to the instance:
```
ssh –i private_key_file username@public-ip-address
```
- private_key_file is the full path and name of the file that contains the private key associated with the instance you want to access.
- username is the default username for the instance. See Prerequisites.
- public-ip-address is your instance IP address that you can get from the Compute Web UI. See Get the Instance IP Address.

Connecting from Microsoft Windows Using OpenSSH

Open Windows PowerShell.
Use this command to connect to the instance:
```
ssh –i private_key_file username@public-ip-address
```
- private_key_file is the full path and name of the file that contains the private key associated with the instance you want to access.
- username is the default username for the instance. See Prerequisites.
- public-ip-address is your instance IP address that you can get from the Compute Web UI. See Get the Instance IP Address.

Connecting from Microsoft Windows Using PuTTY

Use the following procedure if the instance uses a key pair that you created using PuTTY Key Generator as described in Creating an SSH Key Pair Using PuTTY Key Generator.

Open PuTTY.
In the Category pane (on the left), select Session and enter the following:
- Host Name (or IP address): username@public-ip-address
  - username is the default username for the instance. For instances launched from images provided with Private Cloud Appliance, the default username is opc.
  - public-ip-address is your instance IP address.
- Port: 22
- Connection type: SSH
In the Category pane, expand Window, and then select Translation.
In the Remote character set drop-down list, select UTF-8. The default locale setting on Linux instances is UTF-8, and this setting configures PuTTY to use the same locale.
In the Category pane, expand Connection, expand SSH, and then click Auth.
Click Browse, and then select your .ppk private key file.
Click Open to start the session.

If this is your first time connecting to the instance, you might see a message that the server's host key is not cached in the registry. Click Yes to continue the connection.

Tip:

If the connection fails, you might need to update your PuTTY proxy configuration.

Next Actions

Add storage. See Block Volume Storage, Object Storage, and File System Storage.
Install software on the instance.
Configure and enable additional users to connect to your instance.

The utilities you use to perform the administrative tasks vary depending on the type of OS in the instance. For additional administrative information, refer to the documentation for the OS. These documentation libraries provide helpful information:

Connecting to a Microsoft Windows Instance

You can connect to a Microsoft Windows instance using a Remote Desktop connection. Most Microsoft Windows systems include a Remote Desktop client by default.

Enabling Remote Desktop Protocol Access

To enable Remote Desktop Protocol (RDP) access to the Microsoft Windows instance, you need to add a stateful ingress security rule for TCP traffic on destination port 3389 from source 0.0.0.0/0 and any source port. You can implement this security rule in either a network security group that the Microsoft Windows instance belongs to, or a security list that is used by the instance's subnet.

Using the Compute Web UI

Click Dashboard, and click the Networking/View Virtual Cloud Networks button.
Select the compartment where your VCN is located.
Click the the name of the VCN for which you want to enable RDP access.
Perform one of the following actions:
- Add an ingress security rule to an NSG:
  
  NSG security rules provide a virtual firewall for cloud resources in the VCN.
  1. On the VCN details page, under Resources, click Network Security Groups.
  2. Click the name of the network security group for which you want to add a rule.
  3. On the network security group details page, under Resources, click Security Rules, and click the Create Security Rules button.
  4. In the Create New Network Security Group Rules dialog, click Allow Rules for Ingress, and enter the following values for the rule:
    - Stateless: Leave the check box empty to indicate stateful.
    - Ingress Type: CIDR
    - Ingress CIDR: 0.0.0.0/0
    - IP Protocol: TCP
    - Source Port Range: Leave empty to indicate All.
    - Destination Port Range: 3389
    - Description: An optional description of the rule.
  5. Click the Create button in the dialog.
- Add an ingress rule to a VCN security list:
  
  Security list rules provide a virtual firewall for instances that use this VCN.
  1. On the VCN details page, under Resources, click Security Lists.
  2. Click the name of the security list for which you want to add a rule.
  3. On the security list details page, under Resources, click Ingress Rules, and click the Create Ingress Security Rule button.
  4. In the Create Security List Rule dialog, enter the following values for the rule:
    - Stateless: Leave the check box empty to indicate stateful.
    - Ingress CIDR: 0.0.0.0/0
    - IP Protocol: TCP
    - Source Port Range: Leave empty to indicate All.
    - Destination Port Range: 3389
    - Description: An optional description of the rule.
  5. Click the Create Security List Rule button in the dialog.

Connecting with an RDP Client

Open the Remote Desktop client.
In the Computer field, enter the public IP address of the instance. You can retrieve the public IP address from the Compute Web UI. See Get the Instance IP Address.
The User name depends on how the image was configured. If you don't know the user name, consult with your administrator.

Note:

Depending on the Remote Desktop client you are using, you might have to connect to the instance before you can enter this credential.
Click Connect to start the session.
Accept the certificate if you are prompted to do so.
If you are connecting to the instance for the first time, enter the initial password that was provided to you by your administrator when you launched the instance. You will be prompted to change the password as soon as you log in. Your new password must be at least 12 characters long and must comply with the Microsoft password policy.

Otherwise, enter the password that you created. If you are using a custom image, you might need to know the password for the instance that the image was created from.
Press Enter.

Next Actions

Add storage. See Block Volume Storage, and Object Storage File System Storage.
Install software on the instance.
Configure and enable additional users to connect to your instance.

The utilities you use to perform the administrative tasks vary depending on the type of OS in the instance. For additional administrative information, refer to the documentation for the OS.

Connecting to an Instance Using a Console Connection

Important:

Instance console connections are for troubleshooting purposes only. To connect to a running instance for administration and general use, instead use a Secure Shell (SSH) or Remote Desktop connection. See Connecting to a Linux or Oracle Solaris Instance and Connecting to a Microsoft Windows Instance.

You can remotely troubleshoot malfunctioning instances using console connections. For example:

An imported or customized image that does not complete a successful boot
A previously working instance that stops responding

Prerequisites

Ensure that you have these items on the system you plan to use to connect to the instance console.

RSA SSH key pair (See Managing Key Pairs)
SSH client and command-line shell
VNC viewer
(Windows systems) plink.exe – the command link connection tool included with PuTTY. You can install PuTTY or install plink.exe separately. Refer to https://www.putty.org/.

Create an Instance Console Connection

Before you can make a connection to an instance serial console you need to create an instance console connection.

Note:

Instance console connections are limited to one client at a time. If the client fails, the connection remains active for approximately five minutes. During this time, no other client can connect. After five minutes, the connection is closed, and a new client can connect. During the five-minute timeout, any attempt to connect a new client fails.

Using the Compute Web UI

Click Dashboard, and click the Compute/View Instances button.
Select the appropriate compartment where your instance resides.
Click the name of the instance you want to connect to.
Under Resources, click Console Connection.
Click the Create Console Connection button.
Provide the public key portion for the SSH key.

In the Create Console Connection dialog, enter your public SSH key:
- Click inside the Drag and Drop box to open a file browser and select the file.
- Drag the file from your file browser listing and drop the file on the Drag and Drop box.
- Select the Paste the public key(s) button, copy your public SSH key text, and paste the text into the field.
Click the Create Console Connection button in the dialog.

What's Next

Continue to Make a VNC Connection to the Serial Console.

Make a VNC Connection to the Serial Console

After you create the console connection for the instance, you need to set up a secure tunnel to the VNC server on the instance, and then connect with a VNC client.

The VNC console connection uses SSH port forwarding to create a secure connection from your local system to the VNC server attached to your instance's console.

Caution:

Although this method is a secure way to use VNC over the internet, owners of multiuser systems should know that opening a port on the local system makes it available to all users on that system until a VNC client connects. For this reason, we don't recommend using this product on a multiuser system unless you secure the port or you isolate the VNC client by running it in a virtual environment.

Use one of the following procedures based on the type of system you are using to connect to the instance's console.

Connecting from a Linux or macOS System

This procedure sets up a secure tunnel to the VNC server on the instance using OpenSSH on Linux or macOS. macOS and most Linux and other UNIX operating systems include the SSH client OpenSSH by default.

Note:

Remote management for Remote Desktop on macOS uses port 5900. Because VNC console connections in Private Cloud Appliance also use port 5900, VNC console connections are not compatible with remote management. To use VNC console connections, disable remote management.

Using the Compute Web UI

On the instance details page, scroll to Resources, and click Console Connection.
For the active console connection, click the Actions menu, and then click Copy VNC Connection for Linux/Mac.

This places an SSH command line string in your copy/paste buffer.
Paste the connection string into a terminal window, and then press Enter to set up the secure connection.
After the connection is established, open your VNC client, specify localhost as the host to connect to, and set the port to what was listed in the string.

Connecting from a PowerShell on Microsoft Windows

Using the Compute Web UI

This procedure sets up a secure tunnel to a VNC server on the instance using PowerShell on Microsoft Windows.

On the instance details page, under Resources, click Console Connection.
Click the Actions menu, and then click Copy VNC Connection for Windows.

This places a plink.exe -ssh command line string in your copy/paste buffer.
Check the copied connection string.

The copied connection string contains the parameter -i which specifies the location of the private key file. The default value for this parameter in the connection string references an environment variable which might not be configured on your Microsoft Windows client, or it might not represent the location where the private key file is saved.

Tip:

Paste the string into a text editor where you can view and edit the value for the -i parameter before proceeding to the next step.
Paste the connection string copied into a Windows PowerShell, and then press Enter to set up the secure connection.
After the connection is established, open your VNC client and specify localhost as the host to connect to, and set the port to what was listed in the string.

Note:

When you connect, you might see a warning from the VNC client that the connection is not encrypted. Because you are connecting through SSH, the connection is secure, so this warning is not an issue.

Backing Up and Restoring an Instance

Oracle Private Cloud Appliance supports backing up and restoring instances. The instance backup is created in an Object Storage bucket. From there, you copy it to another server in your data center for safekeeping. When needed, you can import the backup into any Private Cloud Appliance 3.x Object Storage bucket, and use it to create instances.

The backup and restore process involves using a series of Compute API commands as described in the following sections.

For conceptual information about backing up and restoring instances, refer to Instance Back Up and Restore in Compute Instance Concepts.

Task Map - Backing Up an Instance

No.	Task	Links
1.	Ensure that you have an Object Storage bucket in the same tenancy where the instance is located.	Listing Buckets Creating a Bucket
2.	Create the instance backup.	Creating an Instance Backup
3.	Transfer the backup object from Object Storage to another system in your data center.	Transferring an Instance Backup to Another System

Task Map – Restoring an Instance From a Backup

The following tasks assume that you are restoring an instance from a backup that is on another system in your data center. If the backup is already on the Private Cloud Appliance where you plan to restore the instance, start with task number 3.

No.	Task	Links
1.	Ensure that you have an Object Storage bucket in the same tenancy where you plan to restore the instance.	Listing Buckets Creating a Bucket
2.	Upload the backup to the bucket.	Transferring an Instance Backup From Another System to Private Cloud Appliance
3.	Identify the backup OCID.	Listing Instance Backups
4.	Import the backup from the bucket into the appliance.	Importing an Instance Backup
5.	Finish restoring the instance by creating an instance using the imported instance backup.	Finishing the Instance Restore

Creating an Instance Backup

This section describes how to back up an instance to an Object Storage bucket.

The instance can be running or stopped as long as the boot volume and any block volumes are attached.

The duration of the backup varies based on the amount of data on the instance boot and block volumes. A small instance that only has a 50 GB boot volume takes only a few minutes to complete. If the instance volumes are as large as 32 TB, the backup can take up to 6 hours to complete.

Caution:

During the backup process, do not perform any volume attach or detach operations on the instance.

Prerequisites

You must have an Object Storage bucket in the tenancy where the instance is located. See Creating a Bucket.
Quiesce instance activities such as running applications so that the backup is created at a known state.

Using the Compute Web UI

In the navigation menu, under Compute, click Instances.
If needed, select the compartment where your instance is located.
Click the name of the instance you plan to back up.
Click Controls and select Export.
In the dialog box, select these items:
- If needed, change the compartment to the compartment where the bucket with the backup is located by clicking (Change).
- Select the Bucket.
Click Create Export.
To see the progress, under Resources, click Work Requests.
To see the status of an instance backup, under Resources, click Instance Exports.

To transfer the backup to another server or to another appliance, see Transferring an Instance Backup to Another System.

Using the Compute API

export API – Creates an instance backup to an Object Storage bucket in the specified compartment.

API Endpoint

https://<mgmt_node_VIP>:30003/20160918/instances/<instance_OCID>/actions/export

where:

<mgmt_node_VIP> is the management node VIP host name or IP address.
<instance_OCID> is the instance ID.

Pass these key-value pairs:

{
	"bucketName": "<bucket_name>",
	"destinationType": "objectStorageTuple",
	"namespaceName": "<namespace_name>",
	"compartmentId": "<bucket_compartment_OCID>"
}

You can verify that the instance backup completed by using commands described in Listing Instance Backups.

Listing Instance Backups

The procedures in this section show you how to list backups for a given instance.

When you list instance backups, you are able to identify these components of the backup:

Backup OCID
Boot volume OCID
Instance OCID
Image OCID

Using the Compute Web UI

In the navigation menu, under Compute, click any of the following links.
- Instance Exports: Displays the list of instance backups.
- Instance Imports: Displays the list of imported instance backups that can be used to create new instances.

Using the Compute API

There are two API endpoints for viewing instance backups:

List All Instance Backups in a Bucket.

API endpoint
```
https://<mgmt_node_VIP>:30003/20160918/instances/instanceBackups?compartmentId=<bucket_compartment_OCID>
```
where:
- <mgmt_node_VIP> is the management node VIP host name or IP address.
- <bucket_compartment_OCID> is the compartment ID where the Object Storage bucket is located.
Get Instance Backup Details

API endpoint
```
https://<mgmt_node_VIP>:30003/20160918/instanceBackups/<instance_backup_id>
```
where:
- <mgmt_node_VIP> is the management node VIP host name or IP address.
- <instance_backup_id> is the backup ID, which you can get from the backup export output or from listing backups with the API.

Transferring an Instance Backup

The procedures in this section describe how to transfer an instance backup to another system and how to transfer an instance backup back to any Private Cloud Appliance 3.x.

Transferring an Instance Backup to Another System

You can use this procedure to transfer the instance backup to another system in your data center for safekeeping.

Instance backups are large files. Ensure that you have enough space on your system to store the backup. You can use the oci os object list command to display the size of the instance backup. See Viewing Objects in a Bucket.

Using the OCI CLI

Gather the information that you need to run the command.
- Namespace name (see Obtaining the Object Storage Namespace)
- Bucket name (oci os bucket list), see Listing Buckets
- Object name (oci os object list), see Viewing Objects in a Bucket

Run this command.

Syntax (entered on a single line):

oci os object get 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--name <object_name> 
--file <file_location>

<file_location> is the destination path for the file being downloaded, such as C:\workspace\backups\ocid1.instance.........uniqueID or /home/downloads/backups/ocid1.instance.........uniqueID.

Example:

oci os object get  \
--namespace-name mytenant  \
--bucket-name my-backup-bucket  \
--name ocid1.instance.........uniqueID  \
--file /home/downloads/backups/ocid1.instance.........uniqueID
Downloading object  [########################------------]   68%  00:00:05

Transferring an Instance Backup From Another System to Private Cloud Appliance

Use this procedure to transfer an instance backup from another system in your data center to an Object Storage bucket in Private Cloud Appliance.

Using the OCI CLI

Gather the information that you need to run the command.
- Namespace name. See Obtaining the Object Storage Namespace.
- Bucket name (oci os bucket list). See Listing Buckets.

Upload the instance backup to an Object Storage bucket in the target appliance.

Use the oci os object put command.

Syntax (entered on a single line):

oci os object put  \
--namespace-name <namespace_name>  \
--bucket-name <bucket_name>  \
--file <instance_backup_pathname>

The value of <instance_backup_pathname> is the path name of the object being uploaded, such as C:\workspace\backups\ocid1.instance.........uniqueID or /home/downloads/backups/ocid1.instance.........uniqueID.

Example:

oci os object put  \
--namespace-name mytenant  \
--bucket-name target-bucket  \
--file ./ocid1.instance.….….….uniqueID

Upload ID: f000bf64-9a96-4008-b1cc-f6b2595b04b1
Split file into 35 parts for upload.
Uploading object  [####################################]  100%
{
  "etag": "ef7bdd67a72536e29da97f3414f4118e",
  "last-modified": "2022-07-06T17:50:00",
  "opc-multipart-md5": "htOEPyjWDFA4Bs2urJJPRQ==-35"

Restoring an Instance from an Instance Backup

You restore an instance by importing the instance backup from an Object Storage bucket. Next, create the instance using the boot volume from the backup as the image source. Then attach any block volumes that were included in the backup.

Importing an Instance Backup

Importing an instance backup copies the backup from an Object Storage backup to a location that is internal to the appliance.

For a given instance backup, you can only have one imported copy. If you need to import the same instance backup again, you must first delete the original instance backup. See Deleting an Instance Backup.

Prerequisites

You must have an instance backup in an Object Storage bucket.

If needed, transfer the backup to Private Cloud Appliance. See Transferring an Instance Backup From Another System to Private Cloud Appliance.

Using the Compute Web UI

Identify the OCID of the backup you plan to use.

See Listing Instance Backups.
In the navigation menu, under Compute, click Instances.
Click Import.
In the dialog box, select these items:
- If needed, change the compartment to the compartment where the bucket with the backup is located by clicking (Change).
- Select the Bucket.
- Select the Backup OCID.
Click Create Import.
When the import is finished, perform the steps in Finishing the Instance Restore.

Using the Compute API

import API – Imports the instance backup from an Object Storage bucket so that instances can be created from the backup.

API endpoint

https://<mgmt_node_VIP>:30003/20160918/instanceBackups<instance_backup_OCID>/actions/import

where:

<mgmt_node_VIP> is the management node VIP host name or IP address.
<instance_backup_OCID> is the instance backup ID.

Pass these key-value pairs:

{
	"bucketName": "<bucket_name>",
	"destinationType": "objectStorageTuple",
	"namespaceName": "<namespace_name>",
	"compartmentId": "<bucket_compartment_OCID>"
}

When the import is complete, perform the steps in Finishing the Instance Restore.

Finishing the Instance Restore

Perform these steps to create as many instances as you like from the instance backup.

Create an instance in the usual fashion (See Creating an Instance). While doing so, perform these actions:
- For the source image, specify a backup boot volume instead of an image. Then select an imported instance.
- If the instance requires access using SSH, ensure that you include an SSH public key.
(Optional) Attach any block volumes that were included in the instance backup.

See Attaching a Volume.

Deleting an Instance Backup

You can use the DELETE API to delete exported and imported instance backups. The API sets the exported backup lifecycle state to TERMINATED and performs one of actions based on the type of backup:

Imported instance backups: Deletes the instance backup.
Exported instance backups: Deletes the instance backup (source for importing) from object storage bucket

Terminated instance backups are eventually cleaned up by a background task.

Using the Compute API

DELETE API – Deletes instance backups

API endpoint

https://<mgmt_node_VIP>:30003/20160918/instancesBackups<instance_backup_OCID>

where:

<mgmt_node_VIP> is the management node VIP host name or IP address.
<instance_backup_OCID> is the instance backup ID.

Tutorial – Launching Your First Instance

Task Flow to Launch an Instance

Prerequisites

Log into Oracle Private Cloud Appliance

Create a Compartment

Create a Virtual Cloud Network (VCN)

Create a Subnet

Create an Internet Gateway and Configure Route Rules

Launch an Instance

Get the Instance IP Address

Connect to Your Instance

Connect from a UNIX System

Connect Using PuTTY

Add a Block Volume

Attach the Block Volume to an Instance

(Optional) Clean Up Resources

Detach and Delete the Block Volume

Terminate the Instance

Delete the Subnet, Internet Gateway, and VCN

Delete the Compartment

Working with Instances

Creating an Instance

Retrieving Instance Metadata from Within the Instance

Updating an Instance

Stopping, Starting, and Resetting an Instance

Terminating an Instance

Working with Instance Configurations and Instance Pools

Creating an Instance Configuration

Updating an Instance Configuration

Moving an Instance Configuration to a Different Compartment

Deleting an Instance Configuration

Using an Instance Configuration to Launch an Instance

Creating an Instance Pool

Updating an Instance Pool

Stopping and Starting Instances in an Instance Pool

Deleting an Instance Pool

Connecting to a Compute Instance

Prerequisites

Managing Key Pairs

Creating an SSH Key Pair on the Command Line

Creating an SSH Key Pair Using PuTTY Key Generator

Connecting to a Linux or Oracle Solaris Instance

Connecting from a UNIX System

Connecting from Microsoft Windows Using OpenSSH

Connecting from Microsoft Windows Using PuTTY

Connecting to a Microsoft Windows Instance

Enabling Remote Desktop Protocol Access

Connecting with an RDP Client

Connecting to an Instance Using a Console Connection

Prerequisites

Create an Instance Console Connection

Make a VNC Connection to the Serial Console

Connecting from a Linux or macOS System

Connecting from a PowerShell on Microsoft Windows

Backing Up and Restoring an Instance

Creating an Instance Backup

Listing Instance Backups

Transferring an Instance Backup

Transferring an Instance Backup to Another System

Transferring an Instance Backup From Another System to Private Cloud Appliance

Restoring an Instance from an Instance Backup

Importing an Instance Backup

Finishing the Instance Restore

Deleting an Instance Backup