Multiple OCI Region Support in Yo

OCI’s services are spread across datacenters in many regions. Most OCI resources are specific to one OCI region, such as instances and block devices. Further, the OCI API is region-specific, and the OCI web console only shows resources from a single region at a time.

Yo’s functionality is similar. Any Yo command can only run against a single region (e.g. yo list will only show instances of a specific region). By default, Yo runs in the region configured by the region key in the [yo] section of yo.ini. However, with proper configuration, you can override the region that Yo runs in with yo -r REGION ... for any sub-command.

Configuring multiple regions

Each region you would like to use must have its own VCN and subnet information configured, within a region-specific configuration section. For example:

[regions.us-ashburn-1]
vcn_id = ocid.vcn...
subnet_id = ocid.subnet...

[regions.us-phoenix-1]
vcn_id = ocid.vcn...
subnet_id = ocid.subnet...

Using multiple regions

The default region is selected via the region configuration key in the [yo] section. This may be overridden on the command line using yo -r REGION. The -r flag must be immediately after the yo command and before the sub-command. For example:

# CORRECT:
yo -r us-ashburn-1 list

# INCORRECT
yo list -r us-ashburn-1

If you’d like to run an entire shell session using a specific Yo region, you may set the YO_REGION environment variable, which Yo will detect and use. The environment variable may be overridden by the command line option.

Migrating yo.ini to multi-region support

Upon upgrading Yo to version 1.7.0 or later from any prior version, you may see the following warning:

warning: region-specific configurations in [yo] section are deprecated, please update your config to use [regions.*] sections

To resolve this warning, make the following changes to your ~/.oci/yo.ini configuration file:

  1. You should already have a line region = something in your configuration. We’ll refer to this value as $REGION here. First, create a new section beneath the [yo] section named [regions.$REGION]

  2. Move the configuration keys vcn_id and subnet_id (or subnet_compartment_id, if you use that instead) into the [regions.$REGION] section.

  3. Optionally, update your availability domain configurations in each instance profile to refer to the AD by number, rather than name.

For example, consider this (incomplete) configuration snippet:

[yo]
instance_compartment_id = ocid1.compartment...
region = us-ashburn-1
vcn_id = ocid1.vcn...
subnet_id = ocid1.subnet...
my_email = example@example.com
my_username = example

[instances.DEFAULT]
availability_domain = VkEH:US-ASHBURN-AD-1
shape = VM.Standard.x86.Generic
cpu = 1
mem = 8
os = Oracle Linux:9
name = ol9-1

The updated configuration would look like this:

[yo]
instance_compartment_id = ocid1.compartment...
region = us-ashburn-1
my_email = example@example.com
my_username = example

[regions.us-ashburn-1]
vcn_id = ocid1.vcn...
subnet_id = ocid1.subnet...

[instances.DEFAULT]
availability_domain = 1
shape = VM.Standard.x86.Generic
cpu = 1
mem = 8
os = Oracle Linux:9
name = ol9-1

Now, you may add more region configurations (each with its own section), and you can easily switch between these regions on the command line.