From 5443149cce2d22c44bce3698dce2c8d72012afd0 Mon Sep 17 00:00:00 2001
From: Ben Duncan <5178243+benduncan@users.noreply.github.com>
Date: Wed, 7 Oct 2026 04:38:44 +1000
Subject: [PATCH] docs: look the OCI compartment OCID up by name

The guide asked the reader to paste `ocid1.compartment.oc1..xxx` three times, and
the `oci` CLI it already requires can resolve the name instead.

The lookup needs its own check. `oci iam compartment list --query ... | [0]` exits 0
and prints nothing when the name matches nothing, so an unset `$CID` would otherwise
reach Terraform and fail with an OCI error naming neither the compartment nor the
cause.

Two compartments in one tenancy can share a name, which the listing command shows
and the lookup cannot resolve, so the paste form stays as the answer for that case.
Records why the tenancy root is the wrong value: the step 2.1 policy is scoped to
whatever `$CID` holds.
---
 docs/oci-integration/README.md | 43 ++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/docs/oci-integration/README.md b/docs/oci-integration/README.md
index dac888125..6e7e04edd 100644
--- a/docs/oci-integration/README.md
+++ b/docs/oci-integration/README.md
@@ -93,10 +93,39 @@ Once installed configure your OCI credentials (~/.oci/config) which will be used
 
 `oci setup config`
 
-Once setup validate your OCI credentials work as expected. `$CID` is the compartment you are deploying into, which is a `ocid1.compartment.oc1..` OCID, or your tenancy OCID if that compartment is the root. The same value is used throughout this guide and again as `compartment_ocid` in step 4.
+Now set `$CID` to the compartment you are deploying into. It is used throughout this guide and again as `compartment_ocid` in step 4, so set it once and keep the same shell.
+
+The CLI can look it up by name, so there is no OCID to copy:
+
+```sh
+export CID=$(oci iam compartment list --compartment-id-in-subtree true \
+    --access-level ACCESSIBLE --all \
+    --query "data[?name=='my-compartment' && \"lifecycle-state\"=='ACTIVE'].id | [0]" \
+    --raw-output)
+
+echo "${CID:?no ACTIVE compartment of that name is visible to this profile}"
+```
+
+The second line is the check, not decoration: the query exits 0 and prints nothing when the name matches nothing, so without it an unset `$CID` reaches Terraform and fails much later with an OCI error that names neither the compartment nor the cause.
+
+To see the names you can choose from, drop the `--query` and ask for a table:
+
+```sh
+oci iam compartment list --compartment-id-in-subtree true --access-level ACCESSIBLE --all \
+    --query 'data[?"lifecycle-state"==`ACTIVE`].{name:name,id:id}' --output table
+```
+
+Two compartments in one tenancy can share a name. If the table shows the name twice, take the OCID from it and set `$CID` directly, because the lookup above returns the first match and cannot tell you which one you wanted:
 
 ```sh
 export CID="ocid1.compartment.oc1..xxx"
+```
+
+> **Deploy into a compartment, not the tenancy root.** The root's OCID is the tenancy OCID and will work, but the instance-principal policy in step 2.1 is scoped to whatever `$CID` holds, so a root value grants every instance in the tenancy the right to consume the regional public-IP quota.
+
+Confirm the credential and the compartment together:
+
+```sh
 oci compute shape list --compartment-id $CID
 ```
 
@@ -164,7 +193,13 @@ There are two ways to provide it, and they differ in who has to authorise them r
 
 **Use 2.1 if you are a tenancy admin.** It is the better of the two because there is no key to leak, rotate or forget about, and a replaced node needs no handoff. Use 2.2 when your compartment was allocated to you inside someone else's tenancy, which is the common case and the reason 2.2 exists at all.
 
-Do one of the two, not both, then continue to step 3.
+Both routes below need `$CID` from the prerequisites, so confirm it is still set in this shell:
+
+```bash
+echo "${CID:?set it as shown under OCI CLI tool}"
+```
+
+Do one of the two authentication methods below, not both, then continue to step 3.
 
 ### 2.1 Instance principal (preferred)
 
@@ -248,11 +283,9 @@ An email will be sent to the designated `$ADMIN_EMAIL` defined, you are required
 
 #### Grant the group its three permissions
 
-Spinifex calls [ten operations](../oci-architecture/README.md#the-iam-policy), and these three statements are what authorise them. Attach the policy to the compartment you are deploying into using the command below. Replace `$CID` with that compartment's OCID.
+Spinifex calls [ten operations](../oci-architecture/README.md#the-iam-policy), and these three statements are what authorise them. This attaches the policy to `$CID`, the compartment you are deploying into.
 
 ```bash
-export CID="ocid1.compartment.oc1..xxx"
-
 oci iam policy create --compartment-id "$CID" --name SpinifexOperators \
     --description "Spinifex external-address allocation" \
     --statements '[