Configuration

Console terminology: In the Maverics Console, Orchestrator instances and configuration delivery are managed through Deployments. When working directly with YAML, configuration is managed as files delivered via the -config flag or MAVERICS_CONFIG environment variable.

What Configuration Controls

Configuration is how you define what the Orchestrator does — which modes it operates in (OIDC Provider, SAML Provider, HTTP Proxy, LDAP Provider, AI Identity Gateway), which identity providers it connects to, how it routes authentication traffic, and what policies it enforces. Every Orchestrator deployment starts with configuration. The configuration system has three layers. The YAML config file defines the full operational blueprint — modes, connectors, apps, routes, TLS profiles, sessions, caching, and monitoring. Environment variables override specific values for deployment-specific settings like secrets, endpoints, and debug flags without modifying the config file. Remote config sources (Console, S3, Azure Blob, GCS, GitHub, GitLab) enable centralized management across distributed deployments, each selected via its own environment variable. The Orchestrator loads configuration at startup, validates the structure, initializes connectors and modes, and begins serving traffic. For remote config sources, the Orchestrator supports ETag-based change detection with automatic hot-reload when MAVERICS_RELOAD_CONFIG is enabled. Local file changes are also watched during runtime. The Console UI provides a visual interface for building and publishing configuration bundles to remote storage, while the YAML file and environment variables give operators direct control. Both paths produce the same Orchestrator behavior — they are different interfaces to the same configuration model.

Key Concepts

Modes define behavior — Each mode (oidcProvider, samlProvider, ldapProvider, mcpProvider) requires its own top-level key and associated app entries in the config file. An Orchestrator can run multiple modes simultaneously by defining multiple provider keys. The HTTP Proxy mode is configured through app entries with type: proxy.
Connectors bridge identity — Connectors define connections to external identity providers, directories, and attribute sources. They are declared as named entries in the connectors array and referenced by name from apps and policies.
Apps and routes handle traffic — Each entry in the apps array defines how the Orchestrator handles requests for a specific application — its type, upstream target, authentication requirements, and route patterns that match incoming traffic.
Policies enforce rules — Authentication and authorization policies determine who can access what, using identity provider connectors, authorization rules, headers and claims enrichment, or custom Service Extensions.

Configuration Overview

The Orchestrator is configured through a combination of YAML configuration files and environment variables. Configuration defines the Orchestrator’s modes, integrations, routes, and runtime behavior. A minimal configuration specifies the version, at least one connector, one app, and the corresponding provider key for the mode you want to run. As deployments grow, you add TLS profiles, session stores, caching, monitoring, and additional modes — all within the same config file.

Config File Structure

The primary configuration file uses YAML format and organizes settings into logical sections. The Orchestrator loads this file at startup and watches for changes during runtime. The major top-level keys are:

Key	Type	Purpose
`version`	string	Configuration format version (required — currently `"1"`) — see Version
`features`	map	Feature flags for enabling experimental or optional behavior — see Feature Flags
`http`	object	HTTP server bind address, timeouts, access logging, and routing — see HTTP Server Configuration
`tls`	map	Named TLS profiles for server certificates and mTLS — see Transport Layer Security (TLS)
`connectors`	array	Identity provider connections (Azure AD, Okta, LDAP, etc.) — see Identity Fabric
`apps`	array	Application definitions with routes, auth policies, and upstream targets — see Apps & Routes
`session`	object	Session cookie, lifetime, and store configuration — see Sessions
`caches`	array	Named cache stores (Redis, cluster) — see Caches
`logger`	object	Structured logging — verbosity, format, and filtering — see Logging
`health`	object	Health check endpoint and heartbeat monitoring — see Telemetry
`telemetry`	object	OpenTelemetry metrics and traces via OTLP — see Telemetry
`singleLogout`	object	Single logout endpoint and post-logout behavior
`oidcProvider`	object	OIDC Provider mode settings
`samlProvider`	object	SAML Provider mode settings
`ldapProvider`	object	LDAP Provider mode settings
`mcpProvider`	object	AI Identity Gateway MCP bridge and proxy settings
`clusters`	array	Multi-node Orchestrator cluster configuration — see Clusters
`apis`	array	Custom API endpoints powered by Service Extensions — see Service Extensions

Version

The version key specifies the configuration format version. It is required in every configuration file.

Key	Type	Default	Required	Description
`version`	string	—	Yes	Configuration version — currently accepts `"1"`

version: "1"

Feature Flags

The features key is a map of string keys to string values that enable optional or experimental behavior.

Key	Type	Default	Required	Description
`features`	map[string]string	—	No	Feature flag map — values `"true"` or `"enabled"` (case-insensitive) turn a feature on; any other value turns it off

features:
  experimental.clusters: "true"

Parsing Rules

Values are parsed as booleans:

Enabled: "true" or "enabled" (case-insensitive)
Disabled: Any other value, or flag not present

features:
  experimental.clusters: true       # enabled
  experimental.clusters: "enabled"  # also enabled (case-insensitive)
  experimental.clusters: "yes"      # disabled (only "true" and "enabled" are recognized)

Known Flags

Flag	Purpose	Stability
`experimental.clusters`	Enable Orchestrator clustering for high availability with gossip-based membership, shared sessions, caches, and routing	Alpha

Feature flags with the experimental. prefix indicate alpha-level features that may change without notice. See the Changelog for feature flag additions and removals.

HTTP Server Configuration

The http key controls the Orchestrator’s HTTP server — bind address, TLS profile, request timeouts, access logging, SNI-based virtual hosts, and cluster-based routing.

