Skip to content

ArgoCD Integration

This guide covers deploying eoAPI with ArgoCD, focusing on sync order management, database initialization, and troubleshooting common issues.

Overview

eoAPI uses database setup jobs that must finish before the API services start. ArgoCD sync hooks and sync waves let you control the order in which resources are applied.

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 Sync for database initialization jobs to ensure they complete before application deployment:

annotations:
  argocd.argoproj.io/hook: "Sync"

Why use Sync?

  • 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
  • Hook deletion: With PreSync, the database cluster is removed before every sync

Sync Waves

Control execution order within phases using sync waves:

annotations:
  argocd.argoproj.io/sync-wave: "0"

Wave Strategy

Wave Resources Purpose
-2 Secrets, ConfigMaps Prerequisites
-1 Database jobs Schema initialization
0 Applications (default) Main services
1 Ingress, monitoring Post-deployment

Sync executions

Phase -7

All required resources are created or updated:

  • PostgresCluster (Required by all jobs)
  • Config: -pgstac-settings-config
  • Config: -initdb-sql-config
  • Config: -initdb-json-config
  • Config: -pgstac-queryables-config
  • Config: -initdb

Phase -6

Database users are created:

  • Job: -pgstac-superuser-init-db
  • Depends on: Config -initdb

Phase -5

Database schema and settings are applied:

  • Job: -pgstac-migrate
  • Depends on: Config: -pgstac-settings-config

Phase -4

Sample data is loaded:

  • Job: -pgstac-load-samples
  • Depends on:
    • Config: -initdb-sql-config
    • Config: -initdb-json-config
    • Job: -pgstac-migrate

Phase -3

Queryables are loaded:

  • Job: -pgstac-load-queryables
    • Depends on
      • Config: Custom Queryable ConfigsMap
      • Job: -pgstac-migrate
      • Job: -pgstac-load-samples (Optional)

Phase >=0

All other resources are created

NOTE: Queryables are user-defined. Make sure their ConfigMap uses a Sync hook and runs before phase -3.

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: montandon-eoapi-stac-queryables
  annotations:
    argocd.argoproj.io/hook: "Sync"
    argocd.argoproj.io/sync-wave: "-7"
    argocd.argoproj.io/hook-delete-policy: "BeforeHookCreation"
data:
  ...

Complete Configuration Example

Use the pre-defined file: values/argocd.yaml

Note: If this configuration does not work as expected, please feel free to submit fixes or improvements.

# 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: "latest"
    helm:
      valueFiles:
        - values/argocd.yaml
      values: |
        # Required values
        gitSha: "abc123def456"

        # Database initialization with ArgoCD integration
        pgstacBootstrap:
          enabled: true

        # 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