Reference on Veneer

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Veneer is configured via YAML file, environment variables, or CLI flags. For Helm-based deployments, configuration values are passed through the config section of the Helm chart values. Configuration precedence (highest to lowest):

CLI flags
Environment variables (VENEER_* prefix)
Configuration file values
Default values

Configuration File

Create a config.yaml (or use config.example.yaml as a starting point):

# Prometheus URL for querying Lumina metrics
prometheusUrl: "http://prometheus:9090"

# Log level: debug, info, warn, or error
logLevel: "info"

# Metrics endpoint bind address
metricsBindAddress: ":8080"

# Health probe endpoint bind address
healthProbeBindAddress: ":8081"

# AWS configuration (REQUIRED)
aws:
 accountId: "123456789012"
 region: "us-west-2"

# Overlay management configuration
overlays:
 # Disabled mode: overlays created but won't match nodes
 disabled: false

 # Utilization threshold for overlay deletion (0-100)
 utilizationThreshold: 95.0

 # Overlay priority weights
 weights:
 reservedInstance: 30
 ec2InstanceSavingsPlan: 20
 computeSavingsPlan: 10

 # Overlay naming prefixes
 naming:
 reservedInstancePrefix: "cost-aware-ri"
 ec2InstanceSavingsPlanPrefix: "cost-aware-ec2-sp"
 computeSavingsPlanPrefix: "cost-aware-compute-sp"

# Instance preference configuration
preferences:
 enabled: true

All Configuration Options

Core Settings

Option	YAML Key	Env Variable	Default	Description
Prometheus URL	`prometheusUrl`	`VENEER_PROMETHEUS_URL`	`http://prometheus:9090`	URL of the Prometheus server for Lumina metrics
Log Level	`logLevel`	`VENEER_LOG_LEVEL`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
Metrics Bind Address	`metricsBindAddress`	`VENEER_METRICS_BIND_ADDRESS`	`:8080`	Address for the Prometheus metrics endpoint
Health Probe Bind Address	`healthProbeBindAddress`	`VENEER_HEALTH_PROBE_BIND_ADDRESS`	`:8081`	Address for health and readiness probes

AWS Settings (Required)

Option	YAML Key	Env Variable	Default	Description
Account ID	`aws.accountId`	`VENEER_AWS_ACCOUNT_ID`	(none)	12-digit AWS account ID where this cluster runs
Region	`aws.region`	`VENEER_AWS_REGION`	(none)	AWS region where this cluster runs

Both aws.accountId and aws.region are required. Veneer uses them to scope Prometheus queries to only return RI/SP data from this specific account and region.

Metrics

Mon, 01 Jan 0001 00:00:00 +0000

Veneer exposes Prometheus metrics on the metrics endpoint (default :8080/metrics, configurable via metricsBindAddress). All metrics use the veneer_ namespace prefix.

Veneer intentionally does not duplicate Lumina metrics (which are already in Prometheus). Instead, it focuses on what Veneer decided and what actions it took.

Metrics at a Glance

Metric	Type	Description
`veneer_reconciliation_duration_seconds`	Histogram	Duration of reconciliation cycles
`veneer_reconciliation_total`	Counter	Total reconciliation cycles
`veneer_lumina_data_freshness_seconds`	Gauge	Age of Lumina data
`veneer_lumina_data_available`	Gauge	Whether Lumina data is fresh
`veneer_decision_total`	Counter	Decisions made by the engine
`veneer_reserved_instance_data_available`	Gauge	Whether RI metrics are available
`veneer_reserved_instance_count`	Gauge	RI count by type and region
`veneer_savings_plan_utilization_percent`	Gauge	SP utilization percentage
`veneer_savings_plan_remaining_capacity_dollars`	Gauge	SP remaining capacity ($/hr)
`veneer_overlay_operations_total`	Counter	Total overlay operations
`veneer_overlay_operation_errors_total`	Counter	Total overlay operation errors
`veneer_overlay_count`	Gauge	Current overlay count
`veneer_prometheus_query_duration_seconds`	Histogram	Prometheus query duration
`veneer_prometheus_query_errors_total`	Counter	Prometheus query errors
`veneer_prometheus_query_result_count`	Gauge	Prometheus query result count
`veneer_config_overlays_disabled`	Gauge	Whether overlays are disabled
`veneer_config_utilization_threshold_percent`	Gauge	Configured utilization threshold
`veneer_info`	Gauge	Controller version info

