Aperture Controller Configuration Reference

info

See also Aperture Controller installation.

List of all configuration parameters for Aperture Controller.

Table of contents

COMMON CONFIGURATION

Key	Reference
client	Client
etcd	Etcd
liveness	Liveness
log	Log
metrics	Metrics
policies	PoliciesConfig
profilers	Profilers
prometheus	Prometheus
readiness	Readiness
server	Server
watchdog	Watchdog

CONTROLLER CONFIGURATION

Key	Reference
otel	OTel

EXTENSION CONFIGURATION

Key	Reference
fluxninja	FluxNinjaExtension
sentry	SentryExtension

Reference

client

proxy

(ProxyConfig) Environment variable prefix: APERTURE_CONTROLLER_CLIENT_PROXY_

---

etcd

(EtcdConfig) Environment variable prefix: APERTURE_CONTROLLER_ETCD_

---

fluxninja

(FluxNinjaExtensionConfig) Environment variable prefix: APERTURE_CONTROLLER_FLUXNINJA_

---

liveness

scheduler

(JobGroupConfig) Environment variable prefix: APERTURE_CONTROLLER_LIVENESS_SCHEDULER_

service

(JobConfig) Environment variable prefix: APERTURE_CONTROLLER_LIVENESS_SERVICE_

---

log

(LogConfig) Environment variable prefix: APERTURE_CONTROLLER_LOG_

---

metrics

(MetricsConfig) Environment variable prefix: APERTURE_CONTROLLER_METRICS_

---

otel

(ControllerOTelConfig) Environment variable prefix: APERTURE_CONTROLLER_OTEL_

---

policies

cr_watcher

(CRWatcherConfig) Environment variable prefix: APERTURE_CONTROLLER_POLICIES_CR_WATCHER_

promql_jobs_scheduler

(JobGroupConfig) Environment variable prefix: APERTURE_CONTROLLER_POLICIES_PROMQL_JOBS_SCHEDULER_

---

profilers

(ProfilersConfig) Environment variable prefix: APERTURE_CONTROLLER_PROFILERS_

---

prometheus

(PrometheusConfig) Environment variable prefix: APERTURE_CONTROLLER_PROMETHEUS_

http_client

(HTTPClientConfig) Environment variable prefix: APERTURE_CONTROLLER_PROMETHEUS_HTTP_CLIENT_

---

readiness

scheduler

(JobGroupConfig) Environment variable prefix: APERTURE_CONTROLLER_READINESS_SCHEDULER_

service

(JobConfig) Environment variable prefix: APERTURE_CONTROLLER_READINESS_SERVICE_

---

sentry

(SentryConfig) Environment variable prefix: APERTURE_CONTROLLER_SENTRY_

---

server

grpc

(GRPCServerConfig) Environment variable prefix: APERTURE_CONTROLLER_SERVER_GRPC_

grpc_gateway

(GRPCGatewayConfig) Environment variable prefix: APERTURE_CONTROLLER_SERVER_GRPC_GATEWAY_

http

(HTTPServerConfig) Environment variable prefix: APERTURE_CONTROLLER_SERVER_HTTP_

listener

(ListenerConfig) Environment variable prefix: APERTURE_CONTROLLER_SERVER_LISTENER_

tls

(ServerTLSConfig) Environment variable prefix: APERTURE_CONTROLLER_SERVER_TLS_

---

watchdog

memory

(WatchdogConfig) Environment variable prefix: APERTURE_CONTROLLER_WATCHDOG_MEMORY_

---

Objects

---

AdaptivePolicy

AdaptivePolicy creates a policy that forces GC when the usage surpasses the configured factor of the available memory. This policy calculates next target as usage+(limit-usage)*factor.

enabled

(bool, default: false)

Flag to enable the policy

factor

(float64, minimum: 0, maximum: 1, default: 0.5)

Factor sets user-configured limit of available memory

---

BackoffConfig

BackoffConfig holds configuration for gRPC client backoff.

base_delay

(string, default: "1s")

Base Delay

jitter

(float64, minimum: 0, default: 0.2)

Jitter

max_delay

(string, default: "120s")

Max Delay

multiplier

(float64, minimum: 0, default: 1.6)

Backoff multiplier

---

BatchAlertsConfig

BatchAlertsConfig defines configuration for OTel batch processor.

send_batch_max_size

(uint32, minimum: 0)

SendBatchMaxSize is the upper limit of the batch size. Bigger batches will be split into smaller units.

send_batch_size

(uint32, minimum: 0)

SendBatchSize is the number of alerts to send in a batch.

timeout

(string, default: "1s")

Timeout sets the time after which a batch will be sent regardless of size.

---

CRWatcherConfig

CRWatcherConfig holds fields to configure the Kubernetes watcher for Aperture Policy custom resource.

