Skip to content

config.md

Latest commit

 

History

History
649 lines (514 loc) · 22.7 KB

config.md

File metadata and controls

649 lines (514 loc) · 22.7 KB

HyperFleet API Configuration Guide

Complete reference for configuring HyperFleet API following the HyperFleet Configuration Standard.

Quick Start

Development:

# Create config.yaml with database settings, then:
hyperfleet-api serve --config=config.yaml

Production (Kubernetes):

helm install hyperfleet-api ./charts/ \
  --set 'config.adapters.required.cluster={validation,dns}' \
  --set 'config.adapters.required.nodepool={validation}'

See Configuration Examples for complete setup.

Configuration Methods

HyperFleet API supports multiple configuration sources:

Method Use Case Example
Configuration File Local development, complex configs config.yaml with all settings
Environment Variables Kubernetes (secretKeyRef), CI/CD HYPERFLEET_DATABASE_HOST=localhost
CLI Flags Quick overrides, testing --server-port=9000

All configuration follows these conventions:

  • Environment variables: HYPERFLEET_* prefix, uppercase, underscores (e.g., HYPERFLEET_SERVER_PORT)
  • CLI flags: --kebab-case, lowercase, hyphens (e.g., --server-port)
  • YAML properties: snake_case, lowercase, underscores (e.g., server.port)

Configuration Priority

Configuration sources are applied in the following order (highest to lowest priority):

1. Command-line flags (highest)
   ↓
2. Environment variables (e.g., HYPERFLEET_DATABASE_PASSWORD)
   ↓
3. Configuration file (config.yaml or ConfigMap)
   ↓
4. Default values (lowest)

Examples:

Flag overrides environment variable:

export HYPERFLEET_SERVER_PORT=8000
hyperfleet-api serve --server-port=9000
# Result: Uses 9000 (flag wins)

Environment variable overrides config file:

# config.yaml has: database.password: "config-password"
export HYPERFLEET_DATABASE_PASSWORD=secret-password
# Result: Uses "secret-password" (env var wins)

Special Case - OpenTelemetry Tracing:

HYPERFLEET_TRACING_ENABLED (Tracing standard) has special precedence for cross-component consistency:

HYPERFLEET_TRACING_ENABLED > config (env/flags) > default

See OpenTelemetry Configuration for details.

Configuration File Locations

The configuration file is resolved in the following order:

  1. --config flag - Explicit path provided via CLI

    hyperfleet-api serve --config=/path/to/config.yaml

  2. HYPERFLEET_CONFIG environment variable - Path in environment

    export HYPERFLEET_CONFIG=/path/to/config.yaml

  3. Default paths - Automatic discovery

    • Production: /etc/hyperfleet/config.yaml
    • Development: ./configs/config.yaml

If none are found, the application continues normally using environment variables and CLI flags.

Core Configuration

These settings are required or commonly used by most deployments.

Database Configuration

PostgreSQL database connection settings.

Property Type Default Description
database.dialect string postgres Database dialect
database.host string localhost Database server hostname
database.port int 5432 Database server port
database.name string hyperfleet Database name
database.username string hyperfleet Database username
database.password string "" Database password (use env var with secretKeyRef for Kubernetes)
database.ssl.mode string disable SSL mode: disable, require, verify-ca, verify-full
database.ssl.root_cert_file string "" Root CA certificate for SSL verification
database.pool.max_connections int 50 Maximum open database connections
database.pool.max_idle_connections int 10 Maximum idle database connections
database.pool.conn_max_lifetime duration 5m Maximum connection lifetime
database.pool.conn_max_idle_time duration 1m Maximum connection idle time
database.pool.request_timeout duration 30s Database request timeout
database.pool.conn_retry_attempts int 10 Connection retry attempts on startup (for sidecar startup races)
database.pool.conn_retry_interval duration 3s Interval between connection retry attempts
database.debug bool false Enable SQL query logging

Example:

