OCI Integration Guide¶
This guide documents OCI provider support in Open Resource Broker and the recommended operational flow.
For handler fields, machine data, fulfilment, and release behaviour, see the OCI Compute Instances provider reference.
Overview¶
OCI support includes:
- generated OCI catalogs with template validation, listing, and inspection
- machine acquire and return workflows through OCI compute
- provider routing via
provider_name=oci-default,provider_type=oci,provider_api=OCICompute
Installation and initialization¶
Install ORB from a source checkout (pip install .) and install the OCI CLI separately.
The provider uses the oci executable on PATH; importing ORB does not require the OCI SDK.
OCI is discovered through the orb.providers entry point.
orb init --non-interactive --provider-type oci --oci-region us-phoenix-1 --oci-credential-source instance_principal
orb templates generate
orb templates list
For a workstation, use --oci-credential-source profile --oci-profile DEFAULT.
Custom profile names are supported by --oci-profile. For Symphony, add
--scheduler hostfactory to initialization. With a custom --config-dir, pass
--config /path/to/config.json to subsequent commands.
Local browser-session authentication¶
For an existing OCI CLI session, use its profile name and select security_token
explicitly. This passes both --auth security_token and --profile to OCI CLI:
oci session authenticate --region us-phoenix-1 --profile-name ORB
orb init --non-interactive --provider-type oci --oci-region us-phoenix-1 --oci-credential-source security_token --oci-profile ORB
Use an existing session profile instead of ORB if one is already configured.
Session tokens expire; reauthenticate when needed. Provider health and credential
checks require the OCI CLI and make an authenticated oci os ns get request.
A failed probe reports unhealthy; a successful probe does not prove capacity or
permission to launch every resource.
See Oracle's token authentication guide.
Provider configuration¶
Choose exactly one OCI config baseline:
# Remote/production: ORB runs on OCI Compute with instance principal auth.
cp config/oci_config.remote.example.json config/config.json
# Local/dev: ORB runs on a workstation with an OCI CLI profile.
cp config/oci_config.local.example.json config/config.json
Run these commands from the repository root. Use the standard config.json
filename so early CLI discovery and the application load the same provider
configuration. A copied file named oci_config.json alone can leave early
discovery using defaults, even when passed with --config.
For an existing prepared configuration, copy it into place before running ORB:
cp config/oci_config.json config/config.json
export ORB_CONFIG_DIR="$PWD/config"
orb --config "$ORB_CONFIG_DIR/config.json" templates list
Remote instance-principal config uses credential_source: instance_principal and must not set profile. Local profile config uses credential_source: profile and profile: DEFAULT; DEFAULT is the standard OCI CLI profile name and can be replaced with another ~/.oci/config profile.
Remote provider block:
{
"provider": {
"providers": [
{
"name": "oci-default",
"type": "oci",
"enabled": true,
"config": {
"region": "us-phoenix-1",
"credential_source": "instance_principal"
}
}
]
}
}
OCI templates keep shape and sizing examples in the packaged src/orb/providers/oci/config/oci_templates.json. Deployment-specific values such as image OCID, subnet OCID, compartment OCID, NSGs, SSH keys, tags, and user data live in provider_defaults.oci.template_defaults in the config file.
orb templates list displays resolved templates, so it includes values inherited
from that deployment configuration. These values are not added to the shipped
catalog. The examples contain no default bootstrap script or environment tag;
add your own only when required by your deployment. ARM/HPC image placeholders
are intentionally incomplete and override a shared x86 image. See
catalog examples and configured templates
for how to interpret the output and prepare a selected template.
Build release artifacts from a clean checkout containing no local deployment configuration. Inspect source archives and container inputs before distribution. Keep deployment configs, private keys, OCI session files, logs, and live-canary reports outside release inputs. Resolved template output and reports can contain resource IDs, network details, and bootstrap data; treat them as deployment records rather than portable examples.
Broker instance-principal setup¶
Create a Python virtual environment for the broker using a Python version supported by ORB. Worker images need the runtime required by their own workload and bootstrap.
Create a dynamic group matching the broker instance explicitly, for example:
For a broker provisioning into one compartment, the tested policy grants are:
Allow dynamic-group <broker-group> to manage instance-family in compartment id <worker-compartment-ocid>
Allow dynamic-group <broker-group> to use volume-family in compartment id <worker-compartment-ocid>
Allow dynamic-group <broker-group> to use virtual-network-family in compartment id <worker-compartment-ocid>
Allow dynamic-group <broker-group> to use compute-clusters in compartment id <worker-compartment-ocid>
The compute-cluster grant is needed for RDMA cluster placement. These statements assume the worker subnet, NSGs, custom image, and cluster are in that compartment; adjust policy scope when resources are elsewhere. Membership must not include workers merely because they share the broker's compartment. See Oracle's instance-principal guide.
Install ORB and OCI CLI in virtual environments on the broker, configure
credential_source: instance_principal, and verify API access there before a live
canary. No OCI profile, user private key, or workstation session token is needed
on the broker. A profile-based workstation canary does not validate this path.
Use the one-machine gate below from the broker itself, then independently inspect
worker termination and boot-volume cleanup. Remove temporary validation IAM grants
when retiring a disposable test broker.
Authentication precedence¶
OCI CLI auth selection order:
- provider config
credential_source ORB_OCI_CREDENTIAL_SOURCEOCI_CLI_AUTH- profile fallback
Supported credential source values:
instance_principalresource_principalapi_keysecurity_token(requires a session profile)profiledefault
Template contract (OCI)¶
See Compute templates and Flex sizing for AMD E5/E6, Intel, Ampere, Standard, and DenseIO coverage, including image architecture and DenseIO sizing requirements.
Required fields for reliable launches:
image_idfrom template defaultssubnet_ids[0]from template defaultscompartment_idfrom template defaults- shape from the template
machine_types,shape,instance_type, or defaults
Recommended:
ssh_authorized_keysuser_data(base64 cloud-init)
Runtime flow¶
For BM.Optimized3.36 workers in an RDMA network group, see
Compute Clusters and RDMA. The
oci-bm-optimized3-rdma example requires its own HPC image, compute cluster OCID,
and matching availability domain; replace its placeholders before requesting nodes.
After filling the deployment defaults in config/config.json, generate and
list templates. Generation writes the provider-owned catalog into the configured
template directory; defaults are resolved when those templates are loaded.
export ORB_CONFIG_DIR="$PWD/config"
orb --config "$ORB_CONFIG_DIR/config.json" templates generate
orb --config "$ORB_CONFIG_DIR/config.json" templates list
orb --config "$ORB_CONFIG_DIR/config.json" templates validate oci-vm-flex-ondemand-small
Skip generation if you already copied a prepared oci_templates.json catalog;
generation replaces deployment-specific edits such as a larger boot volume.
The following commands provision and terminate real instances:
orb --config "$ORB_CONFIG_DIR/config.json" machines request oci-vm-flex-ondemand-small 1 --provider-name oci-default
orb --config "$ORB_CONFIG_DIR/config.json" requests show --request-id <request-id> --provider-name oci-default
orb --config "$ORB_CONFIG_DIR/config.json" machines return <instance-ocid> --provider-name oci-default
Edit OCI-specific fields in the generated catalog. Generic template create/update commands retain their existing upstream behavior.
Integration notes¶
- OCI-specific defaults, CLI options, template fields, and HostFactory mappings
are registered by
OCIPlugin; shared bootstrap and orchestration require no OCI-specific branches. - Template input accepts canonical
machine_image,machine_type, andmachine_disk_size_gbas well as the existing OCI catalog fields. - Live launch results require asynchronous polling. Status and resource discovery
return ORB's flat instance-list format, normalized machine states, and the
ProviderFulfilmentverdict required by the current request state machine. - OCI compute operations run in worker threads so CLI execution does not block the async request loop. The broker's dry-run mode is preserved across threads.
- Explicit API-key paths expand user/environment shorthand and relative paths. Credential validation rejects paths that do not identify an existing file.
- Provider-specific fields are loaded through the OCI template extension. Shared template authoring, defaults resolution, and scheduler behavior are unchanged.
- Dry-run operations never invoke the OCI CLI. Unit tests mock cloud responses; they do not establish that IAM, quotas, images, or network configuration work in a particular tenancy. Test environment variables do not enable simulation; mock workers require an explicit dry-run or mock request.
- OCI command failures report the subcommand, exit code, and structured service code/status when available. Command arguments, launch payloads, and raw CLI output are omitted because they can contain bootstrap data or keys. Timeouts and execution failures also omit the underlying command and output.
- API-key configuration is forwarded via documented child-process OCI CLI environment variables. NSGs are forwarded using the documented instance launch options.
- Pricing figures are static estimates inherited from the original implementation; use template pricing overrides for your applicable rates.
Validation checklist¶
- run OCI unit tests and provider registration tests
- verify request status transitions complete successfully
- confirm routing fields are OCI:
provider_type=ociprovider_api=OCICompute
Live one-machine canary¶
Use an isolated default-scheduler config and generated template catalog. Fill in
the real image, subnet, compartment, shape, and availability domain first. Run this
from the repository root, with the ORB virtual environment activated and the
built ORB CLI and OCI CLI available on PATH. If OCI CLI is installed in a separate
virtual environment, keep the ORB environment first: prepending the OCI CLI
environment alone also changes which python runs and can cause
ModuleNotFoundError: No module named 'orb'.
# Adapt the OCI CLI environment path if needed.
export PATH="$VIRTUAL_ENV/bin:$HOME/.venvs/orb-oci-cli/bin:$PATH"
hash -r
"$VIRTUAL_ENV/bin/python" tests/providers/oci/live/gate.py --config /path/to/config.json --template-file /path/to/oci_templates.json --provider oci-default --orb-bin "$VIRTUAL_ENV/bin/orb" --counts 1 --report-file work/oci-canary-report.json
Replace the provider name with the name from your config. The script updates the
selected catalog entry temporarily with a unique orb_canary_run tag, requests one machine, checks
its routing and private IP, verifies OCI reports it running, then returns it and
waits for OCI to confirm termination. It needs permission to list instances in the
test compartment for tag-scoped recovery after partial launches or lost responses.
Running status resolves the primary VNIC's addresses and, when configured, its
private DNS name using the subnet's real DNS domain.
Failures and interrupts trigger cleanup of this run's tagged instances and write a
hold report. Direct OCI termination is attempted if ORB return fails; such a
fallback keeps the gate failed. Cleanup failures are recorded for manual recovery.
The original catalog is restored after the test; avoid editing it during the run.
The default count is one; mock IDs and skipped cleanup cannot pass this gate.
The same gate is available through the opt-in live test:
export ORB_OCI_LIVE_CONFIG=/path/to/config.json
export ORB_OCI_LIVE_TEMPLATES=/path/to/oci_templates.json
python -m pytest tests/providers/oci/live --live -q
Troubleshooting¶
...config/config.json not found: confirmORB_CONFIG_DIRpoints to your deployment directory and that its standardconfig.jsonexists. A custom filename alone can leave early discovery using defaults, even with--config.ocid1.instance...mock...should only appear in explicit mock/dry-run mode. In live mode, OCI launch failures are returned as provider errors.- auth, region, subnet/AD, or policy mismatches can surface as
NotAuthorizedOrNotFoundduring OCI CLI verification.
Compute launch transport¶
Worker launches use OCI CLI raw-request to send the opc-retry-token header;
the high-level compute instance launch command does not expose that header.
The JSON launch body, including bootstrap metadata, is passed through a temporary
file restricted to the current user and removed after the command finishes.
Other lifecycle operations use the corresponding Compute CLI commands.
The launch endpoint uses the configured region and realm_domain_component,
which defaults to oraclecloud.com for the commercial realm. Set this provider
configuration field to the realm DNS suffix when using another OCI realm.
The suffix must be one of the realms published in the OCI SDKs
(oraclecloud.com, oraclegovcloud.com, oraclegovcloud.uk, oraclecloud.eu,
and oraclecloud<N>.com for the other published realms) or an exact domain listed
in the extra_realm_suffixes provider setting; any other value is rejected.
Entries in extra_realm_suffixes must be lowercase domains with at least two labels
and an alphabetic top-level label (a bare com is rejected). Only add domains that
Oracle owns for an OCI realm, because signed launch requests are sent to
iaas.<region>.<suffix>.