Helm configuration reference

This reference documents all configuration options for the Astro Private Cloud (APC) Helm chart. Use this guide to customize the values.yaml file for your APC installation.

Values file structure

The APC Helm chart uses a hierarchical structure:

global:           # Platform-wide settings
  baseDomain: ""  # Required: your base domain
  plane:
    mode: ""      # unified, control, or data
  # ... more global settings

tags:             # Enable/disable component groups

  monitoring: true
  logging: true

astronomer:       # Platform component settings
  houston: {}
  commander: {}
  registry: {}
  astroUI: {}

nginx: {}         # Ingress configuration
prometheus: {}    # Metrics collection
elasticsearch: {} # Log storage
grafana: {}       # Dashboards
# ... more component sections

Required configuration

Configure the following required values:

global:
  baseDomain: "example.com"  # Your platform domain
  tlsSecret: "astronomer-tls"  # TLS certificate secret name

Global configuration

Base domain and TLS

global:
  # Required: Base domain for all platform endpoints
  # Results in: app.example.com, houston.example.com, etc.
  baseDomain: "example.com"

  # Name of Kubernetes secret containing TLS certificate
  tlsSecret: "astronomer-tls"

  # List of secrets containing private CA certificates
  privateCaCerts: []

Plane Mode (Control, Data, Unified)

Astro Private Cloud 1.0 supports split control plane and data plane deployments:

global:
  plane:
    # Options: unified (default), control, data
    mode: "unified"
    
    # Domain prefix for this plane (used in split deployments)
    domainPrefix: ""

Mode	Description
`unified`	Control and data plane in same cluster (default, like 0.x)
`control`	Control plane only - manages deployments
`data`	Data plane only - runs Airflow workloads

Network policies

global:
  # Enable platform-level network policies
  networkPolicy:
    enabled: true

  # Apply default deny ingress policy
  defaultDenyNetworkPolicy: true

  # Enable namespace labels for network policies
  networkNSLabels: false

RBAC and cluster roles

global:
  # Enable Kubernetes RBAC
  rbacEnabled: true

  # Use cluster-wide roles (required for some features)
  clusterRoles: true

  # Disable management of cluster-scoped resources
  disableManageClusterScopedResources: false

Node selection

Separate platform pods from Airflow pods:

global:
  platformNodePool:
    nodeSelector:
      node-role: platform
    affinity: {}
    tolerations:
      - key: "platform"
        operator: "Equal"
        value: "true"
        effect: "NoSchedule"

Private registry

Use a private container registry:

global:
  privateRegistry:
    enabled: true
    repository: "registry.example.com/astronomer"
    secretName: "registry-credentials"

Namespace pools

Pre-provision namespaces for Airflow Deployments:

global:
  features:
    namespacePools:
      enabled: true
      createRbac: true
      namespaces:
        create: false  # Set true to auto-create
        names:
          - airflow-prod
          - airflow-staging
          - airflow-dev

Storage class

Specify a storage class for all persistent volumes:

global:
  storageClass: "gp3"

OpenShift support

global:
  openshiftEnabled: true
  sccEnabled: true  # Security context constraints

Astronomer platform components

Houston API

Houston is the core internal API that powers the platform:

astronomer:
  houston:
    replicas: 2
    
    resources:
      requests:
        cpu: "500m"
        memory: "1024Mi"
      limits:
        cpu: "1000m"
        memory: "2048Mi"

    # Database connection
    backendSecretName: "houston-backend-secret"
    # Or specify directly:
    backendConnection:
      user: houston
      pass: "password"
      host: postgres.example.com
      port: 5432
      db: houston

    # Airflow database connection template
    airflowBackendSecretName: "airflow-backend-secret"

    # Houston configuration (see houston.config section below)
    config: {}

    # Environment variables common to all houston containers
    env:
      - name: LOG_LEVEL
        value: "info"

    # Worker pods for async processing
    worker:
      enabled: true
      replicas: 2

    # Upgrade all airflow helm deployments when upgrading APC helm deployment
    upgradeDeployments:
      enabled: true

    # Cleanup soft-deleted deployments
    cleanupDeployments:
      enabled: true
      schedule: "0 0 * * *"
      olderThan: 14

    # Cleanup Airflow database metadata
    cleanupAirflowDb:
      enabled: false
      schedule: "23 5 * * *"
      olderThan: 365

Houston configuration (`houston.config`)

Houston accepts extensive configuration via houston.config:

Authentication

