feat: Add clarification about concurrency and db connection configuration. (#356)

Author: pantierra

CHANGELOG.md

@@ -35,6 +35,7 @@ stac:
 - Added tests for observability stack [#342](https://github.com/developmentseed/eoapi-k8s/pull/342)
 - Added validation to require `postgrescluster.enabled: false` when using external databases [#346](https://github.com/developmentseed/eoapi-k8s/pull/346)
 - Added a production.yaml profile [#354](https://github.com/developmentseed/eoapi-k8s/pull/354)
+- Added clarification about concurrency and db connection configuration. [#356](https://github.com/developmentseed/eoapi-k8s/pull/356)
 
 ### Changed
 

charts/eoapi/values.yaml

@@ -288,7 +288,9 @@ raster:
       HOST: "0.0.0.0"
       PORT: "8080"
       # https://www.uvicorn.org/settings/#production
-      WEB_CONCURRENCY: "5"
+      WEB_CONCURRENCY: "4" # CPU-intensive; reduce to 2-3 with autoscaling
+      DB_MIN_CONN_SIZE: "1"
+      DB_MAX_CONN_SIZE: "3" # Less intensive: Metadata queries only
 
 multidim:
   enabled: false # disabled by default
@@ -349,7 +351,9 @@ multidim:
       HOST: "0.0.0.0"
       PORT: "8080"
       # https://www.uvicorn.org/settings/#production
-      WEB_CONCURRENCY: "5"
+      WEB_CONCURRENCY: "4" # CPU-intensive; reduce to 2-3 with autoscaling
+      DB_MIN_CONN_SIZE: "1"
+      DB_MAX_CONN_SIZE: "3" # Less intensive: Metadata queries only
 
 stac:
   enabled: true
@@ -398,7 +402,9 @@ stac:
       HOST: "0.0.0.0"
       PORT: "8080"
       # https://www.uvicorn.org/settings/#production
-      WEB_CONCURRENCY: "5"
+      WEB_CONCURRENCY: "10" # Handles many concurrent requests; reduce to 4-6 with autoscaling
+      DB_MIN_CONN_SIZE: "1"
+      DB_MAX_CONN_SIZE: "5" # Quite intensive (queries, transactions, searches)
 
 vector:
   enabled: true
@@ -451,8 +457,9 @@ vector:
       ##############
       HOST: "0.0.0.0"
       PORT: "8080"
-      # https://www.uvicorn.org/settings/#production
-      WEB_CONCURRENCY: "5"
+      WEB_CONCURRENCY: "8" # Moderate concurrency for complex spatial queries; reduce to 4-5 with autoscaling
+      DB_MIN_CONN_SIZE: "2"
+      DB_MAX_CONN_SIZE: "5" # Vector queries can be complex and long-running
 
 ######################
 # STAC Browser

docs/autoscaling.md

@@ -44,6 +44,46 @@ stac:
       requestRate: 50000m  # 50 requests/second
 ```
 
+## Concurrency settings
+
+Each main eoAPI service has `WEB_CONCURRENCY` and database pool settings that should be adjusted based on your scaling strategy:
+
+### Without autoscaling (default)
+
+Higher concurrency per pod to handle some considerate load:
+
+```yaml
+stac:
+  settings:
+    envVars:
+      WEB_CONCURRENCY: "10"  # More workers per pod
+      DB_MIN_CONN_SIZE: "1"
+      DB_MAX_CONN_SIZE: "5"  # Total: 10-50 connections per pod
+```
+
+### With autoscaling enabled
+
+Lower concurrency for predictable resource usage:
+
+```yaml
+stac:
+  autoscaling:
+    enabled: true
+  settings:
+    envVars:
+      WEB_CONCURRENCY: "4"   # Fewer workers, let HPA scale pods
+      DB_MIN_CONN_SIZE: "1"
+      DB_MAX_CONN_SIZE: "3"  # Total: 4-12 connections per pod
+```
+
+### Service-specific recommentations
+
+| Service | WEB_CONCURRENCY (no autoscaling) | WEB_CONCURRENCY (with autoscaling) | Rationale |
+|---------|----------------------------------|-------------------------------------|-----------|
+| STAC    | 10                               | 4-6                                 | High request volume, DB intensive |
+| Raster  | 4                                | 2-3                                 | CPU intensive image operations |
+| Vector  | 8                                | 4-5                                 | Complex spatial queries |
+
 ### Scaling Policies
 
 1. Go to the [releases section](https://github.com/developmentseed/eoapi-k8s/releases) of this repository and find the latest