database:
  host: postgres.example.com
  port: 5432
  name: hyperfleet
  username: hyperfleet
  # Password via environment variable (recommended for Kubernetes: secretKeyRef)
  ssl:
    mode: verify-full
    root_cert_file: /etc/certs/ca.crt
  pool:
    max_connections: 100
    max_idle_connections: 20
    conn_max_lifetime: 10m
    conn_max_idle_time: 2m
    request_timeout: 60s
    conn_retry_attempts: 15
    conn_retry_interval: 5s

Adapters Configuration

Specifies which adapters must be ready for resources to be marked as "Ready". Should be configured for production deployments.

Property Type Default Description
adapters.required.cluster []string [] Cluster adapters required for Ready state (e.g., ["validation","dns"])
adapters.required.nodepool []string [] Nodepool adapters required for Ready state (e.g., ["validation"])

Example:

adapters:
  required:
    cluster:
      - validation
      - dns
      - pullsecret
      - hypershift
    nodepool:
      - validation
      - hypershift

Environment variable (JSON array format):

export HYPERFLEET_ADAPTERS_REQUIRED_CLUSTER='["validation","dns","pullsecret","hypershift"]'
export HYPERFLEET_ADAPTERS_REQUIRED_NODEPOOL='["validation","hypershift"]'

Logging Configuration

Logging behavior and output settings.

Property Type Default Description
logging.level string info Log level: debug, info, warn, error
logging.format string json Log format: json, text
logging.output string stdout Log output: stdout, stderr
logging.otel.enabled bool true Enable OpenTelemetry tracing (see OpenTelemetry Configuration)
logging.masking.enabled bool true Enable sensitive data masking in logs

Example:

logging:
  level: info
  format: json
  output: stdout
  masking:
    enabled: true
    headers:
      - Authorization
      - Cookie
    fields:
      - password
      - token

OpenTelemetry Configuration

OpenTelemetry tracing is configured via standard environment variables following the HyperFleet Tracing Standard.

Enabling Tracing:

Property Environment Variable Type Default Description
logging.otel.enabled HYPERFLEET_TRACING_ENABLED bool true Enable OpenTelemetry tracing (HyperFleet standard)

Standard OpenTelemetry Environment Variables:

Once enabled, tracing is configured using standard OpenTelemetry variables:

Variable Description Default
OTEL_SERVICE_NAME Service name in traces hyperfleet-api
OTEL_EXPORTER_OTLP_ENDPOINT OTLP collector endpoint stdout exporter
OTEL_EXPORTER_OTLP_PROTOCOL Export protocol (grpc or http/protobuf) grpc
OTEL_TRACES_SAMPLER Sampler type parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG Sampling rate (0.0-1.0) 1.0
OTEL_RESOURCE_ATTRIBUTES Additional resource attributes (k=v,k2=v2) -

See: Logging Documentation for tracing configuration details and Tracing Standard for complete reference.

Advanced Configuration

Server Configuration (click to expand)

HTTP server settings for the API endpoint.

Property Type Default Description
server.hostname string "" Public hostname for logging (optional)
server.host string localhost Server bind host (0.0.0.0 for Kubernetes)
server.port int 8000 Server bind port
server.openapi_schema_path string openapi/openapi.yaml Path to OpenAPI schema for spec validation. API fails to start if missing or invalid.
server.timeouts.read duration 5s HTTP read timeout
server.timeouts.write duration 30s HTTP write timeout
server.tls.enabled bool false Enable HTTPS/TLS
server.tls.cert_file string "" Path to TLS certificate file
server.tls.key_file string "" Path to TLS key file
server.jwt.enabled bool true Enable JWT authentication
server.jwt.issuer_url string "" Expected JWT issuer URL for token validation (required when JWT is enabled)
server.jwt.audience string "" Expected JWT audience claim (optional)
server.jwt.identity_claim string email JWT claim used as request identity for audit (e.g. email, preferred_username, sub)
server.identity_header string "" HTTP header name for caller identity; when set and non-empty, overrides JWT claim for audit attribution
server.jwk.cert_file string "" JWK certificate file path (optional)
server.jwk.cert_url string "" JWK certificate URL (required when JWT is enabled and cert_file is not set)

