Stop OCI VM instance

Introduction

When running workloads on Oracle Cloud Infrastructure (OCI), managing your instances efficiently is crucial. This guide will show you how to create a simple, efficient way to shut down your OCI instance from within the instance itself, using instance metadata and instance principal authentication.

Prerequisites

• An OCI instance with instance principal authentication enabled
• OCI CLI installed on your instance
• Basic understanding of command-line operations

Understanding the Components

Instance Metadata

Every OCI instance has access to its own metadata through a local endpoint. This metadata includes crucial information like:

• Instance OCID (Oracle Cloud Identifier)
• Region
• Compartment ID
• Availability Domain

You can access this information without any authentication when querying from within the instance itself:

curl http://169.254.169.254/opc/v1/instance/id
curl http://169.254.169.254/opc/v1/instance/region

Instance Principal Authentication

Instance Principal is a secure way to authenticate OCI API calls without managing configuration files or API keys. When enabled, your instance can make API calls using its own identity.

The Basic Command

Here’s the basic command to perform a graceful shutdown:

oci compute instance action \
    --action SOFTSTOP \
    --instance-id $(curl -s http://169.254.169.254/opc/v1/instance/id) \
    --auth instance_principal \
    --region $(curl -s http://169.254.169.254/opc/v1/instance/region)

Let’s break down what each part does:

• oci compute instance action: The base command for instance operations
• --action SOFTSTOP: Specifies a graceful shutdown
• --instance-id $(...): Gets the current instance’s ID from metadata
• --auth instance_principal: Uses the instance’s identity for authentication
• --region $(...): Gets the current region from metadata

Making Life Easier with an Alias

To simplify this process, you can create an alias. Here’s how:

1. Open your shell configuration file:

nano ~/.bashrc  # for bash users
# or
nano ~/.zshrc   # for zsh users

2. Add the alias:

alias ocishutdown='oci compute instance action \
    --action SOFTSTOP \
    --instance-id $(curl -s http://169.254.169.254/opc/v1/instance/id) \
    --auth instance_principal \
    --region $(curl -s http://169.254.169.254/opc/v1/instance/region)'

3. Reload your configuration:

source ~/.bashrc  # for bash
# or
source ~/.zshrc   # for zsh

Now you can simply type ocishutdown to gracefully stop your instance!

Conclusion

By leveraging instance metadata and instance principal authentication, you can create efficient, secure ways to manage your OCI instances. This approach eliminates the need for storing credentials and simplifies instance management tasks.

Remember that while this guide focuses on shutdown operations, the same principles apply to other instance management tasks like start, reset, or even gathering instance information. Feel free to adapt these examples for your specific needs.