astronomer:
  houston:
    config:
      auth:
        # Local username/password auth
        local:
          enabled: true

        # OpenID Connect
        openidConnect:
          # Auth flow: "code" (recommended) or "implicit"
          flow: "code"

          # Microsoft/Azure AD
          microsoft:
            enabled: true
            clientId: "your-client-id"
            clientSecret: "your-client-secret"
            discoveryUrl: "https://login.microsoftonline.com/TENANT/v2.0/.well-known/openid-configuration"

          # Google OAuth
          google:
            enabled: false
            clientId: ""
            clientSecret: ""

          # Okta
          okta:
            enabled: false
            clientId: ""
            clientSecret: ""
            discoveryUrl: ""

          # Import groups from IDP
          idpGroupsImportEnabled: true
          idpGroupsRefreshEnabled: false

        # GitHub via Auth0
        github:
          enabled: false

Deployment defaults

astronomer:
  houston:
    config:
      deployments:
        # Enable Dag-only deployments
        dagOnlyDeployment: true

        # Enable configureDagDeployment if you will be enabling any of the dag deployment types listed below
        configureDagDeployment: true

        # Enable NFS volume mounts
        nfsMountDagDeployment: true

        # Enable git-sync
        gitSyncDagDeployment: true

        # Hard delete deployments
        hardDeleteDeployment: false

        # Enable deployment rollbacks
        enableDeployRollback: true

        # Manual release names
        manualReleaseNames: false

        # Component resource limits
        components:
          - name: workers
            resources:
              default:
              cpu: 1000
              memory: 3840
              minimum:
              cpu: 100
              memory: 384
              limit:
              cpu: 3000
              memory: 11520
            extra:
              - name: terminationGracePeriodSeconds
                default: 600
                minimum: 0
                limit: 36000
              - name: replicas
                default: 1
                minimum: 1
                limit: 10

        # Default Helm values for Airflow deployments
        helm:
          airflow:
            # Default Airflow image
            defaultAirflowRepository: quay.io/astronomer/ap-airflow
            
            # Environment variables for all deployments
            env:
              - name: AIRFLOW__CORE__COLORED_CONSOLE_LOG
                value: "false"

            # Scheduler configuration
            scheduler:
              resources:
                requests:
                  cpu: "500m"
                  memory: "1Gi"

            # Worker configuration
            workers:
              resources:
                requests:
                  cpu: "500m"
                  memory: "1Gi"

Email configuration

astronomer:
  houston:
    config:
      email:
        enabled: true
        smtpUrl: "smtp://smtp.example.com:587"
        reply: "noreply@example.com"

      # Require email confirmation for new users
      emailConfirmation: true

      # Allow public signups
      publicSignups: false

Prometheus integration

astronomer:
  houston:
    config:
      prometheus:
        enabled: true
        host: "http://astronomer-prometheus:9090"

Commander

Commander manages Kubernetes resources for deployments:

astronomer:
  commander:
    replicas: 2
    
    resources:
      requests:
        cpu: "250m"
        memory: "1Gi"
      limits:
        cpu: "500m"
        memory: "2Gi"

    # Air-gapped mode (no external registry access)
    airGapped:
      enabled: false

    # Helm upgrade timeout (seconds)
    upgradeTimeout: 600

    # Environment variables
    env: []

Registry

Container registry for deployment images:

astronomer:
  registry:
    replicas: 1

    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "500m"
        memory: "1024Mi"

    # Persistent storage
    persistence:
      enabled: true
      size: "100Gi"
      storageClassName: ~

    # Use external storage backends
    # AWS S3
    s3:
      enabled: false
      accesskey: ""
      secretkey: ""
      region: "us-east-1"
      bucket: "astronomer-registry"

    # Google Cloud Storage
    gcs:
      enabled: false
      bucket: ""
      useKeyfile: true
      keyfile: /var/gcs-keyfile/astronomer-gcs-keyfile

    # Azure Blob Storage
    azure:
      enabled: false
      accountname: ""
      accountkey: ""
      container: ""

Astro UI

astronomer:
  astroUI:
    replicas: 2

    resources:
      requests:
        cpu: "100m"
        memory: "256Mi"
      limits:
        cpu: "500m"
        memory: "1024Mi"

    env: []

NGINX ingress

