Scenario A: Automatically Resize VMs

This topic explains how to set up automatic resizing for virtual machines (VMs) that exceed memory.

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

This scenario involves writing a function to resize VMs and creating an alarm  that sends a message to that function. When the alarm fires, the Notifications service sends the alarm message to the destination topic, which then fans out to the topic's subscriptions. In this scenario, the topic's subscriptions include the function as well as your email. The function is invoked on receipt of the alarm message.

The Notifications service has no information about a function after it's invoked. For more details, see the troubleshooting information at Function not invoked or run.

This image shows Notifications in the context of a scenario that uses a function to resize VMs.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

If you're a member of the Administrators group, you already have the required access to execute this scenario. Otherwise, you need access to Monitoring, Notifications, and Functions. You must have FN_INVOCATION permission against the function to be able to add the function as a subscription to a topic. To resize VMs, the function must be authorized to update Compute instances. To authorize your function for access to other Oracle Cloud Infrastructure resources, such as Compute instances, include the function in a dynamic group  and create a policy to grant the dynamic group access to those resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

Setting Up This Scenario

Once you create your function to resize VMs using your preferred SDK and authorize your function to access VMs (include the function in a dynamic group and grant that dynamic group access), setup is easy in the Console. Alternatively, you can use the Oracle Cloud Infrastructure CLI or API, which lets you execute the individual operations yourself.

For more information about authorizing functions to access other Oracle Cloud Infrastructure resources, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

Function code sample
Include your function in a dynamic group
Create a policy to grant the dynamic group access to VMs (Compute instances)

Using the Console

This section walks through creating an alarm using the Console and then updating the topic created with the alarm. Your function must be deployed.

Note

Another workflow for this scenario involves creating your topic and subscriptions first, then selecting this topic when you create your alarm.

For help with troubleshooting, see Troubleshooting Notifications.

Task 1: Create the alarm
Task 2: Add an email subscription (optional)

Using the CLI

This section walks through creating the topic, subscriptions, and alarm using the CLI. Your function must be deployed.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

  1. Create a topic: Open a command prompt and run the oci ons topic create command: 

    oci ons topic create --name "Alarm Topic" --compartment-id "<compartment-ocid>"
  2. To this topic, add subscriptions referencing your function OCID and an optional email address.
    • Create a function subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>"
    • Create an email subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "EMAIL" --subscription-endpoint "john.smith@example.com"
  3. Create an alarm that defines the memory threshold and references this topic as the destination: Open a command prompt and run the oci monitoring alarm create command: 

    oci monitoring alarm create --display-name "VM Memory Alarm" --compartment-id "<compartment-ocid>" --metric-compartment-id "<compartment-ocid>" --namespace "oci_computeagent" --query-text "MemoryUtilization[1m].max() > 90" --severity "CRITICAL" --destinations "<topic-ocid>" --is-enabled true

For help with troubleshooting, see Troubleshooting Notifications.

Using the API

This section walks through creating the topic, subscriptions, and alarm using the API. Your function must be deployed.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations:

  1. CreateTopic: Create a topic.

    Example CreateTopic request
  2. CreateSubscription: To this topic, add subscriptions referencing your function OCID and an optional email address.

    Example CreateSubscription request: Function
    Example CreateSubscription request: Email
  3. CreateAlarm: Create an alarm that defines the memory threshold and references this topic.

    Example CreateAlarm request

For help with troubleshooting, see Troubleshooting Notifications.