Example:

server:
  hostname: api.example.com
  host: 0.0.0.0
  port: 8000
  tls:
    enabled: true
    cert_file: /etc/certs/tls.crt
    key_file: /etc/certs/tls.key
  jwt:
    enabled: true
    issuer_url: https://your-idp.example.com/auth/realms/your-realm
    audience: ""
  jwk:
    cert_url: https://your-idp.example.com/auth/realms/your-realm/protocol/openid-connect/certs

Caller Identity

The API records who performed each mutation in the created_by, updated_by, and deleted_by audit fields. Two settings control how the caller identity is resolved:

Setting Purpose
server.identity_header HTTP header to read the caller identity from (e.g., X-Forwarded-Email)
server.jwt.identity_claim JWT claim to use as fallback (e.g., email, preferred_username, sub)

Precedence: If both are configured and the header is present in the request, the header value wins. The JWT claim is used only when the header is not configured or is empty in the request.

Validation: Identity values are trimmed, must not exceed 256 characters, and must not contain control characters.

Example — header-based identity (behind an authenticating proxy):

server:
  identity_header: X-Forwarded-Email
  jwt:
    enabled: false

Example — JWT-based identity:

server:
  jwt:
    enabled: true
    issuer_url: https://idp.example.com/realms/hyperfleet
    identity_claim: email
  jwk:
    cert_url: https://idp.example.com/realms/hyperfleet/protocol/openid-connect/certs
Metrics Configuration (click to expand)

Prometheus metrics endpoint settings.

Property Type Default Description
metrics.host string localhost Metrics bind host (0.0.0.0 for Kubernetes)
metrics.port int 9090 Metrics port
metrics.tls.enabled bool false Enable TLS for metrics endpoint
metrics.label_metrics_inclusion_duration duration 168h Duration to include label metrics (7 days)

Example:

metrics:
  host: 0.0.0.0  # Required for Kubernetes Service access
  port: 9090
  tls:
    enabled: false
Health Configuration (click to expand)

Health check endpoint settings.

Property Type Default Description
health.host string localhost Health bind host (0.0.0.0 for Kubernetes)
health.port int 8080 Health port
health.tls.enabled bool false Enable TLS for health endpoint
health.shutdown_timeout duration 20s Graceful shutdown timeout
health.db_ping_timeout duration 2s Database ping timeout for readiness check

Example:

health:
  host: 0.0.0.0  # Required for Kubernetes probes
  port: 8080
  shutdown_timeout: 30s
  db_ping_timeout: 2s

Complete Reference

All Configuration Properties

Complete table of all configuration properties, their environment variables, and types.