nginx:
  replicas: 2

  resources:
    requests:
      cpu: "500m"
      memory: "1024Mi"
    limits:
      cpu: "1"
      memory: "2048Mi"

  # Service type: LoadBalancer, ClusterIP, or NodePort
  serviceType: "LoadBalancer"

  # Specific load balancer IP (optional)
  loadBalancerIP: ~

  # Restrict source IPs
  loadBalancerSourceRanges:
    - "10.0.0.0/8"

  # Private/internal load balancer
  privateLoadBalancer: false

  # NodePort configuration (when serviceType: NodePort)
  httpNodePort: ~
  httpsNodePort: ~

  # Ingress annotations
  ingressAnnotations:
    # AWS
    service.beta.kubernetes.io/aws-load-balancer-internal: "true"
    # GCP
    cloud.google.com/load-balancer-type: "Internal"
    # Azure
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"

  # Proxy settings
  proxyConnectTimeout: 15
  proxyReadTimeout: 600
  proxySendTimeout: 600
  proxyBodySize: "1024m"

  # Default backend
  defaultBackend:
    enabled: true
    resources:
      requests:
        cpu: "100m"
        memory: "50Mi"

Prometheus (Monitoring)

prometheus:
  # Data retention period
  retention: 15d

  # Persistent storage
  persistence:
    enabled: true
    size: "150Gi"

  resources:
    requests:
      cpu: "1000m"
      memory: "4Gi"
    limits:
      cpu: "2000m"
      memory: "8Gi"

Grafana

grafana:
  resources:
    requests:
      cpu: "250m"
      memory: "512Mi"
    limits:
      cpu: "500m"
      memory: "1024Mi"

  # Custom dashboards
  dashboards:
    default:
      custom-dashboard:
        file: dashboards/custom.json

  # Extra environment variables (e.g., SMTP for alerts)
  extraEnvVars:
    - name: GF_SMTP_ENABLED
      value: "true"
    - name: GF_SMTP_HOST
      value: "smtp.example.com:587"

Elasticsearch (Logging)

elasticsearch:
  # Enable persistence
  common:
    persistence:
      enabled: true

  # Client nodes
  client:
    replicas: 2
    heapMemory: "2g"
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"

  # Data nodes
  data:
    replicas: 3
    heapMemory: "2g"
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"
    persistence:
      size: "100Gi"

  # Master nodes
  master:
    replicas: 3
    heapMemory: "2g"
    resources:
      requests:
        cpu: "1"
        memory: "2Gi"
      limits:
        cpu: "2"
        memory: "4Gi"
    persistence:
      size: "20Gi"

Vector (Log Collection)

vector:
  vector:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1000m"
        memory: "1024Mi"

External logging

Forward logs to external Elasticsearch:

global:
  customLogging:
    enabled: true
    scheme: https
    host: "elasticsearch.example.com"
    port: "9200"
    secret: "es-credentials"

NATS (Messaging)

global:
  nats:
    enabled: true
    replicas: 3
    jetStream:
      enabled: true
      tls: false

nats:
  nats:
    resources:
      requests:
        cpu: "75m"
        memory: "30Mi"
      limits:
        cpu: "250m"
        memory: "100Mi"

Database configuration

External PostgreSQL (Recommended)

global:
  # Disable in-cluster PostgreSQL
  postgresqlEnabled: false

astronomer:
  houston:
    backendSecretName: "houston-db-secret"
    # Secret should contain: connection=postgres://user:pass@host:5432/houston

  # Airflow metadata databases
  houston:
    airflowBackendSecretName: "airflow-db-secret"

Database SSL

global:
  ssl:
    enabled: true
    mode: "require"  # disable, allow, prefer, require, verify-ca, verify-full
    grafana:
      sslmode: "require"

PgBouncer (connection pooling)

global:
  pgbouncer:
    enabled: true
    gssSupport: true
    secretName: "astronomer-pgbouncer-config"
    servicePort: "6543"

Auth sidecar (OpenShift)

For OpenShift deployments requiring auth proxy:

global:
  authSidecar:
    enabled: true
    repository: quay.io/astronomer/ap-auth-sidecar
    # tag: 1.29.3
    port: 8084
    resources:
      requests:
        cpu: "500m"
        memory: "512Mi"
      limits:
        cpu: "1000m"
        memory: "1024Mi"

Logging sidecar

Add Vector sidecar to Airflow pods:

global:
  loggingSidecar:
    enabled: true
    name: sidecar-log-consumer
    repository: quay.io/astronomer/ap-vector
    tag: 0.52.0
    resources:
      requests:
        cpu: "100m"
        memory: "386Mi"

Dag-only deployments

global:
  dagOnlyDeployment:
    enabled: true
    repository: quay.io/astronomer/ap-dag-deploy
    tag: 0.8.1
    resources: {}
    persistence: {}