Key	Type	Default	Required	Description
`http.address`	string	`"0.0.0.0:9443"`	No	Network address and port to bind to
`http.tls`	string	—	No	Name of a TLS profile defined under the top-level `tls` key (mutually exclusive with `http.hosts`)
`http.readTimeoutSeconds`	integer	`20`	No	Maximum seconds to read the full request
`http.readHeaderTimeoutSeconds`	integer	`5`	No	Maximum seconds to read request headers
`http.writeTimeoutSeconds`	integer	`20`	No	Maximum seconds to write the response
`http.idleTimeoutSeconds`	integer	`60`	No	Maximum seconds to keep idle connections open
`http.endpointTimeoutSeconds`	integer	`15`	No	Maximum seconds for an endpoint handler to complete
`http.accessLog.disabled`	boolean	`false`	No	Disable HTTP access logging
`http.accessLog.level`	string	`"info"`	No	Access log level — `"debug"`, `"info"`, or `"error"`

SNI-based virtual hosts: The http.hosts array allows binding different TLS profiles to different server names via SNI. It is mutually exclusive with http.tls. Each host entry requires a serverName (or default: true for the fallback) and a tls profile reference. Only one default: true entry is allowed.

Cluster-based routing: The http.routing object enables routing requests across an Orchestrator cluster. Set http.routing.enabled: true with type: "cluster" and a cluster.name reference. Requires the clusters feature to be enabled.

Example

Console UI
Configuration

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

maverics.yaml

version: "1"

http:
  address: "0.0.0.0:9443"
  tls: "default"
  readTimeoutSeconds: 20
  writeTimeoutSeconds: 20
  idleTimeoutSeconds: 60

tls:
  "default":
    certFile: /etc/maverics/certs/server.pem
    keyFile: /etc/maverics/certs/server-key.pem

logger:
  level: "info"
  jsonOutput: true

health:
  location: "/status"
  heartbeat:
    interval: "60s"

connectors:
  - name: azure
    type: azure
    # ...

apps:
  - name: my-app
    type: proxy
    # ...

Environment Variables

Environment variables override config file values and provide a secure mechanism for injecting secrets, endpoints, and deployment-specific settings without modifying the configuration file. Key environment variables include:

MAVERICS_CONFIG — Path to the YAML configuration file (alternative to the -config CLI flag; defaults to /etc/maverics/maverics.yaml)
MAVERICS_SECRET_PROVIDER — Secret provider URL for retrieving secrets from HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, and other providers
MAVERICS_DEBUG_MODE — Enable debug-level logging (true/false), overriding the logger.level setting in the config file
MAVERICS_HTTP_ADDRESS — Override the HTTP server bind address without changing the config file

Environment variables follow the MAVERICS_ prefix convention for Orchestrator-specific settings. The Installation page documents all available CLI flags and environment variables with their precedence rules.

Config Sources

The Orchestrator can load configuration from multiple sources beyond the local filesystem — including the Maverics Console, S3-compatible storage, Azure Blob, GCS, GitHub, and GitLab repositories. Config sources enable centralized management across distributed deployments. There are two categories of config sources:

Local config — A YAML file on disk, specified via MAVERICS_CONFIG or the -config CLI flag. The Orchestrator reads the file at startup and watches for changes during runtime.
Remote config — Console-managed deployments, S3 (MAVERICS_AWS_CONFIG), Azure Blob (MAVERICS_AZURE_CONFIG), GCS (MAVERICS_GCP_CONFIG), GitHub (MAVERICS_GITHUB_CONFIG), or GitLab (MAVERICS_GITLAB_CONFIG). Remote sources support automatic hot-reload via ETag-based change detection.

Only one config source can be active at a time. See the Config Sources reference for all available sources and their environment variables.

Runtime Behavior

Runtime settings control how the Orchestrator operates after loading configuration:

Logging — The logger key controls structured logging with configurable verbosity (debug, info, warn, error), JSON output format, and session ID correlation. The -verbose flag or MAVERICS_DEBUG_MODE=true overrides the configured level to debug at startup.
Health checks — The health key exposes a health check endpoint at the path defined by health.location (defaults to /status) and supports heartbeat monitoring with a configurable interval.
Telemetry — OpenTelemetry-based metrics and traces are exported via the OTLP protocol, configured under the telemetry key.
Graceful shutdown — The Orchestrator handles shutdown signals gracefully, allowing in-flight requests to complete before exiting.
Hot-reload — Remote config sources support automatic reload via ETag-based change detection when MAVERICS_RELOAD_CONFIG=true is set. Local file changes on disk are also watched during runtime.

Installation

CLI flags, environment variables, and deployment options

Modes

Available Orchestrator modes and their configuration

Config Sources

Supported configuration source integrations

Orchestrator Overview

Architecture and capabilities overview

Console Administration

Orchestration

What Configuration Controls

Key Concepts

Configuration Overview

Config File Structure

Version

Feature Flags

Parsing Rules

Known Flags

HTTP Server Configuration

Example

Environment Variables

Config Sources

Runtime Behavior

Installation

Modes

Config Sources

Orchestrator Overview

Console Administration

Orchestration

​What Configuration Controls

​Key Concepts

​Configuration Overview

​Config File Structure

​Version

​Feature Flags

​Parsing Rules

​Known Flags

​HTTP Server Configuration

​Example

​Environment Variables

​Config Sources

​Runtime Behavior

​Related Pages

Installation

Modes

Config Sources

Orchestrator Overview

What Configuration Controls

Key Concepts

Configuration Overview

Config File Structure

Version

Feature Flags

Parsing Rules

Known Flags

HTTP Server Configuration

Example

Environment Variables

Config Sources

Runtime Behavior

Related Pages