|
2 | 2 |
|
3 | 3 | ## Required Values |
4 | 4 |
|
5 | | -The required values to pass to `helm install` or `helm template` commands can be found by showing what is validated: |
| 5 | +The required values to pass to `helm install` or `helm template` commands can be found in our schema validation: |
6 | 6 |
|
7 | 7 | ```bash |
8 | | -$ head -n 9 <eoapi-k8s-repo>/values.schema.json |
9 | 8 | { |
10 | | - "$schema": "http://json-schema.org/schema#", |
11 | | - "type": "object", |
12 | 9 | "required": [ |
13 | 10 | "service", |
14 | 11 | "gitSha" |
15 | | - ], |
| 12 | + ] |
| 13 | +} |
16 | 14 | ``` |
17 | 15 |
|
18 | | -Most of the required fields have common-sense defaults. |
19 | | -The table below and the `values.yaml` comments should explain what the options and defaults are: |
| 16 | +Most fields have sensible defaults. Here are the core configuration options: |
20 | 17 |
|
21 | | -| **Values Key** | **Description** | **Default** | **Choices** | |
22 | | -|:-------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:------------|:------------------------| |
23 | | -| `service.port` | the port that all vector/raster/stac services run on<br>used in `kind: Service` and `kind: Ingress` | 8080 | your favorite port | |
24 | | -| `gitSha` | sha attached to a `kind: Deployment` key `metadata.labels` | gitshaABC123 | your favorite sha | |
| 18 | +| **Values Key** | **Description** | **Default** | **Choices** | |
| 19 | +|:--------------|:----------------|:------------|:------------| |
| 20 | +| `service.port` | Port for all services (vector/raster/stac) | 8080 | any valid port | |
| 21 | +| `gitSha` | SHA for deployment tracking | gitshaABC123 | any valid SHA | |
| 22 | +| `previousVersion` | Previous version during upgrades | "" | semantic version | |
25 | 23 |
|
| 24 | +## Database Configuration |
26 | 25 |
|
27 | | ---- |
| 26 | +### PostgreSQL Cluster (Default) |
28 | 27 |
|
29 | | -## Default Configuration |
| 28 | +Using Crunchydata's PostgreSQL Operator (`postgresql.type: "postgrescluster"`): |
30 | 29 |
|
31 | | -Running `helm install` from https://devseed.com/eoapi-k8s/ should spin up similar infrastructure in EKS or GKE: |
| 30 | +| **Values Key** | **Description** | **Default** | **Choices** | |
| 31 | +|:--------------|:----------------|:------------|:------------| |
| 32 | +| `postgrescluster.enabled` | Enable PostgreSQL cluster | true | true/false | |
| 33 | +| `postgrescluster.name` | Cluster name | Release name | any valid k8s name | |
| 34 | +| `postgrescluster.postgresVersion` | PostgreSQL version | 16 | supported versions | |
| 35 | +| `postgrescluster.postGISVersion` | PostGIS version | "3.4" | supported versions | |
32 | 36 |
|
33 | | -In EKS or GKE you'll by default get: |
| 37 | +### External Database |
34 | 38 |
|
35 | | -* a HA PostgreSQL database deployment and service via [Crunchdata's Postgresl Operator](https://access.crunchydata.com/documentation/postgres-operator) |
36 | | -* the same vector and raster data fixtures used for testing loaded into the DB |
37 | | -* a load balancer and nginx-compatible ingress with the following path rewrites: |
38 | | - * a `/stac` service for `stac_fastapi.pgstac` |
39 | | - * a `/raster` service for `titler.pgstac` |
40 | | - * a `/vector` service for `tipg.pgstac` |
| 39 | +For external databases, set `postgresql.type` to either: |
41 | 40 |
|
42 | | -Here's a simplified high-level diagram to grok: |
43 | | - |
| 41 | +1. Using plaintext credentials (`external-plaintext`): |
| 42 | +```yaml |
| 43 | +postgresql: |
| 44 | + type: "external-plaintext" |
| 45 | + external: |
| 46 | + host: "your-host" |
| 47 | + port: "5432" |
| 48 | + database: "eoapi" |
| 49 | + credentials: |
| 50 | + username: "eoapi" |
| 51 | + password: "your-password" |
| 52 | +``` |
44 | 53 |
|
45 | | ---- |
| 54 | +2. Using Kubernetes secrets (`external-secret`): |
| 55 | +```yaml |
| 56 | +postgresql: |
| 57 | + type: "external-secret" |
| 58 | + external: |
| 59 | + existingSecret: |
| 60 | + name: "your-secret" |
| 61 | + keys: |
| 62 | + username: "username" |
| 63 | + password: "password" |
| 64 | + host: "your-host" # can also be in secret |
| 65 | + port: "5432" # can also be in secret |
| 66 | + database: "eoapi" # can also be in secret |
| 67 | +``` |
46 | 68 |
|
47 | | -## Additional Options |
| 69 | +## Ingress Configuration |
| 70 | + |
| 71 | +Unified ingress configuration supporting both NGINX and Traefik: |
| 72 | + |
| 73 | +| **Values Key** | **Description** | **Default** | **Choices** | |
| 74 | +|:--------------|:----------------|:------------|:------------| |
| 75 | +| `ingress.enabled` | Enable ingress | true | true/false | |
| 76 | +| `ingress.className` | Ingress controller | "nginx" | "nginx", "traefik" | |
| 77 | +| `ingress.host` | Ingress hostname | "" | valid hostname | |
| 78 | +| `ingress.rootPath` | Doc server root path | "" | valid path | |
| 79 | + |
| 80 | +See [Unified Ingress Configuration](./unified-ingress.md) for detailed setup. |
| 81 | + |
| 82 | +## Service Configuration |
| 83 | + |
| 84 | +Each service (stac, raster, vector, multidim) supports: |
| 85 | + |
| 86 | +| **Values Key** | **Description** | **Default** | **Choices** | |
| 87 | +|:--------------|:----------------|:------------|:------------| |
| 88 | +| `{service}.enabled` | Enable the service | varies | true/false | |
| 89 | +| `{service}.image.name` | Container image | varies | valid image | |
| 90 | +| `{service}.image.tag` | Image tag | varies | valid tag | |
| 91 | +| `{service}.autoscaling.enabled` | Enable HPA | false | true/false | |
| 92 | +| `{service}.autoscaling.type` | Scaling metric | "requestRate" | "cpu", "requestRate", "both" | |
| 93 | + |
| 94 | +Example service configuration: |
| 95 | +```yaml |
| 96 | +raster: |
| 97 | + enabled: true |
| 98 | + autoscaling: |
| 99 | + enabled: true |
| 100 | + minReplicas: 2 |
| 101 | + maxReplicas: 10 |
| 102 | + type: "requestRate" |
| 103 | + targets: |
| 104 | + cpu: 75 |
| 105 | + requestRate: "100000m" |
| 106 | +``` |
48 | 107 |
|
49 | | ---- |
| 108 | +## STAC Browser |
50 | 109 |
|
51 | | -### Key `autoscaling` |
| 110 | +| **Values Key** | **Description** | **Default** | **Choices** | |
| 111 | +|:--------------|:----------------|:------------|:------------| |
| 112 | +| `browser.enabled` | Enable STAC browser | true | true/false | |
| 113 | +| `browser.replicaCount` | Number of replicas | 1 | integer > 0 | |
| 114 | +| `browser.ingress.enabled` | Enable browser ingress | true | true/false | |
52 | 115 |
|
53 | | -#### `autoscaling.type` |
| 116 | +## Deployment Architecture |
54 | 117 |
|
55 | | -| **Values Key** | **Description** | **Default** | **Choices** | |
56 | | -|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|:-----------|:--------------| |
57 | | -| `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> | |
| 118 | +When using default settings, the deployment looks like this: |
| 119 | + |
| 120 | + |
| 121 | +The deployment includes: |
| 122 | +- HA PostgreSQL database (via PostgreSQL Operator) |
| 123 | +- Sample data fixtures |
| 124 | +- Load balancer with path-based routing: |
| 125 | + - `/stac` → STAC API |
| 126 | + - `/raster` → Titiler |
| 127 | + - `/vector` → TiPG |
| 128 | + - `/browser` → STAC Browser |
| 129 | + - `/` → Documentation |
| 130 | + |
| 131 | +## Advanced Configuration |
| 132 | + |
| 133 | +### Autoscaling Behavior |
| 134 | + |
| 135 | +Fine-tune scaling behavior: |
| 136 | + |
| 137 | +```yaml |
| 138 | +autoscaling: |
| 139 | + behaviour: |
| 140 | + scaleDown: |
| 141 | + stabilizationWindowSeconds: 60 |
| 142 | + scaleUp: |
| 143 | + stabilizationWindowSeconds: 0 |
| 144 | +``` |
58 | 145 |
|
59 | | -#### `autoscaling.behaviour.[scaleDown||scaleUp]` |
| 146 | +See [Kubernetes HPA documentation](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#configurable-scaling-behavior) for details. |
60 | 147 |
|
61 | | -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) |
| 148 | +### Resource Requirements |
| 149 | + |
| 150 | +Each service can have custom resource limits: |
| 151 | + |
| 152 | +```yaml |
| 153 | +settings: |
| 154 | + resources: |
| 155 | + limits: |
| 156 | + cpu: "768m" |
| 157 | + memory: "1024Mi" |
| 158 | + requests: |
| 159 | + cpu: "256m" |
| 160 | + memory: "512Mi" |
| 161 | +``` |
| 162 | + |
| 163 | +### Additional Service Settings |
| 164 | + |
| 165 | +Each service also supports: |
| 166 | +```yaml |
| 167 | +settings: |
| 168 | + labels: {} # Additional pod labels |
| 169 | + extraEnvFrom: [] # Additional environment variables from references |
| 170 | + extraVolumeMounts: [] # Additional volume mounts |
| 171 | + extraVolumes: [] # Additional volumes |
| 172 | + envVars: {} # Environment variables |
| 173 | +``` |
0 commit comments