Automatic documentation update

_sources/changelog.md.txt

@@ -5,6 +5,16 @@
 Any changes which are committed, but not yet present in a released version,
 should appear here.
 
+- Yo now has support for multiple OCI regions!
+  - Previously, if you wanted to run yo against another OCI region, you needed
+    to edit your config, run `yo cache-clean`, and then run your commands.
+  - Now, Yo allows you to store configuration for several OCI regions into your
+    config. You set a default region in your config file, but you can override
+    it with the `YO_REGION` environment variable, or `yo -r REGION` on the
+    command line.
+  - Please see the documentation for a migration guide:
+    https://oracle.github.io/yo/guide/region.html#migrating-yo-ini-to-multi-region-support
+
 ## 1.6.0 - Wed, Apr 17, 2024
 
 New Features:

_sources/guide/configuration.rst.txt

@@ -34,34 +34,16 @@ in the yo source code for those.
 ~~~~~~~~~~
 
 (String, Required) Set the OCI region. This takes precedence over anything in
-``~/.oci/config``. It should match the ``availability_domain`` configs you have
-in this file, as well as the ``vcn_id`` config.
+``~/.oci/config``.
 
-``vcn_id``
-~~~~~~~~~~
-
-(String, Required) The VCN (virtual cloud network) in which your instances will
-get created. This should be an OCID as well.
-
-``subnet_id``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Whichever region you choose should be a valid OCI region. Further, you must
+include a corresponding section below, ``[regions.NAME]``, which contains
+:ref:`region-specific<regionconf>` configuration information (vcn and subnet).
 
-(String, Optional) The OCI subnet ID to which your instances will be
-connected.
-
-One of either ``subnet_id`` or ``subnet_compartment_id`` is required,
-with ``subnet_id`` being preferred if both are specified.
-
-``subnet_compartment_id``
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-(String, Optional) The OCI compartment which contains the subnets your instances
-should be created within. In OCI, the IDs of subnets change depending on which
-AD (availability domain) they're in. So, yo has a weird approach, where it lists
-every subnet in this compartment and AD, and simply picks the first one.
-
-One of either ``subnet_id`` or ``subnet_compartment_id`` is required,
-with ``subnet_id`` being preferred if both are specified.
+The region may be overridden on the command line with ``yo -r REGION``, in which
+case, a different region (with corresponding config section) will be used. Yo
+maintains separate cache information for each region. Yo commands can only
+operate in one region at a time.
 
 ``my_email``
 ~~~~~~~~~~~~
@@ -388,6 +370,47 @@ viewed in the documentation for ``-x`` in :ref:`yo_list`.
 You can override this on the command line with ``yo list -C Col1,Col2`` and you
 can extend the list on the command line with ``yo list -x Col1``.
 
+.. _regionconf:
+
+Region-Specific Configurations
+------------------------------
+
+Configurations related to the VCN and subnet used by your instance must be
+region specific. Thus, these configurations are placed in a dedicated,
+region-specific section You can select which region Yo will operate in via the
+``region`` config in the ``[yo]`` section, and override this configuration on
+the command line.
+
+The region-specific configuration sections must be named as ``[regions.NAME]``,
+replacing NAME with the region's name. For instance, ``[regions.us-ashburn-1]``.
+
+``vcn_id``
+~~~~~~~~~~
+
+(String, Required) The VCN (virtual cloud network) in which your instances will
+get created. This should be an OCID.
+
+``subnet_id``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(String, Optional) The OCI subnet ID to which your instances will be
+connected.
+
+One of either ``subnet_id`` or ``subnet_compartment_id`` is required,
+with ``subnet_id`` being preferred if both are specified.
+
+``subnet_compartment_id``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(String, Optional) The OCI compartment which contains the subnets your instances
+should be created within. In OCI, the IDs of subnets change depending on which
+AD (availability domain) they're in. So, yo has a weird approach, where it lists
+every subnet in this compartment and AD, and simply picks the first one.
+
+One of either ``subnet_id`` or ``subnet_compartment_id`` is required,
+with ``subnet_id`` being preferred if both are specified.
+
+
 .. _instance profiles:
 
 Instance Profiles

_sources/guide/index.rst.txt

@@ -13,3 +13,4 @@ User Guide
    vnc
    block
    troubleshooting
+   region

_sources/guide/region.md.txt

@@ -0,0 +1,111 @@
+# 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:
+
+```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, 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:
+
+```ini
+[yo]
+instance_compartment_id = ocid1.compartment...
+region = us-ashburn-1
+vcn_id = ocid1.vcn...
+subnet_id = ocid1.subnet...
+my_email = [email protected]
+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:
+
+```ini
+[yo]
+instance_compartment_id = ocid1.compartment...
+region = us-ashburn-1
+my_email = [email protected]
+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.

changelog.html

@@ -37,6 +37,20 @@ <h1>Changelog<a class="headerlink" href="#changelog" title="Link to this heading
 <h2>Unreleased<a class="headerlink" href="#unreleased" title="Link to this heading">¶</a></h2>
 <p>Any changes which are committed, but not yet present in a released version,
 should appear here.</p>
+<ul class="simple">
+<li><p>Yo now has support for multiple OCI regions!</p>
+<ul>
+<li><p>Previously, if you wanted to run yo against another OCI region, you needed
+to edit your config, run <code class="docutils literal notranslate"><span class="pre">yo</span> <span class="pre">cache-clean</span></code>, and then run your commands.</p></li>
+<li><p>Now, Yo allows you to store configuration for several OCI regions into your
+config. You set a default region in your config file, but you can override
+it with the <code class="docutils literal notranslate"><span class="pre">YO_REGION</span></code> environment variable, or <code class="docutils literal notranslate"><span class="pre">yo</span> <span class="pre">-r</span> <span class="pre">REGION</span></code> on the
+command line.</p></li>
+<li><p>Please see the documentation for a migration guide:
+https://oracle.github.io/yo/guide/region.html#migrating-yo-ini-to-multi-region-support</p></li>
+</ul>
+</li>
+</ul>
 </section>
 <section id="wed-apr-17-2024">
 <h2>1.6.0 - Wed, Apr 17, 2024<a class="headerlink" href="#wed-apr-17-2024" title="Link to this heading">¶</a></h2>