Config Path Environment Variable Type Default
Server
server.hostname HYPERFLEET_SERVER_HOSTNAME string ""
server.host HYPERFLEET_SERVER_HOST string localhost
server.port HYPERFLEET_SERVER_PORT int 8000
server.openapi_schema_path HYPERFLEET_SERVER_OPENAPI_SCHEMA_PATH string openapi/openapi.yaml
server.timeouts.read HYPERFLEET_SERVER_TIMEOUTS_READ duration 5s
server.timeouts.write HYPERFLEET_SERVER_TIMEOUTS_WRITE duration 30s
server.tls.enabled HYPERFLEET_SERVER_TLS_ENABLED bool false
server.tls.cert_file HYPERFLEET_SERVER_TLS_CERT_FILE string ""
server.tls.key_file HYPERFLEET_SERVER_TLS_KEY_FILE string ""
server.jwt.enabled HYPERFLEET_SERVER_JWT_ENABLED bool true
server.jwt.issuer_url HYPERFLEET_SERVER_JWT_ISSUER_URL string ""
server.jwt.audience HYPERFLEET_SERVER_JWT_AUDIENCE string ""
server.jwt.identity_claim HYPERFLEET_SERVER_JWT_IDENTITY_CLAIM string email
server.identity_header HYPERFLEET_SERVER_IDENTITY_HEADER string ""
server.jwk.cert_file HYPERFLEET_SERVER_JWK_CERT_FILE string ""
server.jwk.cert_url HYPERFLEET_SERVER_JWK_CERT_URL string ""
Database
database.dialect HYPERFLEET_DATABASE_DIALECT string postgres
database.host HYPERFLEET_DATABASE_HOST string localhost
database.port HYPERFLEET_DATABASE_PORT int 5432
database.name HYPERFLEET_DATABASE_NAME string hyperfleet
database.username HYPERFLEET_DATABASE_USERNAME string hyperfleet
database.password HYPERFLEET_DATABASE_PASSWORD string ""
database.debug HYPERFLEET_DATABASE_DEBUG bool false
database.ssl.mode HYPERFLEET_DATABASE_SSL_MODE string disable
database.ssl.root_cert_file HYPERFLEET_DATABASE_SSL_ROOT_CERT_FILE string ""
database.pool.max_connections HYPERFLEET_DATABASE_POOL_MAX_CONNECTIONS int 50
database.pool.max_idle_connections HYPERFLEET_DATABASE_POOL_MAX_IDLE_CONNECTIONS int 10
database.pool.conn_max_lifetime HYPERFLEET_DATABASE_POOL_CONN_MAX_LIFETIME duration 5m
database.pool.conn_max_idle_time HYPERFLEET_DATABASE_POOL_CONN_MAX_IDLE_TIME duration 1m
database.pool.request_timeout HYPERFLEET_DATABASE_POOL_REQUEST_TIMEOUT duration 30s
database.pool.conn_retry_attempts HYPERFLEET_DATABASE_POOL_CONN_RETRY_ATTEMPTS int 10
database.pool.conn_retry_interval HYPERFLEET_DATABASE_POOL_CONN_RETRY_INTERVAL duration 3s
Logging
logging.level HYPERFLEET_LOGGING_LEVEL string info
logging.format HYPERFLEET_LOGGING_FORMAT string json
logging.output HYPERFLEET_LOGGING_OUTPUT string stdout
logging.otel.enabled HYPERFLEET_TRACING_ENABLED bool true
logging.masking.enabled HYPERFLEET_LOGGING_MASKING_ENABLED bool true
logging.masking.headers HYPERFLEET_LOGGING_MASKING_HEADERS csv Authorization,Cookie
logging.masking.fields HYPERFLEET_LOGGING_MASKING_FIELDS csv password,token
Metrics
metrics.host HYPERFLEET_METRICS_HOST string localhost
metrics.port HYPERFLEET_METRICS_PORT int 9090
metrics.tls.enabled HYPERFLEET_METRICS_TLS_ENABLED bool false
metrics.label_metrics_inclusion_duration HYPERFLEET_METRICS_LABEL_METRICS_INCLUSION_DURATION duration 168h
Health
health.host HYPERFLEET_HEALTH_HOST string localhost
health.port HYPERFLEET_HEALTH_PORT int 8080
health.tls.enabled HYPERFLEET_HEALTH_TLS_ENABLED bool false
health.shutdown_timeout HYPERFLEET_HEALTH_SHUTDOWN_TIMEOUT duration 20s
health.db_ping_timeout HYPERFLEET_HEALTH_DB_PING_TIMEOUT duration 2s
Adapters
adapters.required.cluster HYPERFLEET_ADAPTERS_REQUIRED_CLUSTER json []
adapters.required.nodepool HYPERFLEET_ADAPTERS_REQUIRED_NODEPOOL json []

CLI Flags Reference

All CLI flags and their corresponding configuration paths.

