Unified Ingress Configuration¶

This document describes the unified ingress approach implemented in the eoAPI Helm chart.

Overview¶

eoAPI includes a single streamlined ingress configuration with smart defaults that routes to all enabled services. Services handle their own path routing via --root-path configuration, working with any ingress controller.

Why one ingress? - One TLS certificate to manage - One DNS entry - Simple operations - Works for 99% of deployments

Why per-service paths? - Services can opt out: stac.ingress.enabled: false - Custom paths: raster.ingress.path: "/tiles" - Internal-only services stay off ingress

Note: Ingress is only created when at least one service is enabled.

Configuration¶

The ingress configuration in values.yaml:

ingress:
  enabled: true
  className: "nginx"  # or "traefik", or any ingress controller
  rootPath: ""        # Root path for doc server
  host: ""            # Single host (or use hosts array)
  hosts: []           # Multiple hosts (takes precedence over host)
  annotations: {}     # Custom annotations
  tls:
    enabled: false
    secretName: eoapi-tls

Each service can configure its ingress path:

stac:
  enabled: true
  ingress:
    enabled: true
    path: "/stac"  # or "/" for root path

raster:
  enabled: true
  ingress:
    enabled: true
    path: "/raster"

browser:
  enabled: true
  ingress:
    enabled: true
    path: "/browser"

Result: Single Ingress → https://api.example.com/stac, https://api.example.com/raster

Limitations: - Cannot use different ingress classes per service - Cannot use different domains per service - Cannot use different TLS certificates per service

For these cases, deploy multiple helm releases with different configurations.

How It Works¶

Path Routing¶

All services use pathType: Prefix and handle their own path prefixes internally via the --root-path flag:

STAC: --root-path=/stac (or / for root)
Raster: --root-path=/raster
Vector: --root-path=/vector
Multidim: --root-path=/multidim
Browser: Configured via environment variable

Ingress Controller Support¶

The unified ingress works with any Kubernetes ingress controller:

NGINX Ingress Controller¶

ingress:
  enabled: true
  className: "nginx"
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"

Traefik Ingress Controller¶

ingress:
  enabled: true
  className: "traefik"
  # When using TLS, setting host is required
  host: "example.domain.com"
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web

Path Handling Details¶

Services run at root internally, ingress strips prefixes:

Client: GET /raster/tiles/123
  ↓
Ingress strips /raster
  ↓
Service receives: GET /tiles/123

Exception: STAC with stac-auth-proxy.enabled: true receives full path /stac/...

STAC Browser Configuration¶

The STAC browser now uses a separate ingress configuration to handle its unique requirements: - Fixed /browser path prefix - Special rewrite rules for browser-specific routes - Maintains compatibility with both NGINX and Traefik

The browser-specific ingress is automatically configured when browser is enabled:

browser:
  enabled: true
  ingress:
    enabled: true  # Can be disabled independently

Custom Ingress Solutions¶

When using custom ingress solutions (e.g., APISIX, custom routes) where the Helm chart's ingress is disabled (ingress.enabled: false), you can explicitly override the STAC catalog URL for the browser:

ingress:
  enabled: false  # Using custom ingress solution

browser:
  enabled: true
  catalogUrl: "https://earth-search.aws.element84.com/v1"  # Explicit catalog URL
  ingress:
    enabled: false  # Disable browser's built-in ingress

If browser.catalogUrl is not set, the URL will be automatically constructed from ingress.host and stac.ingress.path. This may result in invalid URLs (e.g., http:///stac) when ingress.host is empty.

Setting up TLS with cert-manager¶

cert-manager can be used to automatically obtain and manage TLS certificates. Here's how to set it up with Let's Encrypt:

First, install cert-manager in your cluster:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Create a ClusterIssuer for Let's Encrypt (staging first for testing):

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # Use Let's Encrypt staging environment first
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-staging
    solvers:
    - http01:
        ingress:
          class: nginx  # or traefik, depending on your setup

After testing with staging, create the production issuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx  # or traefik, depending on your setup

Configure your eoAPI ingress to use cert-manager:

ingress:
  enabled: true
  className: "nginx"  # or "traefik"
  host: "eoapi.example.com"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  tls:
    enabled: true
    secretName: eoapi-tls  # cert-manager will create this secret

Migration from 0.7.0¶

If you're upgrading from version 0.7.0:

Remove any pathType and pathSuffix configurations from your values
The system will automatically use the appropriate settings for your chosen controller
For NGINX users, regex path matching is now enabled by default
For Traefik users, strip-prefix middleware is automatically configured

Path Structure¶

Default service paths are:

/stac - STAC API
/raster - Raster API
/vector - Vector API
/multidim - Multi-dimensional API
/browser - STAC Browser
/ - Documentation server (when enabled)

All paths are configurable via service.ingress.path in values.yaml.