Skip to content
SHC Docs

Oracle Cloud

SHC has a connection type for Oracle Cloud Infrastructure. One set of API signing credentials gives a cluster running on OCI instances DNS, a network load balancer and block volumes.

There is no Terraform module for OCI. You create the instances, the subnet and the compartment yourself, then run shc init and shc node join on them.

This page states what the code does. No live estate has run on OCI yet, so it has no list of gotchas.

ConcernValue
Connection typeoci
Required credentialstenancy_ocid, user_ocid, fingerprint, private_key, region, compartment_ocid
DNSoci: public zones in the compartment
Load balanceroci-nlb: one network load balancer per connection, TCP and UDP
Block volumesoci-volume: created in one availability domain, one node at a time
Node cloudoci, set by hand. OCI nodes are not detected
Node locationThe availability domain’s label in lower case, for example phx-ad-1, set by hand
FieldUsed bySecretMeaning
tenancy_ocidallnoThe tenancy’s OCID
user_ocidallnoThe OCID of the user the API key belongs to
fingerprintallnoThe API key’s fingerprint
private_keyallyesThe API signing key, an RSA private key in PEM
regionallnoThe region, for example us-phoenix-1
compartment_ocidallnoThe compartment SHC reads and creates resources in
subnet_ocidload balancernoThe subnet the load balancer is created in
availability_domainvolumesnoThe availability domain new volumes are created in, as OCI names it, for example Uocm:PHX-AD-1

The first six are required to connect. subnet_ocid is required only by the load balancer: without it a port published through the connection is refused with X400973PRXCFG. availability_domain is optional: without it a new volume goes in the first availability domain OCI lists for the tenancy in that region.

A secret never goes on the command line. The private key is read from the file --value-file names; every other field is typed:

Terminal window
$ shc connection connect oci --cred tenancy_ocid=ocid1.tenancy.oc1..aaaa --cred user_ocid=ocid1.user.oc1..aaaa --cred fingerprint=12:34:56:78:9a:bc:de:f0:12:34:56:78:9a:bc:de:f0 --cred region=us-phoenix-1 --cred compartment_ocid=ocid1.compartment.oc1..aaaa --cred subnet_ocid=ocid1.subnet.oc1.phx.aaaa --cred availability_domain=Uocm:PHX-AD-1 --cred private_key=- --value-file oci_api_key.pem

The load balancer is named shc-<connection name>.

A block volume reaches only the nodes whose recorded cloud and location match the volume’s. For oci-volume that is cloud oci and the volume’s availability domain.

OCI instances are not detected. A node on OCI records no cloud and no location until you say so, and until then no oci-volume reaches it. A deployment whose volume cannot reach any node stays pending.

The location is the availability domain’s label in lower case, without the tenancy prefix: phx-ad-1 for Uocm:PHX-AD-1.

Say both when the node is created:

Terminal window
$ shc init --cloud oci --location phx-ad-1
$ shc node join <token> --cloud oci --location phx-ad-1

Or on a node that already exists:

Terminal window
$ shc node update <node> --cloud oci --location phx-ad-1

Check what each node records:

Terminal window
$ shc node ls

The location column reads oci/phx-ad-1.

oci-volume creates one block volume per volume in the compartment, attaches it to the instance that runs the deployment, and moves it with the deployment.

  • A volume is single-node read-write (rwo). Any other access mode is refused with X400325VOLCFG.
  • A volume is at least 50 GiB. A smaller request gets 50 GiB.
  • The provider finds the instance by the node’s name: an instance in the compartment whose display name equals it. Name each instance after its node. Two instances that match are refused.
  • The volume is attached paravirtualized and mounted from a consistent device path under /dev/oracleoci/. An instance with no such path free is refused with X400325VOLCFG, so use an image that supports consistent device paths.
  • A volume and an instance in different availability domains are refused with X400325VOLCFG. Set availability_domain on the connection to the domain your nodes are in, and record that domain’s label as each node’s location.

With more than one connection that can provision volumes, name the one to use:

Terminal window
$ shc config set storage.volumes.provider oci

Which mounts go on a block volume is covered in Block storage by default.

oci-nlb keeps one public network load balancer per connection, named shc-<connection>, in the subnet from subnet_ocid. Every deployment that publishes a port through the connection shares it, so an outside port binds once per connection.

Publish a port through it by naming the connection after @:

Terminal window
$ shc install <app> -t <tenant> -s <stack> --expose 5432@oci=<service>:5432

It forwards TCP and UDP. It does not speak PROXY protocol: a port that asks for it is refused with X400981PRXPPU.

The oci DNS provider writes records in the public zones of the compartment. Name the zones the connection manages with --zone when you connect.