CLI Flag Config Path Type
--config N/A (config file path) string
Server
--server-hostname server.hostname string
--server-host server.host string
--server-port server.port int
--server-openapi-schema-path server.openapi_schema_path string
--server-read-timeout server.timeouts.read duration
--server-write-timeout server.timeouts.write duration
--server-https-enabled server.tls.enabled bool
--server-https-cert-file server.tls.cert_file string
--server-https-key-file server.tls.key_file string
--server-jwt-enabled server.jwt.enabled bool
--server-jwt-issuer-url server.jwt.issuer_url string
--server-jwt-audience server.jwt.audience string
--server-jwt-identity-claim server.jwt.identity_claim string
--server-identity-header server.identity_header string
--server-jwk-cert-file server.jwk.cert_file string
--server-jwk-cert-url server.jwk.cert_url string
Database
--db-dialect database.dialect string
--db-host database.host string
--db-port database.port int
--db-name database.name string
--db-username database.username string
--db-password database.password string
--db-debug database.debug bool
--db-max-open-connections database.pool.max_connections int
--db-root-cert-file database.ssl.root_cert_file string
Logging
--log-level, -l logging.level string
--log-format logging.format string
--log-output logging.output string
Metrics
--metrics-host metrics.host string
--metrics-port metrics.port int
Health
--health-host health.host string
--health-port health.port int

Configuration Examples

Complete configuration file: See configs/config.yaml.example for all options with inline comments.

Deployment: See Deployment Guide for Kubernetes/Helm setup.

Development

Minimal config for local development (no authentication):

server:
  jwt:
    enabled: false

database:
  password: devpassword

adapters:
  required:
    cluster: []
    nodepool: []

Enable TLS

server:
  tls:
    enabled: true
    cert_file: /etc/certs/tls.crt
    key_file: /etc/certs/tls.key

Testing without Authentication

server:
  jwt:
    enabled: false

Configuration Validation

The application performs comprehensive validation at startup.

Validation Rules

Server:

  • server.port: 1-65535
  • server.timeouts.read: ≥ 1s
  • server.timeouts.write: ≥ 1s

Database:

  • database.host: required
  • database.port: 1-65535
  • database.name: required
  • database.username: required
  • database.password: required
  • database.ssl.mode: must be disable, require, verify-ca, or verify-full

Logging:

  • logging.level: must be debug, info, warn, or error
  • logging.format: must be json or text

Adapters:

  • adapters.required.cluster: must be array of strings
  • adapters.required.nodepool: must be array of strings

Validation Errors

If validation fails, the application will exit with a detailed error message:

Error: Configuration validation failed:
- Server.Port must be between 1 and 65535 (got: 0)
- Database.Host is required
- Logging.Level must be one of: debug, info, warn, error (got: invalid)

Troubleshooting

Configuration not loading

Check configuration file path:

# Verify file exists
ls -l /etc/hyperfleet/config.yaml

# Check environment variable
echo $HYPERFLEET_CONFIG

# Use explicit path
hyperfleet-api serve --config=/path/to/config.yaml

Environment variables not working

Verify variable names:

# Check all HYPERFLEET_* variables
env | grep HYPERFLEET_

# Correct format
export HYPERFLEET_SERVER_PORT=8000  # ✅

# Wrong format
export SERVER_PORT=8000  # ❌ Missing HYPERFLEET_ prefix

Validation errors

Common issues:

  1. Invalid log level:

    Error: Logging.Level must be one of: debug, info, warn, error

    Solution: Use lowercase: info, not INFO

  2. Invalid port:

    Error: Server.Port must be between 1 and 65535

    Solution: Check port value in config file or environment variable

  3. Missing required field:

    Error: Database.Host is required

    Solution: Set via config file, environment variable, or CLI flag

Debugging configuration

Enable debug logging to see configuration loading:

export HYPERFLEET_LOGGING_LEVEL=debug
hyperfleet-api serve

Check effective configuration:

# The application logs loaded configuration at startup (with secrets masked)
# Look for log messages like:
# {"level":"info","msg":"Configuration loaded successfully"}

Additional Resources

Configuration Checklist

Before deploying to production, verify:

  • ✅ Environment variables (HYPERFLEET_*) with secretKeyRef for Kubernetes
  • ✅ CLI flags (--kebab-case)
  • ✅ Configuration files (YAML snake_case)
  • ✅ Default values
  • ✅ OpenTelemetry tracing variables (HYPERFLEET_TRACING_ENABLED, OTEL_*) if tracing is enabled