Teams should update the collector’s management configuration rather than replacing the installation when they need to preserve an existing version. The usual approach is to create a manager.yaml file with the server endpoint, secret key, and agent ID, then restart the collector so it registers with the management plane and begins reporting as a managed agent.
What changes when an existing collector is managed instead of replaced
The key distinction is operational, not architectural: the collector binary stays in place, but its control relationship changes. Teams update the management configuration so the existing instance can enroll with the management plane, retain its current version, and start being governed as a managed agent after restart.
This is the safer path when reinstalling would create avoidable drift or interrupt a known-good deployment. It also preserves the local runtime state long enough to confirm the management endpoint, agent identity, and secret material are correct before the collector begins reporting centrally. For broader lifecycle and ownership context, see the NHI Lifecycle Management Guide and Top 10 NHI Issues.
A practical way to think about this is that the management plane needs enough configuration to recognise the collector as the same runtime, not a new installation. That is why a manager.yaml file with the server endpoint, secret key, and agent ID is typically the smallest required change set. Once restarted, the collector can register cleanly without re-provisioning the whole host or losing continuity in observability data.
What teams need to verify before restarting the collector
The main failure mode is treating enrollment as a simple file edit when it is actually an access and registration change. If the endpoint is wrong, the secret is stale, or the agent ID is duplicated, the collector may restart but never become a trusted managed node. Because the collector is now tied to a control plane, configuration accuracy directly affects visibility and operational trust.
Failure mechanism: The collector starts with incomplete or incorrect management values, so it cannot authenticate or register with the management plane. In practice, that produces a live process that is still effectively unmanaged, which can be mistaken for successful onboarding.
Impact: Teams lose central control and may assume telemetry is governed when it is not. That creates blind spots in monitoring, delayed incident response, and avoidable troubleshooting if the collector is later found to be reporting nowhere or to the wrong tenant.
Where management enrollment uses secrets or keys, the same hygiene issues seen across non-human identities apply. NHIMG research shows that 96% of organisations store secrets outside secret managers in vulnerable locations, and only 5.7% have full visibility into their service accounts. Those are strong reminders to validate where the secret lives, who can read it, and whether the agent identity is unique and traceable. The underlying control patterns align well with the OWASP Non-Human Identity Top 10, the SPIFFE workload identity specification, and NIST SP 800-57 Key Management.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while CIS Controls v8 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Non-Human Identity Top 10 | NHI-01 — Secrets and Credential Management | Collector enrollment depends on a secret key and managed agent identity. |
| NHI-02 — Identity Lifecycle and Ownership | The collector must be registered, owned, and managed as a continuing agent. | |
| NHI-03 — Least Privilege and Access Scoping | A managed collector should only receive the access needed to register and report. | |
| Recommendation — Store and rotate the management secret in a controlled vault and avoid embedding it in host files. Assign a clear owner and lifecycle process for the collector’s management identity. Scope the collector’s management access to the minimum permissions required for enrollment and telemetry. | ||
| CIS Controls v8 | 5.3 — Secure Configuration for Hardware and Software on Mobile Devices, Laptops, Workstations, and Servers | Editing manager.yaml is a configuration control that affects trusted operation. |
| 6.3 — Require MFA for Externally-Exposed Applications | Management plane access should be protected because it governs agent registration. | |
| Recommendation — Harden and verify collector configuration before restart so only intended management settings are active. Protect the management plane and its enrollment path with strong authentication and restricted access. | ||
| NIST CSF 2.0 | PR.AC-4 — Access Permissions and Authorizations | The collector’s management identity must be authorised to enroll and report correctly. |
| CM-2 — Baseline Configuration | Updating the management file changes the collector’s trusted baseline. | |
| DE.CM-1 — Monitoring for Unauthorized or Anomalous Activity | Managed collectors should be observable once they register and begin reporting. | |
| Recommendation — Validate that the collector’s access is explicitly authorised for the target management plane. Document the management configuration as the approved baseline before restarting the collector. Monitor for successful enrollment and alert on collectors that fail to report after restart. | ||
Practitioner Guidance
What to verify: Confirm that the management plane endpoint, secret key, and agent ID all point to the intended environment before restart. If the collector already exists in production, treat duplicate registration and cross-environment enrollment as a higher-risk condition than simple service failure.
Decision rule: If you are preserving an existing collector version, update management configuration first and restart second. If you cannot prove the collector enrolled under the expected identity after restart, do not assume the configuration is correct just because the process is running.
What good looks like: The collector comes back online, registers once, and is visible in the management plane with the expected identity, scope, and reporting path. The team can also show that the secret was changed through a controlled process rather than embedded ad hoc in the host.
Practitioner takeaway: Reinstalling is usually the wrong lever when the goal is to attach governance to an existing collector, because the real control point is the management configuration that binds the running instance to the plane.
Related resources from NHI Mgmt Group
- How should security teams bring existing AWS Direct Connect resources under Terraform management without creating drift or outages?
- How should teams remotely manage a custom OpenTelemetry Collector distribution at scale without losing configuration control?
- What happens when teams rely on the OpenTelemetry Collector without proper configuration and observability?
- How should security teams evaluate whether a log management platform can replace syslog-ng without disrupting existing deployments?
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 19, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
