Adding Regions

You can add new regions to an Oracle Cloud Infrastructure SDK.

At a high level, there are three methods for adding a region to an SDK:

Create a regions config file on the machine running the SDK containing the region's information

Set the OCI_REGION_METADATA region metadata environment variable

If the SDK is running on an OCI instance within the region in question, programmatically opt-in to resolving the region's info from the instance metadata service

Regions Metadata Schema

The schema for a single region's metadata, regardless of method used, is as follows:

{ 
	"realmKey" : string,
	"realmDomainComponent" : string,
	"regionKey" : string,
	"regionIdentifier" : string
 }

The values for the field names above map exactly to the field names/values as described here.

The following example shows the Sydney OC1 region:

{ 
	"realmKey" : "OC1",
	"realmDomainComponent" : "oraclecloud.com",
	"regionKey" : "SYD",
	"regionIdentifier" : "ap-sydney-1"
 }

Regions Environment Variable

You can set the OCI_REGION_METADATA environment variable to specify the principal region. The value is a JSON blob, stored as a string. For example:

export OCI_REGION_METADATA='{"realmKey":"OC1","realmDomainComponent":"oraclecloud.com","regionKey":"SYD","regionIdentifier":"ap-sydney-1"}'

Regions Config File

The regions configuration file (~/.oci/regions-config.json ) enables you to provide metadata about regions which the SDK may otherwise not know about.

The Regions Configuration File will contain the metadata for one or more regions. The file's contents is a JSON array, where each item in the array is an object matching the region metadata schema.

The following example shows a valid regions configuration file:

[
	{ 
		"realmKey" : "OC1",
		"realmDomainComponent" : "oraclecloud.com",
		"regionKey" : "SYD",
		"regionIdentifier" : "ap-sydney-1"
	}
]

Programmatically Resolving from the Instance Metadata Service

The Instance Metadata Service will return the metadata for a single region - the region the instance hosting the instance metadata service is a part of. This option is not enabled by default, since the SDK may not be running within an OCI instance. This section shows examples on how to enable retrieving region metadata from the Instance Metadata Service.

Examples

This section shows examples of how to opt-in to the Instance Metadata Service.

SDK for Java

public void optInInstanceMetadataService() {

    //opt in for IMDS call by calling enableInstanceMetadataService
    Region.enableInstanceMetadataService();

    //set timeout settings for IMDS call(optional)
    Region.setInstanceMetadataServiceClientConfig(
            new ClientConfig()
                    .property(ClientProperties.CONNECT_TIMEOUT, 1000)
                    .property(ClientProperties.READ_TIMEOUT, 5000));

	//use any of the below calls to set region in client
       Region region = Region.fromRegionId("ap-sydney-1");
	myClient.setRegion(region);


	//or
	Region.registerFromInstanceMetadataService();
	myClient.setRegion("ap-sydney-1");


	//or
	Region.registerFromInstanceMetadataService();
	myClient.setRegion(Region.getRegionFromImds());
}

SDK for Python

import oci

# Set up config
config = oci.config.from_file("~/.oci/config", "DEFAULT")

# Opt-in to IMDS lookup
oci.regions.enable_instance_metadata_service()

# Create a service client
identity = oci.identity.IdentityClient(config)

# Get the current user
user = identity.get_user(config["user"]).data
print(user)

SDK for Ruby

require 'oci'

# opt-in for IMDS call
OCI::Regions.enable_instance_metadata_service

# create instance principal signer
instance_principals_signer = OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner.new

# use instance principal signer to create client
identity = OCI::Identity::IdentityClient.new(signer: instance_principals_signer)

pp identity.get_compartment(config.tenancy)

SDK for Go

import (
        "context"
        "fmt"
        "log"
        "github.com/oracle/oci-go-sdk/common"
        "github.com/oracle/oci-go-sdk/common/auth"
        "github.com/oracle/oci-go-sdk/example/helpers"
        "github.com/oracle/oci-go-sdk/identity"
)

func main() {
        // Opt in instance metadata service region info lookup
        common.EnableInstanceMetadataServiceLookup()
        provider, err := auth.InstancePrincipalConfigurationProvider()
        helpers.FatalIfError(err)
 
        tenancyID := "exampleTenancyID"
        request := identity.ListAvailabilityDomainsRequest{
                CompartmentId: &tenancyID,
        }
 
        client, err := identity.NewIdentityClientWithConfigurationProvider(provider)
 
        // Override the region, this is an optional step.
        // the InstancePrincipalsConfigurationProvider defaults to the region
        // in which the compute instance is currently running
        client.SetRegion("syd")
 
        r, err := client.ListAvailabilityDomains(context.Background(), request)
        helpers.FatalIfError(err)
 
        log.Printf("list of available domains: %v", r.Items)
}

SDK for .NET

using System;
using System.Threading.Tasks;
 
using Oci.Common;
using Oci.Common.Auth;
using Oci.IdentityService;
using Oci.IdentityService.Requests;
 
namespace Oci.Examples
{
    public class RegionIMDSExample
    {
        private static readonly NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();
 
        public static async Task MainIMDS()
        {
            // Creates an Instance Principal provider that holds authentication details of the OCI Instance
            // This helps in making API requests by the Instance without user involvement
            var instanceProvider = new InstancePrincipalsAuthenticationDetailsProvider();
 
            // Create a client for the service to enable using its APIs
            var client = new IdentityClient(instanceProvider, new ClientConfiguration());
 
            Region.EnableInstanceMetadataService();
 
            //use any of the below calls to set region in client
            Region region = Region.FromRegionId("ap-sydney-1");
            client.SetRegion(region);
 
            //OR
            Region imdsRegion = Region.RegisterRegionFromInstanceMetadataService();
            client.SetRegion(imdsRegion);
 
            // Use the client to make calls to the endpoint for the new region
            await ListAllRegions(client);
 
        }
 
        private static async Task ListAllRegions(IdentityClient client)
        {
            logger.Info("Querying for list of regions");
 
            var response = await client.ListRegions(new ListRegionsRequest { });
            foreach (var region in response.Items)
            {
                logger.Info($"Region: {region.Name}");
            }
        }
    }
}

PowerShell Modules

PS /> Import-Module OCI.PSModules.Common
PS /> Import-Module OCI.PSModules.Identity

PS /> $Region = Register-OCIRegion -EnableInstanceMetadataService

# Use this region on a cmdlet call.
PS /> Get-OCIIdentityUsersList -Region $Region.RegionId

# Or set the region as the default.
PS /> Set-OCIClientConfig -RegionID $Region.RegionId

CLI

export OCI_CLI_USE_INSTANCE_METADATA_SERVICE=true

Terraform

#Workaround for now is to use the `domain_name_override` environment setting to specify the region and realm.


# So in your Terraform configuration block, you can specify the region:
provider oci {
   region = "ap-sydney-1"
}


# And outside of Terraform, set an environment variable with the correct realm for this region like this:
export domain_name_override=oraclecloud.com
export visitIMDS=true