config.example.yaml

# Lumina Controller Configuration Example
#
# This file shows all available configuration options for the Lumina controller.
# Copy this file to config.yaml and customize for your environment.

# AWS Accounts Configuration
# Define all AWS accounts that the controller should monitor for cost data.
# The controller will assume the specified IAM role in each account to collect
# EC2 instance, Reserved Instance, and Savings Plans data.
awsAccounts:
  # Production account example
  - accountId: "123456789012"
    name: "Production"
    assumeRoleArn: "arn:aws:iam::123456789012:role/lumina-controller"
    # region: "us-west-2"  # Optional: override default region for this account

  # Staging account example
  - accountId: "987654321098"
    name: "Staging"
    assumeRoleArn: "arn:aws:iam::987654321098:role/lumina-controller"

  # Additional accounts can be added as needed
  # Example: Account with custom region list (overrides global 'regions')
  # - accountId: "111111111111"
  #   name: "Development"
  #   assumeRoleArn: "arn:aws:iam::111111111111:role/lumina-controller"
  #   regions:
  #     - "us-west-2"  # This account only uses us-west-2

# Default Account Configuration (Optional)
# Specifies which AWS account to use for non-account-specific API calls
# such as AWS Pricing API. If not specified, the first account in awsAccounts
# will be used. This ensures all AWS API calls use assumed role credentials
# rather than the pod's service account credentials.
#
# defaultAccount:
#   accountId: "123456789012"
#   name: "Production"
#   assumeRoleArn: "arn:aws:iam::123456789012:role/lumina-controller"
#   region: "us-west-2"  # Optional: region for this account

# Default AWS region for API calls
# Can be overridden by LUMINA_DEFAULT_REGION environment variable
# Default: us-west-2
defaultRegion: "us-west-2"

# List of AWS regions to query for Reserved Instances
# RIs are regional resources, so each region must be queried separately
# Can be overridden per-account (see awsAccounts[].regions below)
# Default: ["us-west-2", "us-east-1"]
regions:
  - "us-west-2"
  - "us-east-1"
  # Add more regions as needed:
  # - "eu-west-1"
  # - "ap-southeast-1"

# Log level: debug, info, warn, error
# Can be overridden by LUMINA_LOG_LEVEL environment variable
# Default: info
logLevel: "info"

# Address for the metrics endpoint (Prometheus scraping)
# Can be overridden by LUMINA_METRICS_BIND_ADDRESS environment variable
# Default: :8080
metricsBindAddress: ":8080"

# Metrics Configuration (Optional)
# Controls metric emission behavior and label customization
metrics:
  # Disable per-instance metrics for multi-cluster deployments
  # When multiple Lumina instances report to a shared Prometheus endpoint,
  # set this to true on worker clusters to prevent metric duplication.
  # Only the management cluster should emit instance-level metrics.
  #
  # When true, disables:
  #   - ec2_instance
  #   - ec2_instance_count
  #   - ec2_instance_hourly_cost
  #
  # Always enabled (regardless of this setting):
  #   - Savings Plans metrics (utilization, commitment, etc.)
  #   - Reserved Instance metrics
  #   - Controller health and data freshness metrics
  #
  # Default: false (emit all metrics)
  disableInstanceMetrics: false

  # Customize metric label names (Optional)
  # Override default label names to match your organization's conventions
  # or avoid conflicts with external metric relabeling systems
  #
  # labels:
  #   # Kubernetes-related labels
  #   clusterName: "cluster_name"    # Default: cluster_name
  #   nodeName: "node_name"          # Default: node_name
  #   hostName: "host_name"          # Default: host_name
  #
  #   # AWS-related labels
  #   accountId: "account_id"        # Default: account_id
  #   accountName: "account_name"    # Default: account_name
  #   region: "region"               # Default: region
  #
  # Example: Use custom label names
  # labels:
  #   clusterName: "k8s_cluster"
  #   accountName: "aws_account"
  #   accountId: "aws_account_id"
  #   region: "aws_region"
  #   nodeName: "k8s_node"
  #   hostName: "ec2_hostname"

# Address for health probe endpoints (/healthz, /readyz)
# Can be overridden by LUMINA_HEALTH_PROBE_BIND_ADDRESS environment variable
# Default: :8081
healthProbeBindAddress: ":8081"

