Oracle Cloud Hello World

Overview

Launch, list, and manage your first OCI compute instance. The most common blocker for new OCI users is the

Out of host capacity

Purpose: Get a running compute instance on OCI, including the capacity retry pattern that makes Always Free ARM shapes actually usable.

Prerequisites

• Completed

  oraclecloud-install-auth

  — valid

  ~/.oci/config

  with API key authentication
• Python 3.8+ with

  pip install oci

  installed
• A subnet OCID in your tenancy (VCN > Subnets in the Console, or use the default VCN)
• An image OCID for your region (Compute > Custom Images, or list platform images via API)
• An SSH public key at

  ~/.ssh/id_rsa.pub

  (for instance access)

Instructions

Step 1: List Existing Instances

import oci

config = oci.config.from_file("~/.oci/config")
compute = oci.core.ComputeClient(config)

instances = compute.list_instances(compartment_id=config["tenancy"])
for inst in instances.data:
    print(f"{inst.display_name:<30} {inst.lifecycle_state:<12} {inst.shape}")

Step 2: List Available Shapes and Images

# List shapes available in your tenancy
shapes = compute.list_shapes(compartment_id=config["tenancy"])
for s in shapes.data:
    ocpus = getattr(s, "ocpus", "fixed")
    print(f"{s.shape:<35} OCPUs: {ocpus}")

# List platform images (Oracle Linux)
images = compute.list_images(
    compartment_id=config["tenancy"],
    operating_system="Oracle Linux",
    sort_by="TIMECREATED",
    sort_order="DESC",
    limit=5
)
for img in images.data:
    print(f"{img.display_name:<60} {img.id[:40]}...")

Step 3: Launch an Instance (Standard)

import os

launch_details = oci.core.models.LaunchInstanceDetails(
    compartment_id=config["tenancy"],
    availability_domain="Uocm:US-ASHBURN-AD-1",  # Change for your region
    display_name="hello-oci",
    shape="VM.Standard.E4.Flex",
    shape_config=oci.core.models.LaunchInstanceShapeConfigDetails(
        ocpus=1, memory_in_gbs=8
    ),
    source_details=oci.core.models.InstanceSourceViaImageDetails(
        image_id="ocid1.image.oc1.iad.aaaa...",  # Your image OCID
        boot_volume_size_in_gbs=50
    ),
    create_vnic_details=oci.core.models.CreateVnicDetails(
        subnet_id="ocid1.subnet.oc1.iad.aaaa..."  # Your subnet OCID
    ),
    metadata={
        "ssh_authorized_keys": open(
            os.path.expanduser("~/.ssh/id_rsa.pub")
        ).read()
    }
)

response = compute.launch_instance(launch_details)
instance_id = response.data.id
print(f"Launching: {instance_id}")
print(f"State: {response.data.lifecycle_state}")

Step 4: Wait for Instance to Be Running

# Poll until RUNNING (typically 30-90 seconds)
get_instance = oci.core.ComputeClient(config)
waiter = get_instance.get_instance(instance_id)
result = oci.wait_until(
    get_instance,
    waiter,
    "lifecycle_state",
    "RUNNING",
    max_wait_seconds=300
)
print(f"Instance is RUNNING: {result.data.display_name}")

Step 5: Launch with Capacity Retry (Always Free ARM)

This is the pattern you need for

VM.Standard.A1.Flex

Out of host capacity

import time
import random

def launch_with_retry(compute_client, launch_details, max_retries=720, interval=60):
    """Retry instance launch until capacity is available.

    Default: retry every 60s for up to 12 hours (720 attempts).
    Always Free ARM shapes have intermittent capacity.
    """
    for attempt in range(1, max_retries + 1):
        try:
            response = compute_client.launch_instance(launch_details)
            print(f"Attempt {attempt}: SUCCESS — {response.data.id}")
            return response
        except oci.exceptions.ServiceError as e:
            if e.status == 500 and "Out of host capacity" in str(e.message):
                jitter = random.uniform(0, 15)
                print(f"Attempt {attempt}: Out of capacity. Retrying in {interval + jitter:.0f}s...")
                time.sleep(interval + jitter)
            else:
                raise  # Re-raise non-capacity errors
    raise RuntimeError(f"Failed after {max_retries} attempts — no capacity available")

