feat: Document cloud-native authentication for bucket access. (#364)

Author: pantierra

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Added documentation for cloud-native bucket access [#364](https://github.com/developmentseed/eoapi-k8s/pull/364)
+
 ### Added
 
 ## Changed

docs/aws-eks.md

@@ -216,3 +216,78 @@ Assert that things are set up correctly:
    # service/nginx-ingress-nginx-controller             LoadBalancer   10.100.36.152    eoapi-k8s-553d3ea234b-3eef2e6e61e5d161.elb.us-west-1.amazonaws.com   80:30342/TCP,443:30742/TCP   2d17h
    # service/nginx-ingress-nginx-controller-admission   ClusterIP      10.100.34.22     <none>                                                                          443/TCP                      2d17h
    ```
+
+---
+
+## Configure IRSA for S3 Bucket Access
+
+eoAPI services (especially the raster API) need to access COG files in S3 buckets. Instead of using long-lived credentials, use IRSA (IAM Roles for Service Accounts) for secure, temporary credential access:
+
+1. **Create an IAM policy** for S3 bucket access:
+
+   ```sh
+   cat <<EOF > eoapi-s3-policy.json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Action": [
+           "s3:GetObject",
+           "s3:ListBucket"
+         ],
+         "Resource": [
+           "arn:aws:s3:::your-bucket-name/*",
+           "arn:aws:s3:::your-bucket-name"
+         ]
+       }
+     ]
+   }
+   EOF
+
+   aws iam create-policy \
+       --policy-name eoapi-s3-access \
+       --policy-document file://eoapi-s3-policy.json
+   ```
+
+2. **Create an IAM role and service account**:
+
+   ```sh
+   eksctl create iamserviceaccount \
+       --name eoapi-sa \
+       --namespace default \
+       --cluster $CLUSTER_NAME \
+       --region $REGION \
+       --attach-policy-arn arn:aws:iam::${AWS_ACCOUNT_ID}:policy/eoapi-s3-access \
+       --approve
+   ```
+
+   This command automatically creates a service account with the necessary annotation:
+   ```yaml
+   # This is what eksctl creates for you:
+   apiVersion: v1
+   kind: ServiceAccount
+   metadata:
+     name: eoapi-sa
+     namespace: default
+     annotations:
+       eks.amazonaws.com/role-arn: arn:aws:iam::${AWS_ACCOUNT_ID}:role/eksctl-${CLUSTER_NAME}-addon-iamserviceaccount-default-eoapi-sa
+   ```
+
+3. **Configure EOAPI** to use the service account in your `values.yaml`:
+
+   ```yaml
+   serviceAccount:
+     create: false  # We already created it with eksctl
+     name: eoapi-sa
+   ```
+
+   **Alternative:** If you prefer to let the Helm chart create the service account, skip step 2 and use:
+   ```yaml
+   serviceAccount:
+     create: true
+     annotations:
+       eks.amazonaws.com/role-arn: arn:aws:iam::${AWS_ACCOUNT_ID}:role/your-existing-iam-role
+   ```
+
+The raster service will automatically use IRSA credentials via the AWS SDK credential chain. No hardcoded credentials needed!

docs/azure.md

@@ -221,6 +221,27 @@ multidim:
     <<: *commonVolumeConfig
 ```
 
+## Azure Blob Storage Authentication
+
+eoAPI services (particularly the raster API) need to access COG files stored in Azure Blob Storage. With Azure Workload Identity configured (as shown above), authentication happens automatically:
+
+1. **Grant storage access** to your managed identity:
+   ```bash
+   CLIENT_ID=$(az identity show -g <resource-group> -n eoapi-identity --query clientId -o tsv)
+
+   az role assignment create \
+     --role "Storage Blob Data Reader" \
+     --assignee $CLIENT_ID \
+     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>
+   ```
+
+2. **Automatic authentication**: The raster service (titiler-pgstac) uses GDAL's `/vsiaz/` driver, which automatically authenticates using:
+   - Workload Identity credentials (via service account annotations)
+   - Managed Identity (if running on Azure VMs)
+   - Environment variables (if set)
+
+   No additional configuration or hardcoded credentials needed!
+
 ## Azure Managed Identity Setup
 
 To use Azure Managed Identity with your Kubernetes cluster:

