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 simplifies large-scale monitoring management of New Relic and OpenTelemetry agents. It integrates with Fleet Control to remotely configure, update, and monitor the health of instrumentation agents in Kubernetes and host environments
Overview
Managing observability infrastructure across a large, diverse environment is challenging. Manually deploying and configuring multiple agents is time-consuming, prone to errors, and difficult to keep consistent. This manual toil makes it hard to quickly add new instrumentation, optimize configurations, and keep agents updated.
Agent Control provides a single, unified solution for managing all your New Relic and OpenTelemetry agents. It communicates with the New Relic platform to receive remote configurations and deployment instructions. This eliminates the need for manual intervention on each host, allowing you to manage your entire fleet from a single, centralized location.
Note about cost and data ingestion
Agent Control can be installed on any supported enviroment 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's power comes from its use of a declarative, GitOps-like approach to agent management. It treats the desired state of your instrumentation as a single source of truth, ensuring that what you configure in New Relic Control is what's running on your clusters.
The declarative engine: Flux on Kubernetes
On Kubernetes, Agent Control leverages Flux, a powerful and widely adopted CNCF project, as its declarative engine. Flux's 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 fetched from New Relic Control and rendered directly to your agents. This allows you to manage everything from a central point (and UI), including:
- Credentials: Agent Control can pull sensitive credentials from external secret providers like Vault, rendering them into the agent's configuration at runtime. This enhances security by keeping credentials out of the configuration itself.
- Agent Configuration: It automatically converts remote configurations into a format that is compatible with the underlying agent. This means you can manage different types of agents (e.g., Infrastructure Agent, OpenTelemetry Collector) with a single, unified process.
This is how Agent Control can be used to enhance your observability experience:
- Fleet-wide commands: The ability to send commands and perform actions on your entire fleet of agents.
- Advanced communication: Direct, real-time communication with agents for on-demand troubleshooting and data collection.
- Enhanced security: Further integration with security providers and automated credential management.
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 able to manage your instrumentation, which requires it to perform powerful actions within your environment. It's critical to understand and grant the required 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 declarative engine to install, update, and uninstall agents. As such, Agent Control needs permissions to manage Flux resources, and Flux itself needs elevated permissions to manage the agent workloads.
- 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 tell Flux what to do without needing direct cluster-admin access itself. - Permissions for Flux: Flux requires high-level permissions, typically with a
cluster-adminrole, to manage the lifecycle of any Helm chart it's instructed to deploy. This includes creatingDeployments,DaemonSets,Services, and other core 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 also requires elevated access. The supervisor needs to run with root or equivalent privileges to perform tasks such as:
- Installing new agents: Placing agent binaries and configuration files in system-level directories.
- Managing agent processes: Starting, stopping, and restarting services (e.g., using systemd).
- Reading system data: Accessing system-level logs and performance metrics.
Similar to Kubernetes, the host-based supervisor's power is balanced by the declarative model: it only takes actions that are defined in its configuration. This is designed with a goal to limit the actions the supervisor can take. Elevated privileges are used to maintain the desired state of the 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 level 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 deploying.
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
Multiple installations of Agent Control on the same cluster are 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 | The agent supports these processor architectures:
|
Operating systems | The agent 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.