cloud-ip-validator/configs/control-api.example.yaml

# Control API configuration.
#
# OpenStack credentials are never set here — only the *names* of the
# environment variables to read them from. The actual values must be
# supplied by the process environment (see deploy/systemd/control-api.service
# and its EnvironmentFile=).

server:
  listen_addr: ":8080"

database:
  path: "/var/lib/cloud-ip-validator/control-api.db"

openstack:
  mode: "real"                    # "mock" | "real" — mock uses an in-memory
                                   # OpenStack stand-in for local dev/testing
  auth_method: "token"            # "token" (default) | "password" — see below

  auth_url_env: "OS_AUTH_URL"
  project_id_env: "OS_PROJECT_ID"
  region_env: "OS_REGION_NAME"
  interface_env: "OS_INTERFACE"   # optional; empty env value defaults to "public"

  # auth_method: "token" — an admin supplies an already project-scoped
  # token directly; it's used as-is for every call, never exchanged for a
  # new one. Simplest option, but it can't renew itself: when the token
  # expires, control-api starts failing OpenStack calls until the operator
  # reissues OS_TOKEN and restarts the process.
  token_env: "OS_TOKEN"

  # auth_method: "password" — the client authenticates with a normal
  # Keystone username/password and automatically re-authenticates
  # (mints a fresh token) whenever the current one is rejected, for as
  # long as the process runs. Trade-off: a long-lived password credential
  # sits in the environment file instead of a token.
  username_env: "OS_USERNAME"
  user_domain_name_env: "OS_USER_DOMAIN_NAME"
  password_env: "OS_PASSWORD"

orchestrator:
  poll_interval_seconds: 5
  self_check_timeout_seconds: 60
  max_self_check_retries: 3
  checking_window_seconds: 120
  max_retries: 3
  lease_ttl_seconds: 180
  heartbeat_timeout_seconds: 30
  # Pause (seconds) between FIP association and the start of self-check —
  # gives the OpenStack data plane time to start forwarding traffic
  # through the newly attached floating IP. 0 = no pause (default).
  # This is only the one-time seed value used the first time control-api
  # starts against an empty database; after that it's managed at runtime
  # via PUT /api/v1/admin/config/orchestrator (or the dashboard's
  # /settings page) and this field is ignored. Must satisfy
  # fip_settle_seconds + self_check_timeout_seconds < lease_ttl_seconds.
  fip_settle_seconds: 0

aggregation:
  missing_counts_as_fail: true

# Validators are VMs in the service project; os_port_id is the Neutron port
# ID of each validator's primary NIC, used when associating a floating IP.
validators:
  - validator_id: "validator_01"
    os_port_id: "REPLACE_WITH_NEUTRON_PORT_ID_1"
  - validator_id: "validator_02"
    os_port_id: "REPLACE_WITH_NEUTRON_PORT_ID_2"

# Inbound (prober) checks are OPTIONAL: list here only the external sites
# you actually run a `prober` on, up to 3 slots (index 1-3, matches
# ip_queue.siteN_complete — the schema is capped at 3). Leave this list
# empty to disable inbound checks entirely — the overall result is then
# based on egress checks alone, and aggregation doesn't wait on any
# prober. A partial list (e.g. just index 1) only waits on that one site.
sites:
  - site_id: "site-1"
    index: 1
  - site_id: "site-2"
    index: 2
  - site_id: "site-3"
    index: 3

# Outbound/egress check types the validator-agent runs, and which target
# group (below) each runs against.
check_types:
  - name: "https"
    enabled: true
    targets: ["default-targets"]
  - name: "icmp"
    enabled: true
    targets: ["default-targets"]
  - name: "ssh"
    enabled: false
    targets: []

targets:
  default-targets:
    - "https://hub.docker.com"
    - "https://github.com"
    - "https://packages.ubuntu.com"

# Inbound checks the 3 external-site probers run directly against each
# validator's currently-assigned floating IP. Like validators/sites/targets/
# check_types above, this is only a bootstrap seed for a fresh, empty
# database; after that it's managed at runtime via PUT
# /api/v1/admin/config/inbound-checks (or the dashboard's /settings page)
# and this field is ignored.
inbound_checks:
  ports: [22, 80, 443, 8080]
  icmp: true

# The pool of public IPv4 addresses to validate, in the order they'll be
# processed (ip_queue.sequence). Every address here is checked through to
# the end of the list.
ip_addresses:
  - "203.0.113.10"
  - "203.0.113.11"
  - "203.0.113.12"