Important
Agent Control and New Relic Control are now generally available for Kubernetes! Support for Linux hosts is also in public preview program, pursuant to our pre-release policies.
Agent Control is a lightweight agent supervisor that runs on Kubernetes clusters and hosts to manage the lifecycle of New Relic and open-source instrumentation agents. Communicating with Fleet Control, it remotely configures, updates, and monitors agent health across fleets.
Overview
Managing instrumentation at scale is labor intensive and error prone. Multiple agents, version sprawl, and configuration drift can create telemetry blind spots, compliance risk, and weeks of coordination for even small changes.
Agent Control provides a single, extensible supervisor you install once per host or cluster. It keeps all your New Relic and open source agents healthy and up to date, applies remote configuration, and enforces consistent settings without individually touching each agent.
Note about cost and data ingestion
Agent Control can be installed on any supported environment and doesn't require any paid entitlement. The supervisor itself doesn't push any new telemetry to New Relic. Ingest cost will depend on the instrumentation enabled in the managed agents (Infrastructure, APM, Logs).
Architecture
Agent Control uses a declarative, GitOps-like approach to agent management. It treats the remote configuration received from Fleet Control as the desired state of your instrumentation, ensuring that what you deploy to the fleet is what's running on your clusters.
The declarative engine: Flux on Kubernetes
On Kubernetes, Agent Control leverages Flux, a CNCF-graduated continuous delivery tool, as its declarative engine. Flux controllers automatically deploy and update agents based on the configuration provided by Agent Control.
The diagram below shows how Agent Control connects to New Relic Control (the backend and UI) and Flux (the on-cluster engine) to manage your agents:
Agent Control can use local or remote configurations. While local configurations are defined in the initial installation file, remote configurations are received from New Relic Control and rendered directly to your agents. This allows you to manage everything centrally, including:
- Credentials: Agent Control can pull sensitive credentials from external secrets providers like Vault, injecting them into the agent's configuration at runtime. This enhances security by keeping credentials out of the configuration itself.
- Agent Configuration: Agent Control automatically converts remote configurations into a format that is compatible with the underlying agent. This means you can manage different types of agents, such as the New Relic infrastructure agent and OpenTelemetry collector, with a single, unified process.
With Agent Control installed on each cluster and host, your observability practice can scale:
- Fleet-wide actions: Receive configurations and perform lifecycle operations across your entire fleet of agents.
- Bi-directional communications: Authenticated and encrypted communication with agents for real-time troubleshooting and diagnostics.
- Security posture: Standardize how credentials are sourced from secrets providers to centralize handling, automate rotations, and reduce exposure.
Important
To enable this level of control and communication, Agent Control requires specific permissions. It needs to be configured with the necessary access to pull configurations and to interact with local systems to manage the agent lifecycle. When deploying Agent Control, ensure you understand and grant the required permissions to maintain a secure and functional environment. Refer to the following section on Agent Control permissions.
Agent Control is designed to be a supervisor for managing instrumentation which requires the ability to perform powerful actions within your environment. It's critical to understand and grant the needed permissions.
Agent Control permissions
Deploying and managing agents in a Kubernetes cluster requires a clear understanding of the necessary permissions. Here, we'll explain the roles of both Agent Control and Flux and how they interact to securely install, update, and remove agents while ensuring that each agent only has the permissions it needs.
Kubernetes
In a Kubernetes environment, Agent Control uses Flux as its continuous delivery engine to install, update, and uninstall agents. Agent Control needs permission to create and manage Flux resources, and Flux needs elevated permission to create and update the Kubernetes resources that run the agents.
- Permissions for Agent Control: Agent Control requires permissions to create, read, update, and delete Flux-specific Custom Resources, such as
HelmReleaseandHelmRepository. This allows Agent Control to instruct Flux what to do without giving Agent Control cluster-wide admin rights itself. - Permissions for Flux: Flux requires elevated permissions, typically with a
cluster-adminrole, to manage the lifecycle of Helm charts for the agents it deploys. This includes creatingDeployments,DaemonSets,Services,ConfigMaps,Secrets, and other Kubernetes resources on behalf of the user. For security, it's a best practice to ensure that only trusted and verified configurations are used with Agent Control.
Linux hosts
For host-based systems (currently in public preview), Agent Control requires elevated permissions. The supervisor needs to run with root, administrator, or equivalent privileges to perform agent lifecycle tasks such as:
- Installing new agents: Copying agent binaries and configuration files in system directories.
- Managing agent processes: Starting, stopping, and restarting services, for example using systemd.
- Reading system data: Accessing system information needed for health, inventory, and diagnostics such as logs and performance metrics.
Similar to Kubernetes, Agent Control follows a declarative model on hosts: it reads the desired state in its configuration and only takes actions that are needed to reach that state. This is designed to limit the actions the supervisor can take. Elevated privileges are used to configure, install, update, and uninstall agents, not to perform arbitrary, unapproved actions.
Agent-specific permissions
Different agent types and their configurations require different permissions. For example, an agent that collects metrics from the Kubernetes API needs more permissions than an agent that only reads logs from files.
Agent Control is designed to manage these permissions flexibly. While Flux requires a high degree of access to function, our goal is to ensure that Agent Control only requests the minimum required permissions for the specific combination of agents you are managing.
For detailed information on the specific permissions required by each agent, refer to Supported agent types.
Requirements and compatibility
Kubernetes
Before you begin deploying Agent Control to your Kubernetes clusters, ensure that you meet the following prerequisites:
- Helm 3: Helm version 3 must be installed on your machine. For installation instructions, see Installing Helm.
- New Relic license key: You'll need a license key to report telemetry to your New Relic account.
- Kubernetes cluster name: Have the name of your Kubernetes cluster ready. You'll reference it during the installation process.
- Auth Domain Manager: To set up Agent Control and connect it to Fleet Control, you must have the Authentication Domain Manager role. For more info, refer to User Management Concepts.
Important: Existing instrumentation
If your Kubernetes cluster is already instrumented with New Relic, you must uninstall the existing instrumentation before installing Agent Control. After installing Agent Control, you can use New Relic Control to install and manage all infrastructure agents on the cluster. For guidance on this process, refer to Manage existing instrumentation with Agent Control.
warning
Installing multiple instances of Agent Control on the same cluster is not supported.
Agent Control is compatible with:
- Last three minor Kubernetes releases
- Minikube, Kind, Amazon EKS, Azure AKS, and Google GKE
For system requirements related to the New Relic Kubernetes infrastructure agent and the New Relic OpenTelemetry (NRDOT) collector, refer to:
Linux hosts
Before installing Agent Control, make sure you have a New Relic account and that your system meets the requirements below. We support these operating systems up to their manufacturer's end-of-life.
Processor architectures | Agent Control supports these processor architectures:
|
Operating systems | Agent Control supports these operating systems up to their manufacturer's end-of-life.
|
To check your operating system details, run this command:
$cat /etc/os-releaseNext step
After you've confirmed compatibility and met all the prerequisites, you're ready to install Agent Control.