docs/configuration.md

@@ -137,6 +137,42 @@ pgstacBootstrap:
       context_stats_ttl: "12 hours"
 ```
 
+## Cloud Storage Authentication
+
+eoAPI services access COG files in cloud storage buckets. Use cloud-native authentication instead of long-lived credentials:
+
+### AWS (IRSA)
+
+```yaml
+serviceAccount:
+  create: true
+  annotations:
+    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/eoapi-s3-access
+```
+
+The raster service automatically uses IRSA credentials via the AWS SDK credential chain.
+
+### Azure (Workload Identity)
+
+```yaml
+serviceAccount:
+  create: true
+  annotations:
+    azure.workload.identity/client-id: "your-client-id"
+    azure.workload.identity/tenant-id: "your-tenant-id"
+```
+
+### GCP (Workload Identity)
+
+```yaml
+serviceAccount:
+  create: true
+  annotations:
+    iam.gke.io/gcp-service-account: eoapi-gcs-sa@project.iam.gserviceaccount.com
+```
+
+All services using GDAL (raster API with titiler-pgstac) automatically use these credentials through their respective cloud SDKs. No environment variables or hardcoded credentials needed.
+
 ## Ingress Configuration
 
 Unified ingress configuration supporting both NGINX and Traefik:

docs/gcp-gke.md

@@ -124,3 +124,52 @@ helm upgrade --install cert-manager jetstack/cert-manager \
 ```
 
 Now we are ready to install eoapi. See the [eoapi installation instructions](./helm-install.md) for more details.
+
+# Configure Workload Identity for GCS Bucket Access
+
+eoAPI services need to access COG files in GCS buckets. Use Workload Identity for secure, temporary credential access instead of long-lived credentials:
+
+1. **Enable Workload Identity on your cluster** (if not already enabled):
+   ```bash
+   gcloud container clusters update sandbox \
+       --workload-pool=PROJECT_ID.svc.id.goog \
+       --zone=us-central1-a
+   ```
+
+2. **Create a Google Service Account**:
+   ```bash
+   gcloud iam service-accounts create eoapi-gcs-sa \
+       --display-name="eoAPI GCS Service Account"
+   ```
+
+3. **Grant GCS permissions** to the service account:
+   ```bash
+   # For specific bucket access
+   gsutil iam ch serviceAccount:eoapi-gcs-sa@PROJECT_ID.iam.gserviceaccount.com:objectViewer gs://your-bucket-name
+
+   # Or use IAM roles for multiple buckets
+   gcloud projects add-iam-policy-binding PROJECT_ID \
+       --member="serviceAccount:eoapi-gcs-sa@PROJECT_ID.iam.gserviceaccount.com" \
+       --role="roles/storage.objectViewer"
+   ```
+
+4. **Create Kubernetes service account** and bind it:
+   ```bash
+   kubectl create serviceaccount eoapi-sa -n eoapi
+
+   gcloud iam service-accounts add-iam-policy-binding eoapi-gcs-sa@PROJECT_ID.iam.gserviceaccount.com \
+       --role roles/iam.workloadIdentityUser \
+       --member "serviceAccount:PROJECT_ID.svc.id.goog[eoapi/eoapi-sa]"
+
+   kubectl annotate serviceaccount eoapi-sa -n eoapi \
+       iam.gke.io/gcp-service-account=eoapi-gcs-sa@PROJECT_ID.iam.gserviceaccount.com
+   ```
+
+5. **Configure eoAPI** in your `values.yaml`:
+   ```yaml
+   serviceAccount:
+     create: false  # We already created it
+     name: eoapi-sa
+   ```
+
+The raster service will automatically use Workload Identity credentials. No hardcoded credentials needed!

docs/stac-auth-proxy.md

@@ -12,7 +12,7 @@ external_links:
 
 ## Solution Overview
 
-We have implemented support for STAC Auth Proxy integration with EOAPI-K8S through service-specific ingress control. This feature allows the STAC service to be accessible only internally while other services remain externally available.
+We have implemented support for STAC Auth Proxy integration with eoAPI-K8S through service-specific ingress control. This feature allows the STAC service to be accessible only internally while other services remain externally available.
 
 ## Implementation Details