Configuration¶

Environment Variables¶

All configuration can be set via environment variables:

Variable	Default	Description
`SERVER_PORT`	8080	HTTP listen port
`SERVER_TOKEN`	(required)	Bearer token for API authentication
`CONFIG_PATH`	config.yaml	Path to configuration file
`DISCOVERY_TAG_KEY`	(empty)	OCI tag key to filter instances. When both `tag_key` and `tag_value` are empty, all running instances are returned without tag filtering.
`DISCOVERY_TAG_VALUE`	(empty)	OCI tag value to filter instances. When both `tag_key` and `tag_value` are empty, all running instances are returned without tag filtering.
`DISCOVERY_LINUX_PORT`	9100	Port for Linux node_exporter
`DISCOVERY_WINDOWS_PORT`	9182	Port for Windows exporter
`DISCOVERY_REFRESH_INTERVAL`	5m	How often to poll OCI APIs
`DISCOVERY_RATE_LIMIT_RPS`	10.0	OCI API rate limit (requests/sec per tenancy)

config.yaml¶

Main configuration file with OCI tenancy credentials:

server:
  port: 8080
  token: "use-SERVER_TOKEN-env-var"

discovery:
  # tag_key: monitoring
  # tag_value: enabled
  # Omit both tag_key and tag_value to discover all running instances
  linux_port: 9100
  windows_port: 9182
  refresh_interval: 5m
  rate_limit_rps: 10.0

tenancies:
  - name: my-tenancy
    region: me-jeddah-1
    tenancy_id: ocid1.tenancy.oc1..xxxxxx
    user_id: ocid1.user.oc1..xxxxxx
    fingerprint: "aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"
    private_key_path: /etc/oci-sd/keys/api_key.pem
    passphrase: ""
    compartments: []  # Empty = auto-discover all

Fields¶

server.port: HTTP port to listen on
server.token: Bearer token (prefer SERVER_TOKEN environment variable)
discovery.tag_key / tag_value: OCI freeform or defined tag for filtering instances (e.g., monitoring=enabled). Both fields are optional. When both are omitted (or empty), the proxy returns all running instances without tag filtering - useful for discovering everything in a region and relying on Prometheus relabel rules instead.
discovery.linux_port: Port for Linux Prometheus exporters (default: node_exporter on 9100)
discovery.windows_port: Port for Windows Prometheus exporters (default: windows_exporter on 9182)

Note

Windows OS detection - the proxy selects the port using this priority order:

OCI freeform tag os = windows on the instance (highest priority)
Instance display name contains win (e.g. win-server-01, windows-web)
Everything else defaults to linux_port (9100)

If a Windows VM has no os tag and no win in its display name, it will be targeted on port 9100. To avoid this, either set the freeform tag os = windows on the OCI instance, or ensure win appears in the VM display name.

When installing windows_exporter via the MSI installer, configure it to listen on port 9182 (the default). If you prefer port 9100 for Windows, set that in the MSI installer and update windows_port in this config to match.

discovery.refresh_interval

Background cache refresh interval (e.g., 5m, 30s)

discovery.rate_limit_rps

OCI API rate limit in requests per second per tenancy. Prevents 429 TooManyRequests errors by proactively throttling requests. Combined with automatic retry policy for transient failures. (default: 10.0)

tenancies[]

List of OCI tenancies to discover from

tenancies[].name

Friendly name (used in __meta_oci_tenancy_name label)

tenancies[].region

OCI region code (e.g., me-jeddah-1, us-ashburn-1)

tenancies[].tenancy_id

Tenancy OCID

tenancies[].auth_type

Authentication method. One of:

api_key (default) - static user credentials; requires user_id, fingerprint, and private_key_path
instance_principal - authenticates via OCI IMDS; no credential fields needed. Only valid when the proxy runs on an OCI compute instance with a dynamic group and IAM policy granting read access. See Installation for setup steps.

tenancies[].user_id

User OCID for API authentication. Required when auth_type is api_key.

tenancies[].fingerprint

API key fingerprint. Required when auth_type is api_key.

tenancies[].private_key_path

Path to unencrypted PEM private key. Required when auth_type is api_key.

tenancies[].passphrase

Passphrase for encrypted keys (leave empty for unencrypted). Only used with api_key auth.

tenancies[].compartments

List of compartment OCIDs to scan. Leave empty [] to auto-discover all compartments.