Airflow operator

Enable Kubernetes operator-based deployments:

global:
  airflowOperator:
    enabled: false

Extra objects

Add custom Kubernetes resources:

astronomer:
  extraObjects:
    # Custom LimitRange
    - apiVersion: v1
      kind: LimitRange
      metadata:
        name: default-limits
        namespace: astronomer
      spec:
        limits:
          - default:
              cpu: "1"
              memory: "1Gi"
            defaultRequest:
              cpu: "100m"
              memory: "128Mi"
            type: Container

    # Custom NetworkPolicy
    - apiVersion: networking.k8s.io/v1
      kind: NetworkPolicy
      metadata:
        name: custom-policy
      spec:
        podSelector: {}
        policyTypes:
          - Ingress

Complete example

Here’s an example configuration:

global:
  baseDomain: "airflow.example.com"
  tlsSecret: "astronomer-tls"

  plane:
    mode: "unified"

  rbacEnabled: true
  clusterRoles: true

  networkPolicy:
    enabled: true

  postgresqlEnabled: false

  privateRegistry:
    enabled: true
    repository: "registry.example.com/astronomer"
    secretName: "registry-creds"

  platformNodePool:
    nodeSelector:
      node-type: platform
    tolerations:
      - key: "dedicated"
        value: "platform"
        effect: "NoSchedule"

  ssl:
    enabled: true
    mode: "require"

tags:
  platform: true
  monitoring: true
  logging: true

astronomer:
  houston:
    replicas: 2
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"
      limits:
        cpu: "1000m"
        memory: "2Gi"
    backendSecretName: "houston-db-secret"
    config:
      auth:
        local:
          enabled: false
        openidConnect:
          microsoft:
            enabled: true
            clientId: "your-client-id"
            clientSecret: "your-client-secret"
            discoveryUrl: "https://login.microsoftonline.com/TENANT/v2.0/.well-known/openid-configuration"
      email:
        enabled: true
        smtpUrl: "smtp://smtp.example.com:587"
      publicSignups: false
      deployments:
        hardDeleteDeployment: true
        manualReleaseNames: true

  commander:
    replicas: 2
    resources:
      requests:
        cpu: "250m"
        memory: "1Gi"
      limits:
        cpu: "500m"
        memory: "2Gi"

  registry:
    persistence:
      enabled: true
      size: "200Gi"

nginx:
  replicas: 2
  serviceType: LoadBalancer
  privateLoadBalancer: true
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"

prometheus:
  retention: 30d
  persistence:
    enabled: true
    size: "200Gi"
  resources:
    requests:
      cpu: "1"
      memory: "4Gi"

elasticsearch:
  data:
    replicas: 3
    persistence:
      size: "200Gi"
    resources:
      requests:
        cpu: "1"
        memory: "4Gi"

Validate configuration

After creating your values file, validate it:

# Dry-run to check for errors
helm template astronomer astronomer/astronomer \
  -f values.yaml \
  --namespace astronomer \
  --debug

# Check rendered templates
helm template astronomer astronomer/astronomer \
  -f values.yaml \
  --namespace astronomer > rendered.yaml

Upgrade configuration

(Optional) When updating your values file, you can use the helm diff plugin, and then run the following command to see a diff of your changes:

# Compare changes
helm diff upgrade astronomer astronomer/astronomer \
  -f values.yaml \
  --namespace astronomer

# Apply changes
helm upgrade astronomer astronomer/astronomer \
  -f values.yaml \
  --namespace astronomer

Configure Platform Resources

​Values file structure

​Required configuration

​Global configuration

​Base domain and TLS

​Plane Mode (Control, Data, Unified)

​Network policies

​RBAC and cluster roles

​Node selection

​Private registry

​Namespace pools

​Storage class

​OpenShift support

​Astronomer platform components

​Houston API

​Houston configuration (houston.config)

​Authentication

​Deployment defaults

​Email configuration

​Prometheus integration

​Commander

​Registry

​Astro UI

​NGINX ingress

​Prometheus (Monitoring)

​Grafana

​Elasticsearch (Logging)

​Vector (Log Collection)

​External logging

​NATS (Messaging)

​Database configuration

​External PostgreSQL (Recommended)

​Database SSL

​PgBouncer (connection pooling)

​Auth sidecar (OpenShift)

​Logging sidecar

​Dag-only deployments

​Airflow operator

​Extra objects

​Complete example

​Validate configuration

​Upgrade configuration

​Related documentation