diff --git a/CHANGELOG.md b/CHANGELOG.md index 35983870..1ead4454 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Added support for annotations on the PgSTAC bootstrap job via `pgstacBootstrap.jobAnnotations` in values.yaml [#381](https://github.com/developmentseed/eoapi-k8s/pull/381) + ### Fixed - Fixed Helm template to check queryables `file` field with schema validation [#380](https://github.com/developmentseed/eoapi-k8s/pull/380) diff --git a/charts/eoapi/templates/database/pgstacbootstrap/job.yaml b/charts/eoapi/templates/database/pgstacbootstrap/job.yaml index 83b15ab5..effbeb54 100644 --- a/charts/eoapi/templates/database/pgstacbootstrap/job.yaml +++ b/charts/eoapi/templates/database/pgstacbootstrap/job.yaml @@ -30,6 +30,9 @@ metadata: helm.sh/hook: "post-install,post-upgrade" helm.sh/hook-weight: "-5" helm.sh/hook-delete-policy: "before-hook-creation" + {{- with .Values.pgstacBootstrap.jobAnnotations }} + {{- toYaml . | nindent 4 }} + {{- end }} spec: template: metadata: @@ -98,6 +101,9 @@ metadata: helm.sh/hook: "post-install,post-upgrade" helm.sh/hook-weight: "-4" helm.sh/hook-delete-policy: "before-hook-creation" + {{- with .Values.pgstacBootstrap.jobAnnotations }} + {{- toYaml . | nindent 4 }} + {{- end }} spec: template: metadata: @@ -169,6 +175,9 @@ metadata: helm.sh/hook: "post-install,post-upgrade" helm.sh/hook-weight: "-3" helm.sh/hook-delete-policy: "before-hook-creation" + {{- with .Values.pgstacBootstrap.jobAnnotations }} + {{- toYaml . | nindent 4 }} + {{- end }} spec: template: metadata: diff --git a/charts/eoapi/values.schema.json b/charts/eoapi/values.schema.json index d860cf0e..c53e6d15 100644 --- a/charts/eoapi/values.schema.json +++ b/charts/eoapi/values.schema.json @@ -250,6 +250,13 @@ } } }, + "jobAnnotations": { + "type": "object", + "description": "Additional annotations to add to the pgstac bootstrap jobs (useful for ArgoCD sync waves)", + "additionalProperties": { + "type": "string" + } + }, "settings": { "type": "object", "properties": { diff --git a/charts/eoapi/values.yaml b/charts/eoapi/values.yaml index 582301a5..7de99dd9 100644 --- a/charts/eoapi/values.yaml +++ b/charts/eoapi/values.yaml @@ -153,6 +153,8 @@ pgstacBootstrap: image: name: ghcr.io/stac-utils/pgstac-pypgstac tag: v0.9.8 + # Annotations to add to the pgstac bootstrap job + jobAnnotations: {} settings: # General configuration options loadSamples: true # Set to false to disable sample data loading diff --git a/docs/argocd.md b/docs/argocd.md new file mode 100644 index 00000000..0cf662a9 --- /dev/null +++ b/docs/argocd.md @@ -0,0 +1,160 @@ +--- +title: "ArgoCD Integration" +description: "Guide for deploying eoAPI with ArgoCD, including sync waves, hooks, and best practices" +external_links: + - name: "ArgoCD Sync Phases and Waves" + url: "https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/" + - name: "ArgoCD Resource Hooks" + url: "https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/" +--- + +# ArgoCD Integration + +This guide covers deploying eoAPI with ArgoCD, focusing on sync order management, database initialization, and troubleshooting common issues. + +## Overview + +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. + +## Quick Start + +For most ArgoCD deployments, add these annotations to ensure proper sync order: + +```yaml +pgstacBootstrap: + jobAnnotations: + argocd.argoproj.io/hook: "PreSync" + argocd.argoproj.io/sync-wave: "-1" + argocd.argoproj.io/hook-delete-policy: "HookSucceeded" +``` + +## Database Bootstrap Jobs + +eoAPI includes several database initialization jobs: + +| Job | Purpose | Dependencies | +|:----|:--------|:-------------| +| `pgstac-migrate` | Database schema migration | PostgreSQL ready | +| `pgstac-load-samples` | Load sample data | Schema migrated | +| `pgstac-load-queryables` | Configure queryables | Schema migrated | + +### Job Execution Order + +The jobs use Helm hook weights to ensure proper ordering: + +1. **pgstac-migrate** (weight: `-5`) - Creates database schema +2. **pgstac-load-samples** (weight: `-4`) - Loads sample collections/items +3. **pgstac-load-queryables** (weight: `-3`) - Configures search queryables + +## ArgoCD Sync Configuration + +### Sync Phases + +Use **PreSync** for database initialization jobs to ensure they complete before application deployment: + +```yaml +pgstacBootstrap: + jobAnnotations: + argocd.argoproj.io/hook: "PreSync" +``` + +#### Why PreSync? + +- **Database First**: Schema must exist before application services start +- **Prevents Race Conditions**: Services won't start until database is ready +- **Follows Best Practices**: Standard pattern for database migrations +- **Dependency Management**: Explicit ordering prevents startup failures + +### Sync Waves + +Control execution order within phases using sync waves: + +```yaml +pgstacBootstrap: + jobAnnotations: + argocd.argoproj.io/sync-wave: "-1" # Run before wave 0 (default) +``` + +#### Wave Strategy + +| Wave | Resources | Purpose | +|:-----|:----------|:--------| +| `-2` | Secrets, ConfigMaps | Prerequisites | +| `-1` | Database jobs | Schema initialization | +| `0` | Applications (default) | Main services | +| `1` | Ingress, monitoring | Post-deployment | + +### Cleanup Policies + +Configure job cleanup after successful execution: + +```yaml +pgstacBootstrap: + jobAnnotations: + argocd.argoproj.io/hook-delete-policy: "HookSucceeded" +``` + +#### Available Policies + +| Policy | Behavior | +|:-------|:---------| +| `HookSucceeded` | Delete after successful completion | +| `HookFailed` | Delete after failure | +| `BeforeHookCreation` | Delete before creating new hook | + +## Complete Configuration Example + +```yaml +# Application values for ArgoCD deployment +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: eoapi + namespace: argocd +spec: + project: default + source: + repoURL: https://devseed.com/eoapi-k8s/ + chart: eoapi + targetRevision: "0.8.1" + helm: + values: | + # Required values + gitSha: "abc123def456" + + # Database initialization with ArgoCD integration + pgstacBootstrap: + enabled: true + jobAnnotations: + argocd.argoproj.io/hook: "PreSync" + argocd.argoproj.io/sync-wave: "-1" + argocd.argoproj.io/hook-delete-policy: "HookSucceeded" + + # Service configuration + apiServices: ["stac", "raster", "vector"] + + # Ingress setup + ingress: + enabled: true + className: "nginx" + host: "eoapi.example.com" + + destination: + server: https://kubernetes.default.svc + namespace: eoapi + + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - "CreateNamespace=true" + - "RespectIgnoreAnnotations=true" +``` + +## Further Reading + +- [ArgoCD Sync Phases and Waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/) +- [ArgoCD Resource Hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/) +- [Helm Install Process](../helm-install.md) +- [Configuration Options](../configuration.md) diff --git a/docs/configuration.md b/docs/configuration.md index c41f31b6..a0362589 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -222,6 +222,10 @@ kubectl create configmap my-queryables-cm \ The queryables will be automatically loaded during the PgSTAC bootstrap process. +### ArgoCD Integration + +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. + ## Cloud Storage Authentication eoAPI services access COG files in cloud storage buckets. Use cloud-native authentication instead of long-lived credentials: