v0.7.1: Improve upgrade process and ingress configuration

CHANGELOG.md

@@ -5,12 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [v0.7.1] - Unreleased
+## [v0.7.1] - 2025-05-16
 
 ### Breaking Changes
 - Remove hard-coded cert-manager configuration from ingress template [#227](https://github.com/developmentseed/eoapi-k8s/pull/227)
+- Remove `pathType` and `pathSuffix` configurations in favor of controller-specific defaults [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
+
+### Added
+- Add upgrade job to handle database permissions for migrations from pre-0.7.0 versions [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
+- Add separate ingress configuration for STAC browser [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
+- Support custom cluster naming via `postgrescluster.name` [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
 
 ### Changed
+- Improve Nginx and Traefik support with controller-specific rewrites [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
+- Increase bootstrap job retry limit to 3 attempts [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
+- Enhance secret handling with custom PostgreSQL cluster names [#228](https://github.com/developmentseed/eoapi-k8s/pull/228)
 - Simplify TLS configuration to allow user-controlled certificate management [#227](https://github.com/developmentseed/eoapi-k8s/pull/227)
 - Update documentation with comprehensive cert-manager setup guide [#227](https://github.com/developmentseed/eoapi-k8s/pull/227)
 

README.md

@@ -104,6 +104,9 @@ For cloud-based deployments, refer to our detailed setup guides:
 * [Autoscaling and Monitoring](./docs/autoscaling.md)
 * [Health Checks](./docs/health.md)
 * [Unified Ingress Configuration](./docs/unified-ingress.md)
+* [Upgrade Guide](./docs/upgrade.md)
+
+> **Important Notice**: If you're upgrading from a version prior to 0.7.0, please read the [upgrade guide](./docs/upgrade.md) for important database permission changes.
 
 ## Contributing
 

docs/configuration.md

@@ -2,60 +2,172 @@
 
 ## Required Values
 
-The required values to pass to `helm install` or `helm template` commands can be found by showing what is validated:
+The required values to pass to `helm install` or `helm template` commands can be found in our schema validation:
 
 ```bash
-$ head -n 9 <eoapi-k8s-repo>/values.schema.json
 {
-  "$schema": "http://json-schema.org/schema#",
-  "type": "object",
   "required": [
     "service",
     "gitSha"
-  ],
+  ]
+}
 ```
 
-Most of the required fields have common-sense defaults. 
-The table below and the `values.yaml` comments should explain what the options and defaults are:
+Most fields have sensible defaults. Here are the core configuration options:
 
-|                               **Values Key**                              |                                                              **Description**                                                              |  **Default** | **Choices**            |
-|:-------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:------------|:------------------------|
-| `service.port`                                                              | the port that all vector/raster/stac services run on<br>used in `kind: Service` and `kind: Ingress`                                       |     8080     |   your favorite port   |
-| `gitSha`                                                                    | sha attached to a `kind: Deployment` key `metadata.labels`                                                                                | gitshaABC123 | your favorite sha      |
+| **Values Key** | **Description** | **Default** | **Choices** |
+|:--------------|:----------------|:------------|:------------|
+| `service.port` | Port for all services (vector/raster/stac) | 8080 | any valid port |
+| `gitSha` | SHA for deployment tracking | gitshaABC123 | any valid SHA |
+| `previousVersion` | Previous version during upgrades | "" | semantic version |
 
+## Database Configuration
 
---- 
+### PostgreSQL Cluster (Default)
 
-## Default Configuration
+Using Crunchydata's PostgreSQL Operator (`postgresql.type: "postgrescluster"`):
 
-Running `helm install` from https://devseed.com/eoapi-k8s/ should spin up similar infrastructure in EKS or GKE:
+| **Values Key** | **Description** | **Default** | **Choices** |
+|:--------------|:----------------|:------------|:------------|
+| `postgrescluster.enabled` | Enable PostgreSQL cluster | true | true/false |
+| `postgrescluster.name` | Cluster name | Release name | any valid k8s name |
+| `postgrescluster.postgresVersion` | PostgreSQL version | 16 | supported versions |
+| `postgrescluster.postGISVersion` | PostGIS version | "3.4" | supported versions |
 
-In EKS or GKE you'll by default get:
+### External Database
 
-* a HA PostgreSQL database deployment and service via [Crunchdata's Postgresl Operator](https://access.crunchydata.com/documentation/postgres-operator)
-* the same vector and raster data fixtures used for testing loaded into the DB
-* a load balancer and nginx-compatible ingress with the following path rewrites:
-    * a `/stac` service for `stac_fastapi.pgstac`
-    * a `/raster` service for `titler.pgstac`
-    * a `/vector` service for `tipg.pgstac`
+For external databases, set `postgresql.type` to either:
 
-Here's a simplified high-level diagram to grok:
-![](./images/default_architecture.png)
+1. Using plaintext credentials (`external-plaintext`):
+```yaml
+postgresql:
+  type: "external-plaintext"
+  external:
+    host: "your-host"
+    port: "5432"
+    database: "eoapi"
+    credentials:
+      username: "eoapi"
+      password: "your-password"
+```
 
----
+2. Using Kubernetes secrets (`external-secret`):
+```yaml
+postgresql:
+  type: "external-secret"
+  external:
+    existingSecret:
+      name: "your-secret"
+      keys:
+        username: "username"
+        password: "password"
+    host: "your-host"  # can also be in secret
+    port: "5432"       # can also be in secret
+    database: "eoapi"  # can also be in secret
+```
 
-## Additional Options
+## Ingress Configuration
+
+Unified ingress configuration supporting both NGINX and Traefik:
+
+| **Values Key** | **Description** | **Default** | **Choices** |
+|:--------------|:----------------|:------------|:------------|
+| `ingress.enabled` | Enable ingress | true | true/false |
+| `ingress.className` | Ingress controller | "nginx" | "nginx", "traefik" |
+| `ingress.host` | Ingress hostname | "" | valid hostname |
+| `ingress.rootPath` | Doc server root path | "" | valid path |
+
+See [Unified Ingress Configuration](./unified-ingress.md) for detailed setup.
+
+## Service Configuration
+
+Each service (stac, raster, vector, multidim) supports:
+
+| **Values Key** | **Description** | **Default** | **Choices** |
+|:--------------|:----------------|:------------|:------------|
+| `{service}.enabled` | Enable the service | varies | true/false |
+| `{service}.image.name` | Container image | varies | valid image |
+| `{service}.image.tag` | Image tag | varies | valid tag |
+| `{service}.autoscaling.enabled` | Enable HPA | false | true/false |
+| `{service}.autoscaling.type` | Scaling metric | "requestRate" | "cpu", "requestRate", "both" |
+
+Example service configuration:
+```yaml
+raster:
+  enabled: true
+  autoscaling:
+    enabled: true
+    minReplicas: 2
+    maxReplicas: 10
+    type: "requestRate"
+    targets:
+      cpu: 75
+      requestRate: "100000m"
+```
 
----
+## STAC Browser
 
-### Key `autoscaling`
+| **Values Key** | **Description** | **Default** | **Choices** |
+|:--------------|:----------------|:------------|:------------|
+| `browser.enabled` | Enable STAC browser | true | true/false |
+| `browser.replicaCount` | Number of replicas | 1 | integer > 0 |
+| `browser.ingress.enabled` | Enable browser ingress | true | true/false |
 
-#### `autoscaling.type`
+## Deployment Architecture
 
-|   **Values Key**  |                                                                 **Description**                                                                 | **Default** | **Choices**  |
-|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|:-----------|:--------------|
-| `autoscaling.type` | a simple example of a default metric (`cpu`) and custom metric (`requestRate`) to scale by. If selecting `both` the metric that results in the "highest amount of change" wins. See [k8s documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#scaling-on-multiple-metrics) for more info  | requestRate       | requestRate<br>cpu<br>both<br> |
+When using default settings, the deployment looks like this:
+![](./images/default_architecture.png)
+
+The deployment includes:
+- HA PostgreSQL database (via PostgreSQL Operator)
+- Sample data fixtures
+- Load balancer with path-based routing:
+  - `/stac` → STAC API
+  - `/raster` → Titiler
+  - `/vector` → TiPG
+  - `/browser` → STAC Browser
+  - `/` → Documentation
+
+## Advanced Configuration
+
+### Autoscaling Behavior
+
+Fine-tune scaling behavior:
+
+```yaml
+autoscaling:
+  behaviour:
+    scaleDown:
+      stabilizationWindowSeconds: 60
+    scaleUp:
+      stabilizationWindowSeconds: 0
+```
 
-#### `autoscaling.behaviour.[scaleDown||scaleUp]`
+See [Kubernetes HPA documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior) for details.
 
-These are normal k8s autoscaling pass throughs. They are stablization windows in seconds to for scaling up or down to prevent flapping from happening. Read more about [the options on the k8s documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior)
+### Resource Requirements
+
+Each service can have custom resource limits:
+
+```yaml
+settings:
+  resources:
+    limits:
+      cpu: "768m"
+      memory: "1024Mi"
+    requests:
+      cpu: "256m"
+      memory: "512Mi"
+```
+
+### Additional Service Settings
+
+Each service also supports:
+```yaml
+settings:
+  labels: {}                # Additional pod labels
+  extraEnvFrom: []         # Additional environment variables from references
+  extraVolumeMounts: []    # Additional volume mounts
+  extraVolumes: []         # Additional volumes
+  envVars: {}             # Environment variables
+```

docs/stac-auth-proxy.md

@@ -23,27 +23,6 @@ raster:
     enabled: true
 ```
 
-### 2. Template Changes
-
-The ingress template now checks service-specific settings:
-
-```yaml
-{{- if and .Values.stac.enabled (or (not (hasKey .Values.stac "ingress")) .Values.stac.ingress.enabled) }}
-- pathType: {{ .Values.ingress.pathType }}
-  path: /stac{{ .Values.ingress.pathSuffix }}
-  backend:
-    service:
-      name: stac
-      port:
-        number: {{ .Values.service.port }}
-{{- end }}
-```
-
-This ensures:
-- Service paths are only included if the service and its ingress are enabled
-- Backward compatibility is maintained (ingress enabled by default)
-- Clean separation of service configurations
-
 ## Deployment Guide
 
 ### 1. Configure EOAPI-K8S