Overview

TEAM Cloud regions are part of the New Zealand sovereign realm, not the standard public OCI commercial realm. OCI CLI and OCI SDK tools must use the TEAM Cloud realm when constructing service endpoints.

Set the OCI_DEFAULT_REALM environment variable before running an OCI CLI command or starting an application that uses an OCI SDK.

Configure the environment variable

Linux and macOS

export OCI_DEFAULT_REALM=sovereigncloud.nz

This sets the variable for the current shell session.

To make the setting persistent for Bash, add it to the shell profile:

echo 'export OCI_DEFAULT_REALM=sovereigncloud.nz' >> ~/.bashrc
source ~/.bashrc

Users of another shell, such as Zsh, should update the corresponding shell profile instead.

Windows Command Prompt

set OCI_DEFAULT_REALM=sovereigncloud.nz

This applies only to the current Command Prompt session.

For a persistent user-level setting, run:

setx OCI_DEFAULT_REALM sovereigncloud.nz

Open a new Command Prompt window after using setx.

Windows PowerShell

$env:OCI_DEFAULT_REALM = "sovereigncloud.nz"

This applies only to the current PowerShell session.

For a persistent user-level setting, run:

[Environment]::SetEnvironmentVariable(
    "OCI_DEFAULT_REALM",
    "sovereigncloud.nz",
    "User"
)

Open a new PowerShell session before the persistent setting is available.

Configure the OCI CLI

Create and maintain the normal OCI CLI configuration file in the standard location:

• Linux and macOS: ~/.oci/config

• Windows: %UserProfile%\.oci\config

Example configuration:

[DEFAULT]
user=<user_ocid>
fingerprint=<api_key_fingerprint>
tenancy=<tenancy_ocid>
region=<team_cloud_region_identifier>
key_file=<path_to_private_key>

After the configuration file and environment variable are in place, run standard OCI CLI commands such as:

oci iam region list

or:

oci os ns get

The OCI_DEFAULT_REALM environment variable must be available in the same environment from which the OCI CLI command is executed.

Multi-realm environments

OCI_DEFAULT_REALM is a shell or process environment setting. It is not automatically associated with an OCI CLI profile.

If the same Linux or macOS workstation, build agent or integration host connects to both commercial OCI and TEAM Cloud, avoid relying on a single global or user-wide OCI_DEFAULT_REALM setting. A global setting can cause commands intended for commercial OCI to construct TEAM Cloud endpoints, or commands intended for TEAM Cloud to inherit an unexpected commercial OCI context.

Use separate OCI CLI profiles for commercial OCI and TEAM Cloud to keep credentials, tenancy and region settings separate. OCI CLI profiles separate those configuration values, but they do not independently switch the custom realm setting. For users who regularly move between commercial OCI and TEAM Cloud from the same host, reusable shell context-switching functions can make the active context explicit.

Linux and macOS Bash or Zsh example:

use-team-cloud() {
    export OCI_DEFAULT_REALM=sovereigncloud.nz
    export OCI_CLI_PROFILE=TEAM_CLOUD
    echo "OCI CLI context: TEAM Cloud"
}

use-commercial-oci() {
    unset OCI_DEFAULT_REALM
    export OCI_CLI_PROFILE=DEFAULT
    echo "OCI CLI context: Commercial OCI"
}

Use the TEAM Cloud context before running TEAM Cloud commands:

use-team-cloud
oci os ns get

Use the commercial OCI context before running commercial OCI commands:

use-commercial-oci
oci os ns get

• OCI_CLI_PROFILE selects the default OCI CLI profile, so the user does not need to add --profile to every command.

• use-team-cloud sets both the TEAM Cloud profile and the TEAM Cloud realm.

• use-commercial-oci removes the TEAM Cloud realm override and returns the CLI to the commercial OCI profile.

• Unsetting OCI_DEFAULT_REALM for commercial OCI is preferable to forcing a commercial realm value, because the OCI CLI can use its normal built-in region and realm metadata.

• The functions can be placed in ~/.bashrc or ~/.zshrc. After updating the shell configuration, reload it or open a new terminal.

• The active context applies to the current terminal session and remains active until the user switches context, changes the variables or closes the terminal.

• Confirm the active context before running destructive or production-impacting commands.

Optional verification:

echo "Profile: ${OCI_CLI_PROFILE:-DEFAULT}"
echo "Realm: ${OCI_DEFAULT_REALM:-OCI built-in default}"

Using OCI SDKs

Applications using OCI SDKs should have the same environment variable set before the application process starts:

OCI_DEFAULT_REALM=sovereigncloud.nz

The SDK application can otherwise use its normal authentication provider and OCI configuration file without modification.

Python example:

import oci

config = oci.config.from_file()

identity_client = oci.identity.IdentityClient(config)

regions = identity_client.list_regions()
for region in regions.data:
    print(region.name)

The Python process must inherit OCI_DEFAULT_REALM from its execution environment.

The same principle applies to other OCI SDKs, including Java, .NET, Go and JavaScript. Use a current OCI SDK version.

SDK region metadata options

Current OCI SDKs also support explicit region metadata for regions that are not already known to the SDK. This can be useful for SDK-based applications, especially where the application must be explicit about the region identifier and realm domain it is using.

TEAM Cloud region metadata follows the OCI region metadata schema. Example for ap-hobsonville-1:

{
  "realmKey": "OC31",
  "realmDomainComponent": "sovereigncloud.nz",
  "regionKey": "IZQ",
  "regionIdentifier": "ap-hobsonville-1"
}

SDK region metadata can be supplied using the OCI_REGION_METADATA environment variable for a single principal region, or by adding one or more regions to the SDK regions configuration file at ~/.oci/regions-config.json. For applications running on OCI compute in the target region, supported SDKs can also opt in to region lookup from the instance metadata service.

Use these SDK region metadata options in addition to the normal OCI configuration and authentication details. They do not replace tenancy, user, fingerprint, key file or profile configuration.

Oracle documents these options in Adding Regions.

Running applications as services or containers

Interactive shell configuration may not be inherited by background services, scheduled jobs or containers. Configure OCI_DEFAULT_REALM in the environment that starts the application process.

Docker

docker run \
  -e OCI_DEFAULT_REALM=sovereigncloud.nz \
  <image-name>

Docker Compose

services:
  application:
    image: <image-name>
    environment:
      OCI_DEFAULT_REALM: sovereigncloud.nz

For Windows services, Linux systemd services, CI/CD pipelines and Kubernetes deployments, configure the environment variable in the service, pipeline or workload definition rather than only in the user's interactive shell.

Kubernetes example:

env:
  - name: OCI_DEFAULT_REALM
    value: sovereigncloud.nz

Verification

Verify that the environment variable has been configured.

Linux or macOS:

echo "$OCI_DEFAULT_REALM"

Windows Command Prompt:

echo %OCI_DEFAULT_REALM%

Windows PowerShell:

$env:OCI_DEFAULT_REALM

Expected output:

sovereigncloud.nz

Then test with a simple OCI CLI command:

oci iam region list

Troubleshooting