PBM-1728-OCI-with-WIF

docs/details/oci-workload-identity-auth.md

@@ -0,0 +1,98 @@
+# Oracle Cloud Storage using Workload Identity authentication
+
+Workload Identity Federation (WIF) lets workloads authenticate to OCI resources using federated identities rather than static credentials. This eliminates the need to create, rotate, and distribute API keys or service account key files.
+
+Percona Backup for MongoDB (PBM) supports two WIF authentication types for OCI Object Storage, in addition to the default `userPrincipal`:
+
+| Auth type | When to use|
+|---|---|
+| `instancePrincipal` | PBM is running on a virtual machine inside OCI |
+| `okeWorkloadIdentity` | PBM is running inside an OKE enhanced cluster |
+
+## instancePrincipal
+
+Use this auth type when PBM is running directly on an OCI Compute instance. The instance itself acts as the principal — no credentials file is required.
+
+### Before you begin
+
+You need:
+
+- The [Oracle Cloud Identifier (OCID):octicons-link-external-16:](https://docs.oracle.com/en-us/iaas/Content/General/Concepts/identifiers.htm#Oracle){:target="_blank"} of the OCI Compute instance running PBM
+- The name of the OCI bucket PBM will use for backups
+- A home region, tenancy OCID, and compartment name with sufficient IAM privileges to create dynamic groups and policies
+
+### Prococedure
+
+Follow these steps to set up OCI using **instancePrincipal:**
+
+1. **Create a dynamic group for the instance**
+
+    OCI IAM policies cannot target individual instances directly. You must first add the instance to a dynamic group, then write a policy against that group.
+
+    ```sh
+    oci iam dynamic-group create \
+    --region "$HOME_REGION" \
+    --compartment-id "$TENANCY_OCID" \
+    --name "$INSTANCE_DYNAMIC_GROUP_NAME" \
+    --description "PBM VM instance principal" \
+    --matching-rule "ANY {instance.id = '$INSTANCE_OCID'}"
+    ```
+
+    Replace the following:
+
+    | Variable | Description |
+    |---|---|
+    | `HOME_REGION` | Your tenancy's home region (e.g. `us-ashburn-1`) |
+    | `TENANCY_OCID` | OCID of your OCI tenancy |
+    | `INSTANCE_DYNAMIC_GROUP_NAME` | A name for the dynamic group (e.g. `pbm-vm-group`) |
+    | `INSTANCE_OCID` | OCID of the Compute instance running PBM |
+
+2. **Create an IAM policy for the dynamic group**
+
+    Grant the dynamic group permission to manage objects in the target bucket:
+
+    ```sh
+    export INSTANCE_POLICY_STATEMENT="Allow dynamic-group $INSTANCE_DYNAMIC_GROUP_NAME \
+    to manage objects in compartment $COMPARTMENT_NAME \
+    where target.bucket.name = '$BUCKET_NAME'"
+
+    oci iam policy create \
+    --region "$HOME_REGION" \
+    --compartment-id "$TENANCY_OCID" \
+    --name "$INSTANCE_POLICY_NAME" \
+    --description "Allow PBM VM instance principal to access $BUCKET_NAME" \
+    --statements "[\"$INSTANCE_POLICY_STATEMENT\"]"
+    ```
+
+    Replace the following additional variables:
+
+    | Variable | Description |
+    |---|---|
+    | `COMPARTMENT_NAME` | Name of the compartment containing the bucket |
+    | `BUCKET_NAME` | Name of the OCI Object Storage bucket |
+    | `INSTANCE_POLICY_NAME` | A name for the policy (e.g. `pbm-vm-policy`) |
+
+3. **Configure PBM to use instancePrincipal**
+
+    In your PBM configuration, set the storage type to `oci` and the credentials type to `instancePrincipal`. No key file or passphrase is needed.
+
+    ```yaml
+    storage:
+    type: oci
+    oci:
+        region: <bucket_region>
+        namespace: <namespace>
+        bucket: <bucket_name>
+        prefix: <path_prefix>
+        credentials:
+        type: instancePrincipal
+    ```
+
+## okeWorkloadIdentity
+
+Use this auth type when PBM is running as a workload inside an OKE enhanced cluster. The Kubernetes service account token is exchanged for OCI credentials automatically by the OKE Workload Identity service.
+
+!!! note
+    Your OKE cluster must be an **enhanced cluster** with Workload Identity enabled. Basic clusters do not support this feature.
+
+For setup instructions, see [Configure PBM on OKE with Workload Identity](oci-oke-workload-identity.md).

mkdocs-base.yml

@@ -237,6 +237,7 @@ nav:
   - Storage:
       - Remote backup storage overview: details/storage-configuration.md
       - AWS S3 storage: details/s3-storage.md
+      - details/oci-workload-identity-auth.md
       - details/minio.md
       - details/gcs.md
       - Workload Identity authentication: details/workload-identity-auth.md