config.yaml.example

# HyperFleet API Configuration Example
# Follows HyperFleet Configuration Standard
# Copy this to /etc/hyperfleet/config.yaml (production) or ./configs/config.yaml (development)

# Server Configuration
server:
  hostname: ""                      # Public hostname (optional)
  host: "0.0.0.0"                   # Server bind host (use "localhost" for local dev, "0.0.0.0" for containers/K8s)
  port: 8000                        # Server bind port

  timeouts:
    read: 5s                        # HTTP read timeout
    write: 30s                      # HTTP write timeout

  tls:
    enabled: false                  # Enable TLS
    cert_file: ""                   # Path to TLS cert file (required if enabled=true)
    key_file: ""                    # Path to TLS key file (required if enabled=true)

  jwt:
    enabled: true                   # Enable JWT authentication
    configs:                        # List of JWT issuer configurations (required when jwt.enabled=true)
      - issuer_url: ""              # OIDC issuer URL for token validation (required)
        jwk_cert_url: ""            # URL to fetch JWK certificates from (required unless jwk_cert_file is set)
        jwk_cert_file: ""           # Path to a local JWK certificate file (alternative to jwk_cert_url)
        jwk_cert_ca_file: ""        # CA certificate file for TLS when fetching jwk_cert_url (optional)
        header: Authorization       # HTTP header to read the JWT from (default: Authorization)
        audience: ""                # Expected JWT audience claim (optional)
        identity_claim: email       # JWT claim used as request identity for audit (default: email)
        identity_claim_pattern: ""  # Regex pattern to validate the identity claim value (optional)
        identity_header: ""         # Per-issuer HTTP header for caller identity; overrides JWT claim when set (e.g. X-HyperFleet-Identity)

  tenant:
    enabled: false                  # Enable tenant enforcement middleware
    system_header: ""               # Header marking system callers (required when enabled=true)
    dimensions: []                  # Tenant dimension headers (header, key, required); at least one required=true if enabled

# Database Configuration
database:
  dialect: postgres                 # Database dialect (postgres, mysql)
  host: localhost                   # Database host
  host_file: ""                     # Path to a file containing the database host (overrides host if set)
  port: 5432                        # Database port
  port_file: ""                     # Path to a file containing the database port (overrides port if set)
  name: hyperfleet                  # Database name
  name_file: ""                     # Path to a file containing the database name (overrides name if set)
  username: hyperfleet              # Database username
  username_file: ""                 # Path to a file containing the database username (overrides username if set)
  password: ""                      # Database password (use env var HYPERFLEET_DATABASE_PASSWORD instead)
  password_file: ""                 # Path to a file containing the database password (overrides password if set)
  debug: false                      # Enable database debug logging

  ssl:
    mode: disable                   # SSL mode (disable, require, verify-ca, verify-full)
    root_cert_file: ""              # Root certificate file (for SSL)

  pool:
    max_connections: 50             # Maximum open connections
    max_idle_connections: 10        # Maximum idle connections
    conn_max_lifetime: 5m           # Maximum connection lifetime
    conn_max_idle_time: 1m          # Maximum connection idle time
    request_timeout: 30s            # Database request timeout
    conn_retry_attempts: 10         # Connection retry attempts on startup
    conn_retry_interval: 3s         # Interval between retry attempts

# Logging Configuration
logging:
  level: info                       # Log level (debug, info, warn, error)
  format: json                      # Log format (json, text)
  output: stdout                    # Log output (stdout, stderr)

  otel:
    enabled: true                   # Enable OpenTelemetry tracing (overridden by HYPERFLEET_TRACING_ENABLED env var)

  masking:
    enabled: true                   # Enable masking of sensitive data

    headers:                        # Sensitive HTTP headers to mask
      - Authorization
      - X-API-Key
      - Cookie
      - X-Auth-Token
      - X-Forwarded-Authorization

    fields:                         # Sensitive JSON fields to mask
      - password
      - secret
      - token
      - api_key
      - access_token
      - refresh_token
      - client_secret


# Metrics Configuration
metrics:
  host: localhost                   # Metrics server host
  port: 9090                        # Metrics server port

  tls:
    enabled: false                  # Enable TLS for metrics server

  label_metrics_inclusion_duration: 168h  # Duration for label metrics inclusion (7 days)

# Health Check Configuration
health:
  host: localhost                   # Health check server host
  port: 8080                        # Health check server port

  tls:
    enabled: false                  # Enable TLS for health server

  shutdown_timeout: 20s             # Graceful shutdown timeout
  db_ping_timeout: 2s               # Database ping timeout for readiness check
