manager.yaml is the local configuration file used by a collector to define how it connects to its management server. It typically contains the endpoint, secret key, and agent ID. Those values give the collector identity and connectivity details needed for centralized management.
What manager.yaml does in a collector deployment
manager.yaml is the collector’s local control point for management-plane connectivity. It binds the collector to a specific server endpoint and includes the secret material and collector identifier needed for centralized administration, which is why its contents are operationally sensitive even though the file itself is simple.
Because this file defines where the collector phones home and how it is recognised, it sits at the intersection of connectivity, identity, and secret handling. If the file is wrong, stale, or exposed, the collector may fail to register correctly or may connect to the wrong management plane.
What belongs in the file and why it matters
The core fields are typically the endpoint, secret key, and agent ID. The endpoint tells the collector which server to contact, the secret key proves that the connection is authorised, and the agent ID lets the management service distinguish one collector from another.
Those values are not interchangeable. Changing the endpoint redirects management traffic, changing the secret key affects trust and authentication, and changing the agent ID can cause inventory confusion, duplicate registration, or an inability to match policy and telemetry to the right collector.
Because these values are local configuration rather than runtime guesses, they often end up in deployment artefacts, configuration management, or automation pipelines. That makes the file useful for orchestration, but it also means the file can become a durable record of sensitive connection details if it is not handled carefully.
For a broader non-human identity view of why local secret-bearing configuration is risky, see NHI Mgmt Group’s Ultimate Guide to NHIs.
How manager.yaml fits into identity, access, and lifecycle control
Although manager.yaml is just a configuration file, it participates in identity and access control because the collector uses it to authenticate to the management server and present its assigned identity. That means the file is part of the collector’s lifecycle, not merely a convenience setting.
This is why deployment, rotation, offboarding, and revocation matter. If a collector is decommissioned but the file or its secret remains valid, the management plane may still accept connections. If the secret is rotated without updating the file, the collector can lose access until the new value is distributed.
In practice, the file should be treated as identity-bearing configuration rather than ordinary metadata. The key lesson is that control-plane configuration, secret handling, and device identity are linked, so mismanaging one can break the others.
That lifecycle dependency is the same pattern described in NHI Lifecycle Management Guide and reinforced by Top 10 NHI Issues.
Security implications of storing the file locally
Local configuration is practical, but it concentrates risk. A manager.yaml file commonly contains secrets or secret-like material, so a leak can expose both the collector’s trust relationship and the management plane it can reach. In environment terms, this is the kind of file that belongs in a tight access boundary, not in broad developer or build-system visibility.
The biggest security concern is that the file often lives alongside other deployment artefacts, where it can be copied, committed, backed up, or surfaced in logs. NHIMG research shows that 96% of organisations store secrets outside of secrets managers in vulnerable locations including code, config files, and CI/CD tools, which is exactly the pattern that makes files like this attractive targets.
Excessive privilege can make the impact worse. If the collector account or management identity is over-privileged, compromise of the file can become a path to broader administrative access rather than a limited configuration issue.
Risk and Threat Considerations
Because manager.yaml often carries the secret and endpoint needed for management access, exposure of the file can turn into direct control-plane compromise. The main threat is not the filename itself, but the trusted connection it enables if an attacker obtains the file or can alter it before deployment.
Failure mechanism: If the file is stored insecurely, copied into build artefacts, or left readable to the wrong principals, an attacker can reuse the secret, impersonate the collector, or redirect management traffic to a malicious endpoint.
Impact: The result can be unauthorized enrollment, loss of fleet integrity, misattribution of telemetry, or broader access if the collector identity has excessive privilege.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
NIST CSF 2.0 and CIS Controls v8 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST CSF 2.0 | PR.AC — Access Control | manager.yaml governs collector access to a management server through secret-backed trust |
| PR.DS — Data Security | The file can hold secret material and endpoint details that need protection at rest | |
| GV.OV — Oversight | Collector configuration ties identity, connectivity, and lifecycle governance together | |
| Recommendation — Restrict access to the file and the collector trust path to approved principals only. Protect the file contents as sensitive data wherever they are stored or transferred. Assign ownership for collector configuration and review it as part of governance. | ||
| CIS Controls v8 | 6 — Access Control Management | The file conveys access to the management plane and should be tightly restricted |
| 3 — Data Protection | Secret keys in the file require protection against exposure in config and build paths | |
| 5 — Account Management | The agent ID and secret map the collector to a managed identity lifecycle | |
| Recommendation — Limit who can read, modify, and distribute manager.yaml. Store the file so secret values remain protected at rest and in transit. Revoke or rotate collector access when the associated identity is retired or changed. | ||
Practitioner Guidance
Why practitioners should care: Treat manager.yaml as sensitive operational material, not as a harmless text file. Its contents define trust, connectivity, and identity for the collector, so exposure or drift can break management and create a straightforward abuse path.
What to watch for: Pay attention to hardcoded secrets, stale endpoints, duplicate agent IDs, and collectors that keep working after offboarding events. Those are common signs that the file’s lifecycle is not being controlled with the same discipline as the system it manages.
Practitioner takeaway: The safest mental model is that manager.yaml is a compact trust artefact, not a configuration convenience.