Reconciliation Metrics

Metric	Type	Labels	Description
`veneer_reconciliation_duration_seconds`	Histogram	–	Duration of metrics reconciliation cycles. Buckets: 0.1s to ~51s (exponential).
`veneer_reconciliation_total`	Counter	`result`	Total number of reconciliation cycles. Labels: `result=success\|error`.

Data Source Health Metrics

Metric	Type	Labels	Description
`veneer_lumina_data_freshness_seconds`	Gauge	–	Age of Lumina data in seconds.
`veneer_lumina_data_available`	Gauge	–	`1` if Lumina data is available and fresh, `0` if stale or unavailable.

Decision Metrics

Metric	Type	Labels	Description
`veneer_decision_total`	Counter	`capacity_type`, `should_exist`, `reason`	Total decisions made by the decision engine.

Label values for veneer_decision_total:

Helm Chart

Mon, 01 Jan 0001 00:00:00 +0000

The Veneer Helm chart deploys the controller to a Kubernetes cluster. This page documents all available Helm values.

Installation

helm install veneer veneer/veneer \
 --namespace veneer-system \
 --create-namespace \
 -f values.yaml

Values Reference

Replica and Image

Value	Default	Description
`replicaCount`	`2`	Number of controller replicas (leader election handles HA)
`image.repository`	`ghcr.io/nextdoor/veneer`	Container image repository
`image.pullPolicy`	`IfNotPresent`	Image pull policy
`image.tag`	`""`	Image tag (defaults to chart `appVersion`)
`imagePullSecrets`	`[]`	Image pull secrets for private registries

Naming

Value	Default	Description
`nameOverride`	`""`	Override the name of the chart
`fullnameOverride`	`""`	Override the full name of the release

Service Account

Value	Default	Description
`serviceAccount.create`	`true`	Create a service account
`serviceAccount.automount`	`true`	Automatically mount API credentials
`serviceAccount.annotations`	`{}`	Annotations (e.g., `eks.amazonaws.com/role-arn` for IRSA)
`serviceAccount.name`	`""`	Service account name (auto-generated if empty)

Pod Configuration

Value	Default	Description
`podAnnotations`	`{}`	Annotations to add to the pod
`podLabels`	`{}`	Labels to add to the pod

Security Context

The chart enforces a restrictive security posture by default:

NodeOverlay CRD

Mon, 01 Jan 0001 00:00:00 +0000

NodeOverlay is a Karpenter custom resource (karpenter.sh/v1alpha1) that allows adjusting instance type pricing used during provisioning. Veneer creates and manages NodeOverlay resources to influence which instances Karpenter selects.

API Definition

apiVersion: karpenter.sh/v1alpha1
kind: NodeOverlay
metadata:
 name: <overlay-name>
 labels:
 app.kubernetes.io/managed-by: veneer
 veneer.io/type: <cost-aware|preference>
 veneer.io/source-nodepool: <nodepool-name>  # For preference overlays
spec:
 # Requirements that an instance must match for this overlay to apply
 requirements:
 - key: <label-key>
 operator: <In|NotIn|Gt|Lt|Exists|DoesNotExist>
 values: [<value1>, <value2>, ...]

 # Price adjustment (percentage string)
 priceAdjustment: "<adjustment>"

 # Weight for overlay precedence (higher = higher priority)
 weight: <integer>

Spec Fields

`spec.requirements`

A list of node selector requirements that an instance type must match for this overlay’s price adjustment to apply. Uses the same requirement format as Karpenter NodePool requirements.