Skip to content

Commit 761bb49

Browse files
emmanuelmathotemmanuelmathot
authored
feat: Add support for job annotations in pgstac bootstrap configuration (#381)
1 parent fba8c9f commit 761bb49

File tree

6 files changed

+186
-0
lines changed

6 files changed

+186
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- Added support for annotations on the PgSTAC bootstrap job via `pgstacBootstrap.jobAnnotations` in values.yaml [#381](https://github.com/developmentseed/eoapi-k8s/pull/381)
13+
1014
### Fixed
1115

1216
- Fixed Helm template to check queryables `file` field with schema validation [#380](https://github.com/developmentseed/eoapi-k8s/pull/380)

‎charts/eoapi/templates/database/pgstacbootstrap/job.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ metadata:
3030
helm.sh/hook: "post-install,post-upgrade"
3131
helm.sh/hook-weight: "-5"
3232
helm.sh/hook-delete-policy: "before-hook-creation"
33+
{{- with .Values.pgstacBootstrap.jobAnnotations }}
34+
{{- toYaml . | nindent 4 }}
35+
{{- end }}
3336
spec:
3437
template:
3538
metadata:
@@ -98,6 +101,9 @@ metadata:
98101
helm.sh/hook: "post-install,post-upgrade"
99102
helm.sh/hook-weight: "-4"
100103
helm.sh/hook-delete-policy: "before-hook-creation"
104+
{{- with .Values.pgstacBootstrap.jobAnnotations }}
105+
{{- toYaml . | nindent 4 }}
106+
{{- end }}
101107
spec:
102108
template:
103109
metadata:
@@ -169,6 +175,9 @@ metadata:
169175
helm.sh/hook: "post-install,post-upgrade"
170176
helm.sh/hook-weight: "-3"
171177
helm.sh/hook-delete-policy: "before-hook-creation"
178+
{{- with .Values.pgstacBootstrap.jobAnnotations }}
179+
{{- toYaml . | nindent 4 }}
180+
{{- end }}
172181
spec:
173182
template:
174183
metadata:

‎charts/eoapi/values.schema.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -250,6 +250,13 @@
250250
}
251251
}
252252
},
253+
"jobAnnotations": {
254+
"type": "object",
255+
"description": "Additional annotations to add to the pgstac bootstrap jobs (useful for ArgoCD sync waves)",
256+
"additionalProperties": {
257+
"type": "string"
258+
}
259+
},
253260
"settings": {
254261
"type": "object",
255262
"properties": {

‎charts/eoapi/values.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,8 @@ pgstacBootstrap:
153153
image:
154154
name: ghcr.io/stac-utils/pgstac-pypgstac
155155
tag: v0.9.8
156+
# Annotations to add to the pgstac bootstrap job
157+
jobAnnotations: {}
156158
settings:
157159
# General configuration options
158160
loadSamples: true # Set to false to disable sample data loading

‎docs/argocd.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: "ArgoCD Integration"
3+
description: "Guide for deploying eoAPI with ArgoCD, including sync waves, hooks, and best practices"
4+
external_links:
5+
- name: "ArgoCD Sync Phases and Waves"
6+
url: "https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/"
7+
- name: "ArgoCD Resource Hooks"
8+
url: "https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/"
9+
---
10+
11+
# ArgoCD Integration
12+
13+
This guide covers deploying eoAPI with ArgoCD, focusing on sync order management, database initialization, and troubleshooting common issues.
14+
15+
## Overview
16+
17+
eoAPI includes database initialization jobs that must complete before application services start. ArgoCD's sync waves and hooks provide fine-grained control over resource deployment order.
18+
19+
## Quick Start
20+
21+
For most ArgoCD deployments, add these annotations to ensure proper sync order:
22+
23+
```yaml
24+
pgstacBootstrap:
25+
jobAnnotations:
26+
argocd.argoproj.io/hook: "PreSync"
27+
argocd.argoproj.io/sync-wave: "-1"
28+
argocd.argoproj.io/hook-delete-policy: "HookSucceeded"
29+
```
30+
31+
## Database Bootstrap Jobs
32+
33+
eoAPI includes several database initialization jobs:
34+
35+
| Job | Purpose | Dependencies |
36+
|:----|:--------|:-------------|
37+
| `pgstac-migrate` | Database schema migration | PostgreSQL ready |
38+
| `pgstac-load-samples` | Load sample data | Schema migrated |
39+
| `pgstac-load-queryables` | Configure queryables | Schema migrated |
40+
41+
### Job Execution Order
42+
43+
The jobs use Helm hook weights to ensure proper ordering:
44+
45+
1. **pgstac-migrate** (weight: `-5`) - Creates database schema
46+
2. **pgstac-load-samples** (weight: `-4`) - Loads sample collections/items
47+
3. **pgstac-load-queryables** (weight: `-3`) - Configures search queryables
48+
49+
## ArgoCD Sync Configuration
50+
51+
### Sync Phases
52+
53+
Use **PreSync** for database initialization jobs to ensure they complete before application deployment:
54+
55+
```yaml
56+
pgstacBootstrap:
57+
jobAnnotations:
58+
argocd.argoproj.io/hook: "PreSync"
59+
```
60+
61+
#### Why PreSync?
62+
63+
- **Database First**: Schema must exist before application services start
64+
- **Prevents Race Conditions**: Services won't start until database is ready
65+
- **Follows Best Practices**: Standard pattern for database migrations
66+
- **Dependency Management**: Explicit ordering prevents startup failures
67+
68+
### Sync Waves
69+
70+
Control execution order within phases using sync waves:
71+
72+
```yaml
73+
pgstacBootstrap:
74+
jobAnnotations:
75+
argocd.argoproj.io/sync-wave: "-1" # Run before wave 0 (default)
76+
```
77+
78+
#### Wave Strategy
79+
80+
| Wave | Resources | Purpose |
81+
|:-----|:----------|:--------|
82+
| `-2` | Secrets, ConfigMaps | Prerequisites |
83+
| `-1` | Database jobs | Schema initialization |
84+
| `0` | Applications (default) | Main services |
85+
| `1` | Ingress, monitoring | Post-deployment |
86+
87+
### Cleanup Policies
88+
89+
Configure job cleanup after successful execution:
90+
91+
```yaml
92+
pgstacBootstrap:
93+
jobAnnotations:
94+
argocd.argoproj.io/hook-delete-policy: "HookSucceeded"
95+
```
96+
97+
#### Available Policies
98+
99+
| Policy | Behavior |
100+
|:-------|:---------|
101+
| `HookSucceeded` | Delete after successful completion |
102+
| `HookFailed` | Delete after failure |
103+
| `BeforeHookCreation` | Delete before creating new hook |
104+
105+
## Complete Configuration Example
106+
107+
```yaml
108+
# Application values for ArgoCD deployment
109+
apiVersion: argoproj.io/v1alpha1
110+
kind: Application
111+
metadata:
112+
name: eoapi
113+
namespace: argocd
114+
spec:
115+
project: default
116+
source:
117+
repoURL: https://devseed.com/eoapi-k8s/
118+
chart: eoapi
119+
targetRevision: "0.8.1"
120+
helm:
121+
values: |
122+
# Required values
123+
gitSha: "abc123def456"
124+
125+
# Database initialization with ArgoCD integration
126+
pgstacBootstrap:
127+
enabled: true
128+
jobAnnotations:
129+
argocd.argoproj.io/hook: "PreSync"
130+
argocd.argoproj.io/sync-wave: "-1"
131+
argocd.argoproj.io/hook-delete-policy: "HookSucceeded"
132+
133+
# Service configuration
134+
apiServices: ["stac", "raster", "vector"]
135+
136+
# Ingress setup
137+
ingress:
138+
enabled: true
139+
className: "nginx"
140+
host: "eoapi.example.com"
141+
142+
destination:
143+
server: https://kubernetes.default.svc
144+
namespace: eoapi
145+
146+
syncPolicy:
147+
automated:
148+
prune: true
149+
selfHeal: true
150+
syncOptions:
151+
- "CreateNamespace=true"
152+
- "RespectIgnoreAnnotations=true"
153+
```
154+
155+
## Further Reading
156+
157+
- [ArgoCD Sync Phases and Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/)
158+
- [ArgoCD Resource Hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/)
159+
- [Helm Install Process](../helm-install.md)
160+
- [Configuration Options](../configuration.md)

‎docs/configuration.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,10 @@ kubectl create configmap my-queryables-cm \
222222

223223
The queryables will be automatically loaded during the PgSTAC bootstrap process.
224224

225+
### ArgoCD Integration
226+
227+
For ArgoCD deployments, you can control job sync order using the `jobAnnotations` field. See the [ArgoCD Integration Guide](argocd.md) for detailed configuration and best practices.
228+
225229
## Cloud Storage Authentication
226230

227231
eoAPI services access COG files in cloud storage buckets. Use cloud-native authentication instead of long-lived credentials:

0 commit comments

Comments
 (0)