Variables Registry

CloudGrange configuration has two layers, and they are different things:

  • Platform configuration registry — typed, scoped variables served by the API and edited in the portal's Config Registry. These control platform and module behavior.
  • Component environment variables — process-level settings for the runtime agent and relay, set at install/deploy time.

CloudGrange is in preview, not GA. The surface below reflects current preview code and may change during the preview. See current product and release status.

Platform configuration registry

The registry is a set of named variables owned by the platform or by individual modules. Each variable has a schema: a key, an optional description, a grouping, an owning module, and a flag marking whether its value is secret. Values are set against a scope (for example an organization or site); a value set directly at a scope is an override, while a value that only comes from the schema default is inherited.

The Config Registry page in the portal shows each variable with its effective value, whether it is an override, its source (scope or inherited), and its description.

Registry API

Reading and writing the registry is permission-checked. Reading variables and values requires config:read; writing a value requires the corresponding write permission.

Route Description
GET /api/v1/config/variables List registered variables (optional ?module= filter).
GET /api/v1/config/values/{scopeId} Every variable joined with its value at a scope.
GET /api/v1/config/values/{scopeId}/{key} Get one value at a scope.
PUT /api/v1/config/values/{scopeId}/{key} Set (override) a value at a scope.
DELETE /api/v1/config/values/{scopeId}/{key} Remove an override, reverting to inherited/default.
GET /api/v1/config/snapshot/{scopeId} Full configuration snapshot for a scope.

Secret variables are stored through the platform secrets subsystem; their values are never returned in list responses.

Runtime agent environment variables

The agent is a Windows service on each Hyper-V host, configured by environment variables (set by Install-Agent.ps1 or service configuration).

Variable Description
AGENT_RELAY_URL Base URL of the relay the agent enrolls with and polls.
AGENT_ENROLLMENT_TOKEN One-time token used to enroll with the relay.
AGENT_CLUSTER_ID Cluster the host belongs to.
AGENT_IDENTITY_PATH Path to the agent's persisted identity file.
AGENT_INSTALL_DIRECTORY Installation root; ACL-hardened to SYSTEM + Administrators.
AGENT_SCAN_INTERVAL_SECONDS Interval between local inventory scans.
AGENT_UPDATE_ALLOWED_HOSTS Hosts the agent self-updater will trust.
AGENT_MTLS_CERT_THUMBPRINT Client certificate thumbprint for mTLS (planned transport security).
AGENT_BMC_CERT_PATH Certificate for baseboard management controller (BMC/Redfish) connections.
AGENT_SECRET_* Prefixed secrets (for example AGENT_SECRET_BMC_IPMI_HOST) supplied to jobs; redacted from all health/diagnostic output.

Relay environment variables

The relay is a per-site workload that routes jobs from the control plane to enrolled agents. It is configured by environment variables — set through the chart's relay.env values on the Kubernetes/Helm paths, or in its Compose service definition on the legacy engine.

Variable Description
RELAY_PAAS_URL Upstream control-plane URL the relay connects to.
RELAY_ENROLLMENT_TOKEN Token the relay uses to enroll itself with the control plane.
RELAY_AGENT_ENROLLMENT_TOKEN Shared token agents present on first enrollment.
RELAY_ADMIN_TOKEN Admin token required to approve re-enrollment of an already-enrolled host.
RELAY_CLUSTER_ID / RELAY_SITE_ID Cluster and site the relay serves.
RELAY_DISPLAY_NAME Friendly name shown in the portal.
RELAY_LISTEN_PORT Port the relay listens on for agent (LAN) routes.
RELAY_IDENTITY_DIR Directory holding the relay's persisted identity.
RELAY_HYPER_V_HOSTS Hyper-V hosts the relay scans for inventory.
RELAY_PSREMOTE_USERNAME / RELAY_PSREMOTE_PASSWORD Credentials for WinRM/PSRemoting to hosts.
RELAY_PSREMOTE_TRANSPORT PSRemoting transport (for example HTTPS).
RELAY_HEALTH_* Health thresholds: AGENT_STALE_SECONDS, MIN_FREE_BYTES, MIN_FREE_PERCENT, QUEUE_DEPTH_THRESHOLD, QUEUE_AGE_THRESHOLD_SECONDS, RECEIPT_LAG_THRESHOLD, RECEIPT_AGE_THRESHOLD_SECONDS, UPSTREAM_PUSH_ENABLED.

Security note: several relay/agent settings are secrets (tokens, PSRemoting credentials). Supply them through a secret store or protected environment, never in committed files. The agent redacts AGENT_SECRET_* and the enrollment token from diagnostics; the relay rejects jobs for unenrolled hosts and requires admin approval for re-enrollment.

See current product and release status.