# Entity Registration
# Generic resource types registered at startup. Each entry auto-generates
# REST endpoints, spec validation, and delete policies.
# See docs/config.md for condition mapping documentation.
entities:
  - kind: Cluster
    plural: clusters
    spec_schema_name: ClusterSpec
    required_adapters: [validation, dns, pullsecret, hypershift]

    name_min_len: 3
    name_max_len: 53
    require_spec_schema: true

    # CEL-based condition mapping rules
    # conditions:
      # Example: Expose Landing Zone namespace readiness
      # - type: LandingZoneReady
      #   when:
      #     expression: 'statuses.exists(s, s.adapter == "landing-zone-adapter" && s.conditions.exists(c, c.type == "NamespaceReady"))'
      #   output:
      #     status:
      #       expression: |
      #         statuses.filter(s, s.adapter == "landing-zone-adapter")[0]
      #           .conditions.filter(c, c.type == "NamespaceReady")[0].status
      #     reason:
      #       expression: |
      #         statuses.filter(s, s.adapter == "landing-zone-adapter")[0]
      #           .conditions.filter(c, c.type == "NamespaceReady")[0].reason
      #     message:
      #       expression: |
      #         "Landing zone: " + statuses.filter(s, s.adapter == "landing-zone-adapter")[0]
      #           .conditions.filter(c, c.type == "NamespaceReady")[0].message

  - kind: NodePool
    plural: nodepools
    parent_kind: Cluster
    on_parent_delete: cascade
    spec_schema_name: NodePoolSpec
    required_adapters: [validation, hypershift]

    name_min_len: 3
    name_max_len: 15
    require_spec_schema: true

    # CEL-based condition mapping rules
    # conditions:
      # Example: Expose Validation quota check status
      # - type: QuotaValid
      #   when:
      #     expression: 'statuses.exists(s, s.adapter == "validation-adapter" && s.conditions.exists(c, c.type == "QuotaSufficient"))'
      #   output:
      #     status:
      #       expression: |
      #         statuses.filter(s, s.adapter == "validation-adapter")[0]
      #           .conditions.filter(c, c.type == "QuotaSufficient")[0].status
      #     reason:
      #       expression: |
      #         statuses.filter(s, s.adapter == "validation-adapter")[0]
      #           .conditions.filter(c, c.type == "QuotaSufficient")[0].reason
      #     message:
      #       expression: |
      #         statuses.filter(s, s.adapter == "validation-adapter")[0]
      #           .conditions.filter(c, c.type == "QuotaSufficient")[0].message

  - kind: Channel
    plural: channels
    spec_schema_name: ChannelSpec


  - kind: Version
    plural: versions
    parent_kind: Channel
    on_parent_delete: restrict
    spec_schema_name: VersionSpec


  - kind: WifConfig
    plural: wifconfigs
    spec_schema_name: WifConfigSpec

# ----------------------------------------------------------------------------
# Configuration Priority (highest to lowest):
# 1. Command-line flags (e.g., --server-host=0.0.0.0 --server-port=8000)
# 2. Environment variables (e.g., HYPERFLEET_SERVER_HOST=0.0.0.0)
# 3. Configuration file (this file)
# 4. Default values
#
# Environment Variable Naming Convention:
# - All env vars use HYPERFLEET_ prefix
# - All uppercase: HYPERFLEET_SERVER_HOST=localhost
#
#
# Exception - Standard OpenTelemetry Variables:
# - OTEL_* variables follow OpenTelemetry standard naming (no HYPERFLEET_ prefix)
# - HYPERFLEET_TRACING_ENABLED is the only HYPERFLEET-prefixed tracing variable
# - See "OpenTelemetry Tracing Configuration" section below for details
#
# CLI Flag Naming Convention:
# - All flags use kebab-case with hyphens
# - Nested values use hyphens: --server-host --server-port
# - All lowercase: --log-level=info
#
# Example: server.host → --server-host
#
# YAML Naming Convention:
# - All properties use snake_case (single words with underscores for multi-word labels)
# - Single-word hierarchy nodes: server, database, logging, timeouts, pool, masking
# - Multi-word keys use underscores: base_url, cert_file, max_connections
#
# File-based Secrets:
# Sensitive values can be loaded from files using *_FILE environment variables.
# The file content will be read and used as the configuration value.
#
# Note: File path fields (cert_file, key_file, etc.) should be set
# directly via environment variables, not loaded from files, since they already
# represent file paths. Use HYPERFLEET_SERVER_TLS_CERT_FILE=/path/to/cert.pem
# to set the path directly.
#
# Supported file-based secrets:
# - HYPERFLEET_DATABASE_HOST_FILE=/secrets/db-host
# - HYPERFLEET_DATABASE_PORT_FILE=/secrets/db-port
# - HYPERFLEET_DATABASE_USERNAME_FILE=/secrets/db-username
# - HYPERFLEET_DATABASE_PASSWORD_FILE=/secrets/db-password
# - HYPERFLEET_DATABASE_NAME_FILE=/secrets/db-name
#
# OpenTelemetry Tracing Configuration:
# HyperFleet uses standard OpenTelemetry environment variables for tracing.
# These have special precedence and override config file settings.
#
# Master tracing switch:
# - HYPERFLEET_TRACING_ENABLED=true|false  # Enables/disables all tracing (overrides logging.otel.enabled)
#
# Standard OTEL environment variables (only used when tracing is enabled):
# - OTEL_SERVICE_NAME=hyperfleet-api       # Service name in traces (default: hyperfleet-api)
# - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317  # OTLP collector endpoint (if not set, uses stdout)
# - OTEL_EXPORTER_OTLP_PROTOCOL=grpc       # Protocol: grpc (default) or http/protobuf
# - OTEL_TRACES_SAMPLER=parentbased_traceidratio  # Sampler type (default: parentbased_traceidratio)
# - OTEL_TRACES_SAMPLER_ARG=1.0            # Sampling rate 0.0-1.0 (default: 1.0 = 100%)
# - OTEL_RESOURCE_ATTRIBUTES=env=prod,region=us-east  # Additional resource attributes
#
# Variable Precedence for Tracing:
# 1. HYPERFLEET_TRACING_ENABLED (env var) - master switch
# 2. logging.otel.enabled (config file)
# 3. Default (true)
#
# See docs/logging.md for complete OpenTelemetry configuration guide.
# ----------------------------------------------------------------------------