enabled

(bool, default: false)

Enabled indicates whether the Kubernetes watcher is enabled.

---

ClientConfig

ClientConfig is the client configuration.

grpc

(GRPCClientConfig)

gRPC client settings.

http

(HTTPClientConfig)

HTTP client settings.

---

ClientTLSConfig

ClientTLSConfig is the configuration for client TLS.

ca_file

(string)

cert_file

(string)

insecure_skip_verify

(bool)

key_file

(string)

key_log_file

(string)

---

ControllerOTelConfig

ControllerOTelConfig is the configuration for Controller's OTel collector.

enable_high_cardinality_platform_metrics

(bool, default: false)

EnableHighCardinalityPlatformMetrics filters out high cardinality Aperture platform metrics from being published to Prometheus. Filtered out metrics are: "grpcserver_handled_total." "grpcserver_handling_seconds." "grpcserver_handling_seconds_bucket." "grpcserver_handling_seconds_count." "grpcserver_handling_seconds_sum." "grpcserver_msg_received_total." "grpcserver_msg_sent_total." "grpcserver_started_total."

batch_alerts

(BatchAlertsConfig)

BatchAlerts configures batch alerts processor.

ports

(PortsConfig)

Ports configures debug, health and extension ports values.

---

EtcdConfig

EtcdConfig holds configuration for etcd client.

endpoints

([]string)

List of etcd server endpoints

lease_ttl

(string, default: "10s")

Lease time-to-live

log_level

(string, format: empty | empty, one of: debug | DEBUG | info | INFO | warn | WARN | error | ERROR | dpanic | DPANIC | panic | PANIC | fatal | FATAL, default: "error")

LogLevel of logs coming from inside the etcd client

namespace

(string, default: "aperture")

etcd namespace

password

(string)

username

(string)

Authentication

tls

(ClientTLSConfig)

Client TLS configuration

---

FluxNinjaExtensionConfig

FluxNinjaExtensionConfig is the configuration for FluxNinja integration.

api_key

(string)

API Key for this agent. If this key is not set, the extension won't be enabled.

agent_api_key

(string, DEPRECATED)

Deprecated: v3.0.0. Use APIKey instead

controller_id

(string)

Overrides Controller ID for Aperture Controller. If not set, random id will be generated and persisted in etcd.

disable_local_otel_pipeline

(bool, default: false)

Disables local Prometheus OTel pipelines for metrics. Implied by EnableCloudController.

enable_cloud_controller

(bool, default: false)

Whether to connect to Aperture Cloud Controller.

Enabling this flag configures various agent components to point to the Aperture Cloud Controller, for example configures remote etcd endpoint and disables local Prometheus OTel pipelines.

Disable this flag only if using Self-Hosted Aperture Controller.

endpoint

(string, format: empty | hostname_port | url | fqdn)

Address to gRPC or HTTP(s) server listening in agent service. For connecting to Aperture Cloud Controller, the endpoint should be a grpc/http2 address. For self-hosted controller, the HTTP protocol address can start with http(s)://.

heartbeat_interval

(string, default: "5s")

Interval between each heartbeat.

installation_mode

(string, one of: KUBERNETES_SIDECAR | KUBERNETES_DAEMONSET | LINUX_BARE_METAL | CLOUD_AGENT, default: "LINUX_BARE_METAL")

Installation mode describes on which underlying platform the Agent or the Controller is being run.

client

(ClientConfig)

Client configuration.

---

GRPCClientConfig

GRPCClientConfig holds configuration for gRPC Client.

insecure

(bool, default: false)

Disable ClientTLS

min_connection_timeout

(string, default: "20s")

Minimum connection timeout

use_proxy

(bool, default: false)

Use HTTP CONNECT Proxy

backoff

(BackoffConfig)

Backoff configuration

tls

(ClientTLSConfig)

Client TLS configuration

---

GRPCGatewayConfig

GRPCGatewayConfig holds configuration for gRPC to HTTP gateway

grpc_server_address

(string, format: empty | hostname_port)

gRPC server address to connect to - By default it points to HTTP server port because FluxNinja stack runs gRPC and HTTP servers on the same port

---

GRPCServerConfig

GRPCServerConfig holds configuration for gRPC Server.

connection_timeout

(string, default: "120s")

Connection timeout

enable_reflection

(bool, default: false)

Enable Reflection

latency_buckets_ms

([]float64, default: [10,25,100,250,1000])

Buckets specification in latency histogram

---

HTTPClientConfig

HTTPClientConfig holds configuration for HTTP Client.

disable_compression

(bool, default: false)

Disable Compression

disable_keep_alives

(bool, default: false)

Disable HTTP Keepalive

expect_continue_timeout

