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
    issuer_url: ""                  # JWT issuer URL (required when jwt.enabled=true)
    audience: ""                    # JWT audience claim (optional)

  jwk:
    cert_file: ""                   # JWK certificate file path
    cert_url: ""                    # JWK certificate URL (required when jwt.enabled=true and cert_file is not set)

# Database Configuration
database:
  dialect: postgres                 # Database dialect (postgres, mysql)
  host: localhost                   # Database host
  port: 5432                        # Database port
  name: hyperfleet                  # Database name
  username: hyperfleet              # Database username
  password: ""                      # Database password (use env var HYPERFLEET_DATABASE_PASSWORD instead)
  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

# Adapter Requirements Configuration
adapters:
  required:
    cluster:                        # Required adapters for cluster resources
      - validation
      - dns
      - pullsecret
      - hypershift

    nodepool:                       # Required adapters for nodepool resources
      - validation
      - hypershift

# ----------------------------------------------------------------------------
# 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.
# ----------------------------------------------------------------------------