fix: Allow setting stac.overrideRootPath to empty string for stac-auth-proxy integration (#307)

Author: emmanuelmathot

CHANGELOG.md

@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Fixed `stac.overrideRootPath` empty string handling for stac-auth-proxy integration - empty string now properly omits `--root-path` argument entirely [#307](https://github.com/developmentseed/eoapi-k8s/pull/307)
 - Pin `metrics-server` to `bitnamilegacy` registry due to https://github.com/bitnami/charts/issues/35164 [#309](https://github.com/developmentseed/eoapi-k8s/pull/309)
 
 ## [0.7.8] - 2025-09-10

charts/eoapi/templates/services/stac/deployment.yaml

@@ -40,8 +40,10 @@ spec:
           {{- if (and (.Values.ingress.className) (or (eq .Values.ingress.className "nginx") (eq .Values.ingress.className "traefik"))) }}
           - "--proxy-headers"
           - "--forwarded-allow-ips=*"
-          {{- if .Values.stac.overrideRootPath}}
+          {{- if hasKey .Values.stac "overrideRootPath" }}
+          {{- if ne .Values.stac.overrideRootPath "" }}
           - "--root-path={{ .Values.stac.overrideRootPath }}"
+          {{- end }}
           {{- else }}
           - "--root-path={{ .Values.stac.ingress.path }}"
           {{- end }}
@@ -55,8 +57,12 @@ spec:
           timeoutSeconds: 1
         readinessProbe:
           httpGet:
-            {{- if .Values.stac.overrideRootPath}}
+            {{- if hasKey .Values.stac "overrideRootPath" }}
+            {{- if ne .Values.stac.overrideRootPath "" }}
             path: {{ .Values.stac.overrideRootPath }}/_mgmt/ping
+            {{- else }}
+            path: /_mgmt/ping
+            {{- end }}
             {{- else}}
             path: /_mgmt/ping
             {{- end}}
@@ -66,8 +72,12 @@ spec:
           successThreshold: 1
         startupProbe:
           httpGet:
-            {{- if .Values.stac.overrideRootPath}}
+            {{- if hasKey .Values.stac "overrideRootPath" }}
+            {{- if ne .Values.stac.overrideRootPath "" }}
             path: {{ .Values.stac.overrideRootPath }}/_mgmt/ping
+            {{- else }}
+            path: /_mgmt/ping
+            {{- end }}
             {{- else}}
             path: /_mgmt/ping
             {{- end}}

docs/advanced/stac-auth-proxy.md

@@ -1,4 +1,4 @@
-# STAC Auth Proxy Integration with EOAPI-K8S
+# STAC Auth Proxy Integration with eoAPI-K8S
 
 ## Solution Overview
 
@@ -25,7 +25,7 @@ raster:
 
 ## Deployment Guide
 
-### 1. Configure EOAPI-K8S
+### 1. Configure eoAPI-K8S
 
 ```yaml
 # values.yaml for eoapi-k8s
@@ -98,9 +98,93 @@ Expected behavior:
    - Check ingress controller logs
    - Verify service-specific settings in values.yaml
 
+## Root Path Configuration for Direct Service Access
+
+### Understanding usage of overrideRootPath with stac-auth-proxy
+
+When deploying the eoAPI-K8S with the STAC service behind a stac-auth-proxy, you may want to configure the `stac.overrideRootPath` parameter to control how the FastAPI application handles root path prefixes. This is particularly useful when the auth proxy is responsible for managing the `/stac` path prefix.
+
+When deploying stac-auth-proxy in front of the eoAPI service, you may need to configure the root path behavior to avoid URL conflicts. The `stac.overrideRootPath` parameter allows you to control how the STAC FastAPI application handles root path prefixes.
+
+### Setting overrideRootPath to Empty String
+
+For stac-auth-proxy deployments, you often want to set `stac.overrideRootPath` to an empty string:
+
+```yaml
+# values.yaml for eoapi-k8s
+stac:
+  enabled: true
+  overrideRootPath: ""  # Empty string removes --root-path argument
+  ingress:
+    enabled: false  # Disable external ingress for STAC
+```
+
+**Important**: This configuration creates an **intentional inconsistency**:
+
+- **Ingress routes**: Still configured for `/stac` (if ingress was enabled)
+- **FastAPI application**: Runs without any root path prefix (no `--root-path` argument)
+
+### Why This Works for stac-auth-proxy
+
+This behavior is specifically designed for stac-auth-proxy scenarios where:
+
+1. **stac-auth-proxy** receives requests via its own ingress and handles the `/stac` path prefix
+2. **stac-auth-proxy** filters requests managing the `/stac` prefix and forwards them directly to the STAC service without the path prefix
+3. **STAC service** responds from its internal service as if it's running at the root path `/`
+
+### Configuration Examples
+
+#### Standard Deployment (with ingress)
+
+```yaml
+stac:
+  enabled: true
+  # Default behavior - uses ingress.path as root-path
+  ingress:
+    enabled: true
+    path: "/stac"
+```
+
+Result: FastAPI runs with `--root-path=/stac`
+
+#### stac-auth-proxy Deployment
+
+```yaml
+stac:
+  enabled: true
+  overrideRootPath: ""  # Empty string - no --root-path argument
+  ingress:
+    enabled: false  # Access via auth proxy only
+```
+
+Result: FastAPI runs without `--root-path` argument
+
+#### Custom Root Path
+
+```yaml
+stac:
+  enabled: true
+  overrideRootPath: "/api/v1/stac"  # Custom path
+```
+
+Result: FastAPI runs with `--root-path=/api/v1/stac`
+
+### Request Flow with stac-auth-proxy
+
+```mermaid
+graph LR
+    A[Client Request: /stac/collections] --> B[stac-auth-proxy]
+    B -->|Authentication & Authorization| C[Forward: /collections]
+    C --> D[STAC Service: receives /collections]
+    D --> E[Response: collections data]
+    E --> B
+    B --> A
+```
+
 ## Additional Notes
 
 - The solution leverages Kubernetes service discovery for internal communication
 - No changes required to the STAC service itself
 - Zero downtime deployment possible
 - Existing deployments without auth proxy remain compatible
+- The `overrideRootPath: ""` configuration is specifically for proxy scenarios