(string, default: "1s")

Expect Continue Timeout. 0 = no timeout.

idle_connection_timeout

(string, default: "90s")

Idle Connection Timeout. 0 = no timeout.

key_log_file

(string)

SSL/TLS key log file (useful for debugging)

max_conns_per_host

(int64, minimum: 0, default: 0)

Max Connections Per Host. 0 = no limit.

max_idle_connections

(int64, minimum: 0, default: 100)

Max Idle Connections. 0 = no limit.

max_idle_connections_per_host

(int64, minimum: 0, default: 5)

Max Idle Connections per host. 0 = no limit.

max_response_header_bytes

(int64, minimum: 0, default: 0)

Max Response Header Bytes. 0 = no limit.

network_keep_alive

(string, default: "30s")

Network level keep-alive duration

network_timeout

(string, default: "30s")

Timeout for making network connection

read_buffer_size

(int64, minimum: 0, default: 0)

Read Buffer Size. 0 = 4 KB

response_header_timeout

(string, default: "0s")

Response Header Timeout. 0 = no timeout.

tls_handshake_timeout

(string, default: "10s")

TLS Handshake Timeout. 0 = no timeout

timeout

(string, default: "60s")

HTTP client timeout - Timeouts include connection time, redirects, reading the response and so on. 0 = no timeout.

use_proxy

(bool, default: false)

Use Proxy

write_buffer_size

(int64, minimum: 0, default: 0)

Write Buffer Size. 0 = 4 KB.

proxy_connect_header

(Header)

Proxy Connect Header - map[string][]string

tls

(ClientTLSConfig)

Client TLS configuration

---

HTTPServerConfig

HTTPServerConfig holds configuration for HTTP Server.

disable_http_keep_alives

(bool, default: false)

Disable HTTP Keepalive

idle_timeout

(string, default: "30s")

Idle timeout

latency_buckets_ms

([]float64, default: [10,25,100,250,1000])

Buckets specification in latency histogram

max_header_bytes

(int64, minimum: 0, default: 1048576)

Max header size in bytes

read_header_timeout

(string, default: "10s")

Read header timeout

read_timeout

(string, default: "10s")

Read timeout

write_timeout

(string, default: "45s")

Write timeout

---

Header

A Header represents the key-value pairs in an HTTP header.

The keys should be in canonical form, as returned by CanonicalHeaderKey.

Header

---

HeapConfig

HeapConfig holds configuration for heap Watchdog.

limit

(uint64, minimum: 0)

Maximum memory (in bytes) sets limit of process usage. Default = 256MB.

min_gogc

(int64, minimum: 0, maximum: 100, default: 25)

Minimum GoGC sets the minimum garbage collection target percentage for heap driven Watchdogs. This setting helps avoid over scheduling.

adaptive_policy

(AdaptivePolicy)

watermarks_policy

(WatermarksPolicy)

---

JobConfig

JobConfig is configuration for a periodic job

execution_period

(string, default: "10s")

Time between job executions. Zero or negative value means that the job will never run periodically.

execution_timeout

(string, default: "5s")

Execution timeout

initially_healthy

(bool, default: false)

Sets whether the job is initially healthy

---

JobGroupConfig

JobGroupConfig holds configuration for JobGroup.

blocking_execution

(bool, default: false)

When true, the scheduler will run jobs synchronously, waiting for each execution instance of the job to return before starting the next execution. Running with this option effectively serializes all job execution.

worker_limit

(int64, default: 0)

Limits how many jobs can be running at the same time. This is useful when running resource intensive jobs and a precise start time is not critical. 0 = no limit. If BlockingExecution is set, then WorkerLimit is ignored.

---

ListenerConfig

ListenerConfig holds configuration for socket listeners.

addr

(string, format: hostname_port, default: ":8080")

Address to bind to in the form of [host%zone]:port

keep_alive

(string, default: "180s")

Keep-alive period - 0 = enabled if supported by protocol or operating system. If negative, then keep-alive is disabled.

network

(string, format: empty | empty, one of: tcp | tcp4 | tcp6, default: "tcp")

TCP networks - tcp, tcp4 (IPv4-only), tcp6 (IPv6-only)

---

LogConfig

LogConfig holds configuration for a logger and log writers.

level

(string, format: empty | empty, one of: debug | DEBUG | info | INFO | warn | WARN | error | ERROR | fatal | FATAL | panic | PANIC | trace | TRACE | disabled | DISABLED, default: "info")

Log level

non_blocking

(bool, default: true)

Use non-blocking log writer (can lose logs at high throughput)

pretty_console

(bool, default: false)

Additional log writer: pretty console (stdout) logging (not recommended for prod environments)

writers

([]LogWriterConfig)

Log writers

---

LogWriterConfig

