Documentation

High availability identifiers

High availability identifiers

Radiator includes lightweight instance and cluster identifiers designed to:

  • Distinguish production vs. test / source-of-config nodes
  • Provide stable labels for logging, metrics and (future) clustering / replication features
  • Enable operators to group instances into logical HA clusters prior to full active/active feature rollout

These identifiers are optional but recommended for multi-node or mixed test / production environments.

Overview

Two identifier families are recognised at startup (typically via command line arguments or environment variables mapped by your wrapper scripts):

| Identifier | Form | Typical examples | Scope | Purpose | |------------|------|------------------|-------|---------| | Instance ID | RNN where NN = 2 decimal digits | R00, R01, R02, R03 | Single server instance | Distinguish individual Radiator processes / nodes | | Cluster ID | CNN where NN = 2 decimal digits | C01, C02 | Logical HA cluster | Group instances for future cluster‑wide coordination |

Instance IDs (RNN)

  • R00 is reserved by operational convention for configuration source, test, staging or ephemeral nodes (not primary production traffic handlers). When R00 is used the startup log annotates it as (test instance id). This is the default value for instance id. There is no way to unset it.
  • R01, R02 usually denote the first two production nodes in a basic HA pair. Additional nodes (R03 .. R99) may be assigned if scaling horizontally.
  • Uniqueness: Each running instance within the same deployment environment SHOULD have a distinct RNN.
  • Persistence: Keep the same RNN for a node across restarts to simplify correlation in logs / metrics / external monitoring.

Cluster IDs (CNN)

  • Optional. Omit if you operate only a single cluster; metrics / logs then implicitly belong to that default cluster.
  • Define different CNN values (C01, C02, etc.) when you have segregated clusters (for example: geographic separation, blue/green environments, or phased migration testing).

Use cases

| Scenario | Recommended IDs | |----------|-----------------| | Two-node production pair | R01, R02 + shared C01 to prepare for possible future second cluster | | Test node feeding configs / experimentation | R00 (no cluster or C01) | | Blue/green pair (green preparing upgrade) | Blue: R01,R02 + C01; Green: R11,R12 + C02 | | Geo-distributed four nodes | Region A: R01,R02 + C01; Region B: R03,R04 + C02 |

Operational guidance

  • Expose instance / cluster IDs in monitoring dashboards
  • Treat these identifiers as stable—frequent renumbering reduces their value for historical analysis.

Logging & metrics

Where configured, the instance and cluster identifiers appear as labels or structured log fields. Metrics and scraping APIs pick these up automatically.

Environment variables / CLI flags

Exact names implemented in loikka/src/args.rs:

| Purpose | CLI flag | Environment variable | Precedence & fallback | |---------|----------|----------------------|-----------------------| | Instance ID | --instance-id <VALUE> | RADIATOR_INSTANCE_ID | CLI flag > env var > default R00 | | Cluster ID | --cluster-id <VALUE> | RADIATOR_CLUSTER_ID | CLI flag > env var > unset |

Values are accepted if every character is ASCII alphanumeric ([0-9A-Za-z]+). Invalid or empty values are ignored silently. This does mean that any naming convention can be used to unify with operations standards.

Visibility of settings

Startup log lines will include instance and cluster (if set) IDs:

main INFO High availability identifiers: cluster='C01' instance='R00' (test instance id)

Metrics are exposed over API and Prometheus (see Prometheus scraping for full metric names and label sets).

Constraints & validation

Current code validation (present behaviour):

  • Any non-empty ASCII alphanumeric string is considered valid; no enforced prefix / length.
  • Default instance ID = R00 when omitted or invalid.
  • Cluster ID stays unset if omitted or invalid.

Recommended operational convention (adopt now to ease future stricter validation):

  • Instance IDs: RNN (capital R + two digits) starting at R01; reserve R00 for test / config / staging.
  • Cluster IDs: CNN (capital C + two digits) starting at C01.
  • Keep IDs stable over time for auditability.

Avoid using R00 for production traffic unless necessary.