# How often to validate AWS account access
# Format: Go duration string (e.g., "5m", "10m", "1h")
# Can be overridden by LUMINA_ACCOUNT_VALIDATION_INTERVAL environment variable
# Default: 10m
accountValidationInterval: "10m"

# Reconciliation Configuration
# Controls how often different data sources are queried and refreshed
reconciliation:
  # RISP (Reserved Instances + Savings Plans) reconciliation interval
  # Format: Go duration string (e.g., "30m", "1h", "2h")
  # Default: 1h
  # Recommended: 1h - RI/SP data changes infrequently (purchases, expirations)
  risp: "1h"

  # EC2 instance inventory reconciliation interval
  # Format: Go duration string (e.g., "1m", "5m", "10m")
  # Default: 5m
  # Recommended: 5m - EC2 instances change frequently due to autoscaling
  ec2: "5m"

  # Pricing data reconciliation interval (on-demand pricing from AWS Pricing API)
  # Format: Go duration string (e.g., "12h", "24h", "48h")
  # Default: 24h
  # Recommended: 24h - AWS pricing changes monthly, daily refresh is sufficient
  pricing: "24h"

  # Spot pricing reconciliation interval
  # Controls how often to CHECK for stale spot prices
  # Format: Go duration string (e.g., "15s", "30s", "1m")
  # Default: 15s
  # Recommended: 15s - Fast checks are OK because lazy-loading means 0 API calls in steady-state
  #
  # NOTE: This works together with pricing.spotPriceCacheExpiration:
  #   - spotPricing: How often to CHECK for stale prices
  #   - spotPriceCacheExpiration: How old prices must be before considered stale
  spotPricing: "15s"

# Pricing Configuration
# Controls which pricing data to load and how to cache it
pricing:
  # Operating systems to load pricing data for
  # Valid values: "Linux", "Windows", "RHEL", "SUSE"
  # Default: ["Linux", "Windows"]
  # Example: ["Linux"] for Linux-only environments (faster, lower memory)
  operatingSystems:
    - "Linux"
    - "Windows"

  # Spot price cache expiration
  # Controls how old cached spot prices must be before being refreshed
  # Format: Go duration string (e.g., "30m", "1h", "2h")
  # Default: 1h
  # Recommended: 1h - AWS spot prices change hourly
  #
  # NOTE: This works together with reconciliation.spotPricing:
  #   - reconciliation.spotPricing: How often to CHECK (default: 15s)
  #   - spotPriceCacheExpiration: How old before stale (default: 1h)
  #
  # Example: With spotPriceCacheExpiration=1h and spotPricing=15s,
  # the reconciler checks every 15 seconds for prices older than 1 hour
  # and refreshes them.
  #
  # Tuning advice:
  #   - Tight budget → shorter expiration (more accurate, more API calls)
  #   - Loose budget → longer expiration (less accurate, fewer API calls)
  spotPriceCacheExpiration: "1h"

  # Default Savings Plan discount multipliers (fallback when API rates unavailable)
  # These are MULTIPLIERS (what you pay), not discount percentages
  # Formula: effectiveCost = onDemandPrice * multiplier
  #
  # Typical AWS Savings Plan rates:
  #   - 1-year commitment: ~28% OFF → you pay 72% → multiplier 0.72
  #   - 3-year commitment: ~50% OFF → you pay 50% → multiplier 0.50
  #
  # Default: 0.72 for both (1-year rates)
  # defaultDiscounts:
  #   ec2Instance: 0.72  # EC2 Instance Savings Plans
  #   compute: 0.72      # Compute Savings Plans

# IAM Role Requirements:
#
# Each AWS account must have an IAM role with the following permissions:
#
# {
#   "Version": "2012-10-17",
#   "Statement": [
#     {
#       "Effect": "Allow",
#       "Action": [
#         "ec2:DescribeInstances",
#         "ec2:DescribeReservedInstances",
#         "ec2:DescribeSpotPriceHistory",
#         "savingsplans:DescribeSavingsPlans",
#         "organizations:DescribeOrganization"
#       ],
#       "Resource": "*"
#     }
#   ]
# }
#
# Trust relationship:
#
# {
#   "Version": "2012-10-17",
#   "Statement": [
#     {
#       "Effect": "Allow",
#       "Principal": {
#         "AWS": "arn:aws:iam::<CONTROLLER_ACCOUNT_ID>:role/<CONTROLLER_ROLE_NAME>"
#       },
#       "Action": "sts:AssumeRole"
#     }
#   ]
# }