LogWriterConfig holds configuration for a log writer.

compress

(bool, default: false)

Compress

file

(string, default: "stderr")

Output file for logs. Keywords allowed - [stderr, default]. default maps to /var/log/fluxninja/<service>.log

max_age

(int64, minimum: 0, default: 7)

Max age in days for log files

max_backups

(int64, minimum: 0, default: 3)

Max log file backups

max_size

(int64, minimum: 0, default: 50)

Log file max size in MB

---

MetricsConfig

MetricsConfig holds configuration for service metrics.

enable_go_metrics

(bool, default: false)

EnableGoCollector controls whether the go collector is registered on startup. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector

enable_process_collector

(bool, default: false)

EnableProcessCollector controls whether the process collector is registered on startup. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector

pedantic

(bool, default: false)

Pedantic controls whether a pedantic registry is used. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewPedanticRegistry

---

PortsConfig

PortsConfig defines configuration for OTel debug and extension ports.

debug_port

(uint32, minimum: 0)

Port on which OTel collector exposes Prometheus metrics on /metrics path.

health_check_port

(uint32, minimum: 0)

Port on which health check extension in exposed.

pprof_port

(uint32, minimum: 0)

Port on which pprof extension in exposed.

zpages_port

(uint32, minimum: 0)

Port on which zpages extension in exposed.

---

ProfilersConfig

ProfilersConfig holds configuration for profilers.

cpu_profiler

(bool, default: false)

Flag to enable CPU profiling on process start and save it to a file. The Browser (HTTP) interface won't work if this is enabled, as the CPU profile will always be running.

profiles_path

(string, default: "default")

Path to save performance profiles. "default" path is /var/log/aperture/<service>/profiles.

register_http_routes

(bool, default: true)

Register routes. Profile types profile, symbol and cmdline will be registered at /debug/pprof/{profile,symbol,cmdline}.

---

PrometheusConfig

PrometheusConfig holds configuration for Prometheus Server.

address

(string, format: empty | hostname_port | url | fqdn | empty)

Address of the Prometheus server

labels

([]PrometheusLabel)

A list of labels to be attached to every query

---

PrometheusLabel

PrometheusLabel holds Name->Value mapping for the label that will be attached to every PromQL query executed by the controller.

name

(string)

value

(string)

---

ProxyConfig

ProxyConfig holds proxy configuration.

This configuration has preference over environment variables HTTP_PROXY, HTTPS_PROXY or NO_PROXY. See https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config

http

(string, format: empty | url | hostname_port)

https

(string, format: empty | url | hostname_port)

no_proxy

([]string)

---

SentryConfig

SentryConfig holds configuration for Sentry.

attach_stack_trace

(bool, default: true)

Configure to generate and attach stack traces to capturing message calls

debug

(bool, default: true)

Debug enables printing of Sentry SDK debug messages

disabled

(bool, default: false)

Sentry crash report disabled

dsn

(string, default: "https://6223f112b0ac4344aa67e94d1631eb85@o574197.ingest.sentry.io/6605877")

If DSN is not set, the client is effectively disabled You can set test project's DSN to send log events. oss-aperture project DSN is set as default.

environment

(string, default: "production")

Environment

sample_rate

(float64, minimum: 0, maximum: 1, default: 1)

Sample rate for event submission

traces_sample_rate

(float64, minimum: 0, maximum: 1, default: 0.2)

Sample rate for sampling traces

---

ServerTLSConfig

ServerTLSConfig holds configuration for setting up server TLS support.

allowed_cn

(string, format: empty | fqdn)

Allowed CN

cert_file

(string)

Server Cert file path

client_ca_file

(string)

Client CA file path

enabled

(bool, default: false)

Enabled TLS

key_file

(string)

Server Key file path

---

WatchdogConfig

WatchdogConfig holds configuration for Watchdog Policy. For each policy, either watermark or adaptive should be configured.

cgroup

(WatchdogPolicyType)

heap

(HeapConfig)

job

(JobConfig)

system

(WatchdogPolicyType)

---

WatchdogPolicyType

WatchdogPolicyType holds configuration Watchdog Policy algorithms. If both algorithms are configured then only watermark algorithm is used.

adaptive_policy

(AdaptivePolicy)

watermarks_policy

(WatermarksPolicy)

---

WatermarksPolicy

WatermarksPolicy creates a Watchdog policy that schedules GC at concrete watermarks.

enabled

(bool, default: false)

Flag to enable the policy

watermarks

([]float64, default: [0.5,0.75,0.8,0.85,0.9,0.95,0.99])

Watermarks are increasing limits on which to trigger GC. Watchdog disarms when the last watermark is surpassed. It's recommended to set an extreme watermark for the last element (for example, 0.99).

---