Environment Rules

Environment Rules allow you to dynamically assign agents to operational environments (e.g. Production, Staging, Development) by evaluating their reported attributes. This eliminates the need to manually tag individual servers.

---

1. Dynamic Categorization Workflow

When a Supervisor connects to CollectorCtrl, it transmits its system attributes (e.g. hostname, Kubernetes namespace, cloud region) in its OpAMP description payload. The server evaluates these attributes against your rules to assign the agent to an environment.

The Evaluation Pipeline

1. Handshake Trigger: During the initial agent registration, the server extracts all attributes.
2. Sequential Matching: Rules are evaluated in Priority order (lowest integer value first).
3. Environment Tagging: Once a matching rule is found, the evaluation stops, and the resolved environment is tagged on the agent model.
4. Target Matching: The assigned environment label is used by the Policy Engine to determine which configurations and rollout templates target the agent.

---

2. Rule Configuration Schema

Configure environment rules in the Settings > Environment Rules dashboard:

Setting Parameter	Description	Valid Options / Examples
Target Field	The specific metadata attribute key to evaluate.	hostname, service_name, k8s.pod.name, or custom resource attributes like cloud.availability_zone.
Match Operator	The string matching logic to apply.	equals, contains, starts_with, ends_with, or regex.
Match Value	The string pattern, substring, or regular expression to search for.	e.g. us-east-1 (contains), ^prod-web-.*$ (regex).
Assign Environment	The name of the environment tag applied to matching agents.	e.g. Production, Staging, QA.
Rule Priority	Evaluated lowest-number first (e.g. 10 runs before 50).	Any positive integer value.

---

3. Operations & API Reference

Administrative REST Endpoints

Retrieve Rules

• GET /api/system/env_rules
  Returns the complete list of environment rules, sorted by evaluation priority order.

Create or Update Rules

• POST /api/system/env_rules
  Creates a new rule or updates an existing rule in the database.

  Example request payload to route production web servers:

  {
    "field": "hostname",
    "operator": "regex",
    "value": "^prd-web-[0-9]+$",
    "environment": "Production",
    "priority": 10
  }
  

Delete Rules

• DELETE /api/system/env_rules/{id}
  Deletes the specified rule from the registry.

Audit Compliance

Creating, modifying, or deleting environment rules creates an audit record (e.g., Created Environment Rule routing hostname contains 'prod' to Production).