# Oracle OCI In Juju, [Oracle OCI](https://docs.oracle.com/en-us/iaas/Content/home.htm) is a [machine cloud](https://documentation.ubuntu.com/juju/4.0/reference/cloud.md#machine-cloud) and works as described below. #### NOTE This reference assumes basic familiarity with Juju. If you are new to Juju, start with the [Tutorial](https://documentation.ubuntu.com/juju/4.0/tutorial.md#tutorial), then use this page together with the generic materials it links to. ## Requirements An OCI compartment OCID. All resources (VCNs, subnets, instances, volumes) are created in this single compartment. See [Bootstrap behavior](#oci-controller-bootstrap-behavior) for how to pass it to Juju. ## Concepts The following table shows how OCI abstractions map to Juju concepts: | OCI | Juju | |---------------------------------|------------------------------------------------------------------------| | Compute instance | [machine](https://documentation.ubuntu.com/juju/4.0/reference/machine.md#machine) | | Process on an instance | [unit](https://documentation.ubuntu.com/juju/4.0/reference/unit.md#unit) | | Group of units for one workload | [application](https://documentation.ubuntu.com/juju/4.0/reference/application.md#application) | | Block volume | [storage](https://documentation.ubuntu.com/juju/4.0/reference/storage.md#storage) | | VCN/subnet | Network spaces and placement targets (roughly) | | Availability domain | Placement target (`zones`) | ## The cloud See also: [Cloud](https://documentation.ubuntu.com/juju/4.0/reference/cloud.md#cloud), [Juju | Manage clouds](https://documentation.ubuntu.com/juju/4.0/howto/manage-clouds.md#manage-clouds), [Terraform Provider for Juju | Manage clouds](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-clouds/#manage-clouds) As for all machine clouds, the cloud is registered in Juju via a cloud definition, stored in `clouds.yaml` on the client (on Linux: `~/.local/share/juju/clouds.yaml`) and following this schema: ```yaml clouds: : # Predefined name type: oci auth-types: - # See Authentication types below regions: : # e.g. us-phoenix-1 endpoint: # Region-specific OCI API endpoint config: # Optional: model config defaults : # See Configuration keys below ``` ## Credentials See also: [Credential](https://documentation.ubuntu.com/juju/4.0/reference/credential.md#credential), [Juju | Manage credentials](https://documentation.ubuntu.com/juju/4.0/howto/manage-credentials.md#manage-credentials), [Terraform Provider for Juju | Manage credentials](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-credentials/#manage-credentials) As for all machine clouds, credentials are stored in `credentials.yaml` on the client and follow this schema: ```yaml credentials: oracle # Predefined cloud name for OCI : # User-defined credential name auth-type: # httpsig (the only type) : # Auth-type-specific attributes (see below) ``` ### Authentication types Oracle OCI supports the following authentication types: #### `httpsig` Attributes: - `user`: Username OCID (required). - `tenancy`: Tenancy OCID (required). - `key`: PEM encoded private key (required). - `pass-phrase`: Passphrase used to unlock the key (required). - `fingerprint`: Private key fingerprint (required). - `region`: DEPRECATED – Region to log into (optional). ## Controllers See also: [Controller](https://documentation.ubuntu.com/juju/4.0/reference/controller.md#controller), [Juju | Manage controllers](https://documentation.ubuntu.com/juju/4.0/howto/manage-controllers.md#manage-controllers), [Terraform Provider for Juju | Manage controllers](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-controllers/#manage-controllers) ### Bootstrap behavior Creates a controller instance on OCI by provisioning the required network and compute resources, then waiting for them to become ready. All resources are created in a single OCI compartment – you must specify it via the `compartment-id` model configuration key: `juju bootstrap --config compartment-id= oracle oracle-controller`. ### Resources created at bootstrap The controller runs on an OCI instance provisioned using the same mechanisms as workload machines – see [Resources created per machine](#oci-machine-resources-created-per-machine) for the full per-machine resource model. Controller-specific differences are noted below. **Compute** - **Controller instance**: Boot volume (minimum 50 GiB), VNIC with optional public IP, and instance type from constraints (default flexible shape). - **Freeform tags**: All resources tagged with `JujuController=`, `JujuModel=`. Controller instances also tagged `JujuIsController=true`. **Networking** - **Virtual Cloud Network (VCN)**: CIDR block from `address-space` config (default: `10.0.0.0/16`). Name: `juju-vcn--`. - **Security list**: Permissive by default – allows all ingress/egress (`0.0.0.0/0`, all protocols). Name: `juju-seclist--`. Applied at subnet level. - **Internet gateway**: Enables public internet routing for the VCN. - **Route table**: Default route `0.0.0.0/0` to Internet Gateway. Name: `juju-rt--`. - **Subnets**: One per availability domain. CIDR `/24` auto-selected from VCN address space. Name: `juju---`. - **Availability-domain layout**: Bootstrap discovers region availability domains and prepares network resources for each one. ## Models See also: [Model](https://documentation.ubuntu.com/juju/4.0/reference/model.md#model), [Juju | Manage models](https://documentation.ubuntu.com/juju/4.0/howto/manage-models.md#manage-models), [Terraform Provider for Juju | Manage models](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-models/#manage-models) ### Configuration keys Oracle OCI supports the following [cloud-specific model configuration keys](https://documentation.ubuntu.com/juju/4.0/reference/configuration/list-of-model-configuration-keys.md#model-config-cloud-specific-key): **Compute** - **`compartment-id`**: The OCID of the compartment in which Juju has access to create resources. Type: `string`. Default: `""`. **Networking** - **`address-space`**: The CIDR block to use when creating default subnets. The subnet must have at least a `/16` size. Type: `string`. Default: `"10.0.0.0/16"`. ## Machines See also: [Machine](https://documentation.ubuntu.com/juju/4.0/reference/machine.md#machine), [Juju | Manage machines](https://documentation.ubuntu.com/juju/4.0/howto/manage-machines.md#manage-machines), [Terraform Provider for Juju | Manage machines](https://canonical.com/juju/docs/terraform-provider-juju/latest/howto/manage-machines/#manage-machines) ### Constraints Oracle OCI supports the following [constraints](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint): **Compute** - [arch](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-arch). Valid values: `amd64`, `arm64`. - [cores](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-cores) - [instance-type](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-instance-type). Valid values: Any OCI shape. Examples: `VM.Standard.E4.Flex` (flexible VM), `BM.Standard.E4.Bare` (bare metal), `VM.Standard.A1.Flex` (Ampere ARM), `BM.GPU.A100-v2` (GPU). - [mem](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-mem) **Networking** - [allocate-public-ip](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-allocate-public-ip) - [zones](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-zones). Specifies availability domain. Example: `zones=us-phoenix-1:AD-1`. **Storage** - [root-disk](https://documentation.ubuntu.com/juju/4.0/reference/constraint.md#constraint-root-disk) ### Placement directives Oracle OCI supports the following [placement directives](https://documentation.ubuntu.com/juju/4.0/reference/placement-directive.md#placement-directive): - [](https://documentation.ubuntu.com/juju/4.0/reference/placement-directive.md#placement-directive-machine) - [zone=](https://documentation.ubuntu.com/juju/4.0/reference/placement-directive.md#placement-directive-zone) ### Resources created per machine Applies to all machines, including controller machines. Controller-specific defaults are documented in [Resources created at bootstrap](#oci-controller-resources-created-at-bootstrap). **Compute** - **Compute instance**: Shape from constraint (default flexible shape). Image auto-selected by OS and architecture. - **Availability-domain selection**: Without `zones` constraints, Juju launches machines in the first available AD. With `zones`, Juju targets the specified AD. - **Flexible shape configuration** (if applicable): For flexible shapes (e.g., `VM.Standard.A1.Flex`), OCPUs and memory are set from constraints or defaults. - **Instance metadata**: Bootstrap metadata is written for instance initialization. VMs can query the OCI metadata service at `169.254.169.254`. - **Freeform tags**: `JujuController=`, `JujuModel=`. User-provided tags from instance config. **Networking** - **VNIC**: Created during instance launch. Subnet: first subnet of target availability domain. Private IP auto-assigned. Public IP optional (default enabled). **Storage** - **Boot volume**: Created during instance launch. Size: minimum 50 GiB, maximum 16 TiB. From `root-disk` constraint or default 50 GiB. Lifecycle tied to instance. - **Additional block volumes** (optional): Created when storage is specified. Attached over iSCSI with CHAP enabled. Must be in same availability domain as the instance. ### Networking behavior - **VCN architecture**: One VCN per model. All machines in model share VCN. - **Subnet selection**: One subnet per availability domain. Instance uses first subnet of its target AD. - **IP address management**: Private IPs obtained via `Networking.GetVnic()` after VNIC attachment. Public IPs optional, queried from same VNIC. Private scope: `ScopeCloudLocal`. Public scope: `ScopePublic`. - **Security model**: Network-level security list (all ports open by default) applied at subnet level. Instance-level firewall via SSH – `open-ports`/`close-ports` translate to SSH rule modifications. Limitation: Cannot specify target prefix per rule. - **Routing**: All subnets route `0.0.0.0/0` through Internet Gateway. No custom routes currently managed. - **Public IP allocation**: Not guaranteed immediately. Juju polls up to 30 seconds after instance reaches Running state. ### Storage behavior See also: [oracle](#storage-provider-oracle) for the OCI storage provider configuration options. - **Boot volume**: Minimum 50 GiB, maximum 16 TiB. Lifecycle tied to instance. - **Additional volumes**: Attached via iSCSI with CHAP enabled. Must be in the same availability domain as the instance. Juju waits for volume and attachment readiness before declaring storage available. ## Storage See also: [Storage](https://documentation.ubuntu.com/juju/4.0/reference/storage.md#storage), [Juju | Manage storage](https://documentation.ubuntu.com/juju/4.0/howto/manage-storage.md#manage-storage) ### Storage providers In addition to generic storage providers, Oracle OCI provides the following [cloud-specific storage providers](https://documentation.ubuntu.com/juju/4.0/reference/storage.md#storage-provider-cloud-specific): #### `oracle` **Type:** OCI block volumes (iSCSI) **Configuration options:** - `volume-type`: The volume type. Valid values: `default` (associated with Juju pool `oracle`) or `latency` (associated with Juju pool `oracle-latency`). Use `latency` for low-latency, high IOPS requirements, and `default` otherwise.