diff --git a/.gitignore b/.gitignore index 4da6fc20..a0962e49 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ venv/ # Local Netlify folder .netlify site +.cache/ styles/ diff --git a/docs/details/oci-workload-identity-auth.md b/docs/details/oci-workload-identity-auth.md new file mode 100644 index 00000000..7bd6b835 --- /dev/null +++ b/docs/details/oci-workload-identity-auth.md @@ -0,0 +1,170 @@ +# Oracle Cloud Infrastructure (OCI) Object Storage with Workload Identity Authentication + +Percona Backup for MongoDB (PBM) supports Workload Identity authentication for Oracle Cloud Infrastructure (OCI) Object Storage. With Workload Identity, PBM can access OCI resources without storing or managing API keys, reducing operational overhead and improving security. + +Percona Backup for MongoDB (PBM) supports two Workload Identity authentication types for OCI Object Storage, in addition to the default `userPrincipal`: + +| Auth type | When to use | +|---|---| +|`userPrincipal`|PBM is running anywhere — on-premises, on other clouds, or on OCI| +| `instancePrincipal`| PBM is running on a virtual machine inside OCI | +| `okeWorkloadIdentity`| PBM is running inside an OKE enhanced cluster| + +## userPrincipal + +Choose `userPrincipal` when PBM runs outside OCI, or when you want a single authentication approach that works in any environment. PBM authenticates using an OCI user account and an API signing key. + +### Before you begin + +You need: + +- An OCI user account with access to the target bucket +- An [API signing key pair :octicons-link-external-16:](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm){:target="_blank"} (private key file and its fingerprint) +- 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 user and tenancy +- The name of the OCI bucket PBM will use for backups + +### Procedure + +1. Create an IAM policy + Grant the user permission to manage objects in the target bucket: + ```sh + oci iam policy create \ + --region "$HOME_REGION" \ + --compartment-id "$TENANCY_OCID" \ + --name "$USER_POLICY_NAME" \ + --description "Allow PBM user to access $BUCKET_NAME" \ + --statements "[\"Allow group $USER_GROUP_NAME to manage objects in compartment $COMPARTMENT_NAME where target.bucket.name = '$BUCKET_NAME'\"]" + ``` + +Replace the following variables: + +| Variable | Description | +|---|---| +| `HOME_REGION` | Your tenancy's home region (e.g. `us-ashburn-1`) | +| `TENANCY_OCID` | OCID of your OCI tenancy | +| `USER_POLICY_NAME` | A name for the policy (e.g. `pbm-user-policy`) | +| `USER_GROUP_NAME` | The IAM group the PBM user belongs to | +| `COMPARTMENT_NAME` | Name of the compartment containing the bucket | +| `BUCKET_NAME` | Name of the OCI Object Storage bucket | + +2. Configure PBM authentication + + In your PBM configuration, set the storage type to `oci` and the credentials type to `userPrincipal`. Provide the path to the private key file and its passphrase if one was set during key generation. + + ```yaml + storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: userPrincipal + userPrincipal: + tenancy: + user: + fingerprint: + key: + passphrase: + ``` + +## instancePrincipal + +Choose `instancePrincipal` when PBM runs directly on an OCI Compute instance. PBM automatically obtains OCI credentials from the instance, eliminating the need for credential files or API keys. + +### 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. + +### Procedure + +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 variables: + + | 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** + + 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 authentication** + + 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: + namespace: + bucket: + prefix: + credentials: + type: instancePrincipal + ``` + +## okeWorkloadIdentity + +Choose `okeWorkloadIdentity` when PBM runs as a workload in an Oracle Kubernetes Engine (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. + +In your PBM configuration, set the storage type to `oci` and the credentials type to `okeWorkloadIdentity`: + +```yaml +storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: okeWorkloadIdentity +``` +For setup instructions, see [Configure OKE Workload Identity for workloads :octicons-link-external-16:](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm){:target="_blank"}. \ No newline at end of file diff --git a/docs/install/backup-storage.md b/docs/install/backup-storage.md index 56b10c0f..e6702c61 100644 --- a/docs/install/backup-storage.md +++ b/docs/install/backup-storage.md @@ -81,6 +81,20 @@ Percona Backup for MongoDB needs its own dedicated S3 bucket exclusively for bac key: ``` + === ":material-database: OCI Object Storage" + + ```yaml + storage: + type: oci + oci: + region: us-ashburn-1 + namespace: your-namespace + bucket: your-bucket-name + prefix: data/pbm/backup + credentials: + type: instancePrincipal + ``` + === "Alibaba Cloud Storage" ```yaml diff --git a/docs/reference/configuration-options.md b/docs/reference/configuration-options.md index 7a18330c..375ea3e3 100644 --- a/docs/reference/configuration-options.md +++ b/docs/reference/configuration-options.md @@ -7,7 +7,7 @@ *Type*: string
*Required*: YES -Remote backup storage type. Supported values: `s3`, `minio`, `gcs`, `filesystem`, `azure`. +Remote backup storage type. Supported values: `s3`, `minio`, `gcs`, `filesystem`, `azure`, `oci`. ## AWS S3 storage options @@ -679,6 +679,55 @@ The minimum time to wait before the next retry, specified as a `time.Duration`. The maximum time to wait before the next retry, specified as a `time.Duration`. Units like ms, s, etc., are supported. Defaults to nanoseconds if no unit is provided. +## OCI Object Storage options + +```yaml +storage: + type: oci + oci: + region: + namespace: + bucket: + prefix: + credentials: + type: userPrincipal +``` + +### storage.oci.region + +*Type*: string
+*Required*: YES + +The region where your OCI Object Storage bucket is located. + +### storage.oci.namespace + +*Type*: string
+*Required*: YES + +The Object Storage namespace for your tenancy. + +### storage.oci.bucket + +*Type*: string
+*Required*: YES + +The name of the OCI Object Storage bucket. + +### storage.oci.prefix + +*Type*: string
+*Required*: NO + +The path prefix inside the bucket where PBM stores backup data. + +### storage.oci.credentials.type + +*Type*: string
+*Required*: YES + +The OCI authentication type. Supported values: `userPrincipal`, `instancePrincipal`, `okeWorkloadIdentity`. + ## Alibaba Cloud OSS storage options ```yaml diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 0774a511..c8dad618 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -237,6 +237,7 @@ nav: - Storage: - Remote backup storage overview: details/storage-configuration.md - AWS S3 storage: details/s3-storage.md + - OCI Object Storage (Workload Identity): details/oci-workload-identity-auth.md - details/minio.md - details/gcs.md - Workload Identity authentication: details/workload-identity-auth.md