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:

.. code:: bash

   # 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:

.. code:: ini

   [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:

.. code:: ini

   [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.