This project provides Python and shell scripts to automate the creation of Oracle Free Tier ARM instances (4 OCPU, 24 GB RAM) with minimal manual intervention. Acquiring resources in certain availability domains can be challenging due to high demand, and repeatedly attempting creation through the Oracle console is impractical. While other methods like OCI CLI and PHP are available (linked at the end), this solution aims to streamline the process by implementing it in Python.

The script attempts to create an instance every 60 seconds or as per the REQUEST_WAIT_TIME_SECS variable specified in the oci.env file until the instance is successfully created. Upon completion, a file named INSTANCE_CREATED is generated in the project directory, containing details about the newly created instance. Additionally, you can configure the script to send a Gmail notification upon instance creation.

Note: This script doesn’t configure a public IP by default; you need to configure it post the creation of the instance from the console. (Planning on automating it soon)

In short, this script is another way to bypass the “Out of host capacity” or “Out of capacity for shape VM.Standard.A1.Flex” error and create an instance when the resources are freed up.

Features

  • Single file needs to be run after basic setup
  • Configurable wait time, OCPU, RAM, DISPLAY_NAME
  • Gmail notification
  • SSH keys for ARM instances can be automatically created
  • OS configuration based on Image ID or OS and version

Pre-Requisites

  • VM.Standard.E2.1.Micro Instance: The script is designed for a Ubuntu environment, and you need an existing subnet ID for ARM instance creation. Create an always-free VM.Standard.E2.1.Micro instance with Ubuntu 22.04. This instance can be deleted after the ARM instance creation.
  • OCI API Key (Private Key) & Config Details: Follow this Oracle API Key Generation link to create the necessary API key and config details.
  • OCI Free Availability Domain: Identify the eligible always-free tier availability domain during instance creation.
  • Gmail App Passkey (Optional): If you want to receive an email notification after instance creation and have two-factor authentication enabled, follow this Google App’s Password Generation link to create a custom app and obtain the passkey.

Setup

  1. SSH into the VM.Standard.E2.1.Micro Ubuntu machine, clone this repository, and navigate to the project directory. Change the permissions of setup_init.sh to make it executable.

    git clone https://github.com/mohankumarpaluru/oracle-freetier-instance-creation.git
    cd oracle-freetier-instance-creation
    chmod +x setup_init.sh
  2. Create a file named oci_api_private_key.pem and paste the contents of your API private key. The name and path of the file can be anything, but the current user should have read access.

  3. Create a file named oci_config inside the repository directory. Paste the config details copied during the OCI API key creation. Refer to sample_oci_config.

  4. In your oci_config, fill the key_file with the absolute path of your oci_api_private_key.pem. For example, /home/ubuntu/oracle-freetier-instance-creation/oci_api_private_key.pem.

  5. Edit the oci.env file and fill in the necessary details. Refer below for more information oci.env fields.

Run

Once the setup is complete, run the setup_init.sh script from the project directory. This script installs the required dependencies and starts the Python program in the background.

./setup_init.sh

If you are running in a fresh VM.Standard.E2.1.Micro instance, you might receive a prompt Daemons using outdated libraries. Just click OK; that’s due to updating the libraries through apt update and won’t be asked again.

View the logs of the instance creation API call in launch_instance.log and details about the parameters used (availability-domain, compartment-id, subnet-id, image-id) in setup_and_info.log.

TODO

  • Make Block Volume Size configurable and handle errors
  • Assign a public IP through the script
  • Create a list of images and OS to display before launching an instance to select

Environment Variables

Required Fields:

  • OCI_CONFIG: Absolute path to the file with OCI API Config Detail content
  • OCT_FREE_AD: Availability Domain that’s eligible for Always-Free Tier

Optional Fields:

  • DISPLAY_NAME: Name of the Instance
  • REQUEST_WAIT_TIME_SECS: Wait before trying to launch an instance again.
  • SSH_AUTHORIZED_KEYS_FILE: Give the absolute path of an SSH public key for ARM instance. The program will create a public and private key pair with the name specified if the key file doesn’t exist; otherwise, it uses the one specified.
  • OCI_IMAGE_ID: Image_id of the desired OS and version; the script will generate the image_list.json.
  • OPERATING_SYSTEM: Exact name of the operating system
  • OS_VERSION: Exact version of the operating system
  • NOTIFY_EMAIL: Make it True if you want to get notified and provide email and password
  • EMAIL: Only Gmail is allowed, the same email will be used for FROM and TO
  • EMAIL_PASSWORD: If two-factor authentication is set, create an App Password and specify it, not the email password. Direct password will work if no two-factor authentication is configured for the email.

Credits and References