# ARM Always Free shape
arm_details = oci.core.models.LaunchInstanceDetails(
    compartment_id=config["tenancy"],
    availability_domain="Uocm:US-ASHBURN-AD-1",
    display_name="hello-arm",
    shape="VM.Standard.A1.Flex",
    shape_config=oci.core.models.LaunchInstanceShapeConfigDetails(
        ocpus=4, memory_in_gbs=24  # Always Free max: 4 OCPUs, 24 GB
    ),
    source_details=oci.core.models.InstanceSourceViaImageDetails(
        image_id="ocid1.image.oc1.iad.aaaa...",
        boot_volume_size_in_gbs=100  # Always Free: up to 200 GB total
    ),
    create_vnic_details=oci.core.models.CreateVnicDetails(
        subnet_id="ocid1.subnet.oc1.iad.aaaa..."
    ),
    metadata={
        "ssh_authorized_keys": open(
            os.path.expanduser("~/.ssh/id_rsa.pub")
        ).read()
    }
)

launch_with_retry(compute, arm_details)

Step 6: Instance Lifecycle Operations

# Stop an instance (preserves boot volume)
compute.instance_action(instance_id=instance_id, action="STOP")

# Start a stopped instance
compute.instance_action(instance_id=instance_id, action="START")

# Reboot
compute.instance_action(instance_id=instance_id, action="RESET")

# Terminate (deletes instance, boot volume preserved by default)
compute.terminate_instance(instance_id=instance_id)

Step 7: OCI CLI Equivalent

# List instances
oci compute instance list --compartment-id <TENANCY_OCID> --output table

# Launch (CLI)
oci compute instance launch \
  --compartment-id <TENANCY_OCID> \
  --availability-domain "Uocm:US-ASHBURN-AD-1" \
  --shape "VM.Standard.E4.Flex" \
  --shape-config '{"ocpus": 1, "memoryInGBs": 8}' \
  --display-name "hello-cli" \
  --image-id <IMAGE_OCID> \
  --subnet-id <SUBNET_OCID> \
  --ssh-authorized-keys-file ~/.ssh/id_rsa.pub

# Stop / start / terminate
oci compute instance action --instance-id <INSTANCE_OCID> --action STOP
oci compute instance action --instance-id <INSTANCE_OCID> --action START
oci compute instance terminate --instance-id <INSTANCE_OCID>

Output

Successful completion produces:

• A list of existing compute instances in your tenancy
• A newly launched compute instance (standard or ARM Always Free) in RUNNING state
• The instance OCID for use in subsequent lifecycle operations
• SSH connectivity to the instance via its public IP

Error Handling

oraclecloud-install-auth

allow group <grp> to manage instances in compartment <comp>

oraclecloud-sdk-patterns

Examples

Quick instance count with CLI:

oci compute instance list --compartment-id <TENANCY_OCID> \
  --lifecycle-state RUNNING --query 'data | length(@)'

Get public IP of a running instance:

network = oci.core.VirtualNetworkClient(config)
vnic_attachments = compute.list_vnic_attachments(
    compartment_id=config["tenancy"],
    instance_id=instance_id
).data
for att in vnic_attachments:
    vnic = network.get_vnic(att.vnic_id).data
    if vnic.public_ip:
        print(f"Public IP: {vnic.public_ip}")

Resources

• OCI Compute Documentation — instance shapes, images, and lifecycle
• OCI Python SDK Reference — ComputeClient API
• OCI CLI Reference — command-line usage
• Always Free Resources — ARM shape limits (4 OCPU, 24 GB RAM, 200 GB boot)
• OCI Known Issues — capacity and service issues
• OCI Status — real-time service health

Next Steps

After launching your first instance, proceed to

oraclecloud-local-dev-loop

oraclecloud-sdk-patterns