Environment Files

Environment files define Director topology, clustering, and access control for self-managed deployments. Located in config/environments/. Files containing .example. or .sample. in their name are templates only and are not loaded by the system.

For the vmetric.yml service settings that accompany these files, see Service Configuration.

Standalone Director

Minimal configuration for a single Director instance. The node name must match the director.id from vmetric.yml.

environments:
  - name: "1"
    status: true
    nodes:
      - name: "1"
        status: true

Pairs with the minimal vmetric.yml under Minimal Standalone Director in Service Configuration.

Clustered Director

Clustered configurations define a cluster with multiple nodes for high availability. See Clusters for operational details.

cluster: "{cluster-id}"
environments:
  - name: "{cluster-id}"
    description: "Production Cluster"
    status: true
    clusters:
      - name: "{cluster-id}"
        description: "Primary Cluster"
        status: true
        type: director
        properties:
          address: "10.0.0.1"
          port: 6222
          authentication:
            username: ""
            password: ""
            token: ""
          tls:
            status: false
            cert_name: "cert.pem"
            key_name: "key.pem"
            ca_name: ""
            verify: false
        nodes:
          - name: "{node-1-id}"
            status: true
            properties:
              address: "10.0.0.1"
              port: 4222
              cluster:
                address: "10.0.0.1"
                port: 6222
                authentication:
                  token: ""
                tls:
                  status: false

Three-Node HA Cluster with VIP

A complete production cluster file: three nodes, token-authenticated and TLS-secured inter-node links, cluster-level ACL, VIP failover, and a scheduled update window.

config/environments/cluster.yml:

cluster: "prod-cluster"
environments:
  - name: "prod-cluster"
    description: "Production HA Cluster"
    status: true
    clusters:
      - name: "prod-cluster"
        description: "3-node director cluster"
        status: true
        type: director
        properties:
          address: "10.0.1.101"
          port: 6222
          authentication:
            token: "cluster-secret-token"
          tls:
            status: true
            cert_name: "cluster-cert.pem"
            key_name: "cluster-key.pem"
            ca_name: "ca.pem"
            verify: true
          acl:
            allowed_ips:
              - "10.0.0.0/16"
            allowed_tokens:
              - "api-token-xyz"
            rate_limit_max_requests: 500
            rate_limit_window: 60
          vip:
            use_vip: true
            bind_vip: true
            vip_address: "10.0.1.100"
            vip_netmask: "255.255.255.0"
            vip_gateway: "10.0.1.1"
            vip_interface: "eth0"
            vip_monitor_interval: 5
            is_nats_cluster: true
          update:
            mode: auto
            method: cron
            cron: "0 3 * * 0"
            version: "latest"
        nodes:
          - name: "1"
            description: "Node 1 - 10.0.1.101"
            status: true
            properties:
              address: "10.0.1.101"
              port: 4222
              cluster:
                address: "10.0.1.101"
                port: 6222
                authentication:
                  token: "cluster-secret-token"
                tls:
                  status: true
                  cert_name: "cluster-cert.pem"
                  key_name: "cluster-key.pem"
                  ca_name: "ca.pem"
                  verify: true
          - name: "2"
            description: "Node 2 - 10.0.1.102"
            status: true
            properties:
              address: "10.0.1.102"
              port: 4222
              cluster:
                address: "10.0.1.102"
                port: 6222
                authentication:
                  token: "cluster-secret-token"
                tls:
                  status: true
                  cert_name: "cluster-cert.pem"
                  key_name: "cluster-key.pem"
                  ca_name: "ca.pem"
                  verify: true
          - name: "3"
            description: "Node 3 - 10.0.1.103"
            status: true
            properties:
              address: "10.0.1.103"
              port: 4222
              cluster:
                address: "10.0.1.103"
                port: 6222
                authentication:
                  token: "cluster-secret-token"
                tls:
                  status: true
                  cert_name: "cluster-cert.pem"
                  key_name: "cluster-key.pem"
                  ca_name: "ca.pem"
                  verify: true

Pairs with the vmetric.yml under Three-Node HA Cluster in Service Configuration, which is identical on all three nodes apart from director.id.

ACL

ACL rules can be applied at the cluster or node level within environment files.

Field	YAML Path	Type	Default	Description
Allowed IPs	`acl.allowed_ips`	[]string	--	IP allowlist (individual IPs, ranges `"ip1 - ip2"`, or CIDR notation)
Access Tokens	`acl.allowed_tokens`	[]string	--	Valid access tokens for API authentication
Rate Limit Max	`acl.rate_limit_max_requests`	int	`100`	Maximum requests per rate limit window
Rate Limit Window	`acl.rate_limit_window`	int	`60`	Rate limit window in seconds
Update Interval	`acl.update_interval`	int	`20`	ACL configuration refresh interval in seconds

Production Standalone with ACL

A single-node environment file restricting API access to two subnets and a single host, with a token and a raised rate limit.

config/environments/env.yml:

environments:
  - name: "1"
    status: true
    nodes:
      - name: "1"
        status: true
        properties:
          acl:
            allowed_ips:
              - "10.0.0.0/24"
              - "192.168.1.50"
              - "172.16.0.1 - 172.16.0.254"
            access_tokens:
              - "prod-token-abc123"
            rate_limit_max_requests: 200
            rate_limit_window: 60

Pairs with the vmetric.yml under Production Standalone with ACL in Service Configuration.

TLS

TLS settings for inter-node and cluster communication.

Field	YAML Path	Type	Default	Description
Status	`tls.status`	bool	`false`	Enable TLS
Cert Name	`tls.cert_name`	string	`cert.pem`	TLS certificate filename
Key Name	`tls.key_name`	string	`key.pem`	TLS key filename
CA Name	`tls.ca_name`	string	--	CA certificate filename
Verify	`tls.verify`	bool	`false`	Enable certificate verification

Node Properties

Field	YAML Path	Type	Default	Description
Address	`properties.address`	string	--	Node bind address
Port	`properties.port`	int	`4222`	Node NATS port
Cluster Address	`properties.cluster.address`	string	--	Cluster communication address
Cluster Port	`properties.cluster.port`	int	`6222`	Cluster communication port

VIP (Virtual IP) Configuration

VIP enables high-availability failover for clustered Directors. Configured within cluster properties in the environment file. For a complete cluster file with VIP in place, see Three-Node HA Cluster with VIP.

Field	YAML Path	Type	Default	Description
Use VIP	`vip.use_vip`	bool	`false`	Enable VIP management
Bind VIP	`vip.bind_vip`	bool	`false`	Bind VIP on startup
VIP Address	`vip.vip_address`	string	--	Virtual IP address
VIP Netmask	`vip.vip_netmask`	string	--	VIP subnet mask
VIP Gateway	`vip.vip_gateway`	string	--	VIP gateway address
VIP Interface	`vip.vip_interface`	string	--	Network interface for VIP
VIP Monitor Interval	`vip.vip_monitor_interval`	int	--	Health check interval in seconds
Is NATS Cluster	`vip.is_nats_cluster`	bool	`false`	Whether this is a NATS cluster (affects VIP binding logic)

Standalone Director​

Clustered Director​

Three-Node HA Cluster with VIP​

ACL​

Production Standalone with ACL​

TLS​

Node Properties​

VIP (Virtual IP) Configuration​