Agent Control overview

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.

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.

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 HelmRelease and HelmRepository. 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-admin role, to manage the lifecycle of Helm charts for the agents it deploys. This includes creating Deployments, 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.

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:

• Kubernetes integration: compatibility and requirements
• OpenTelemetry for Kubernetes

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.

To check your operating system details, run this command:

$
cat /etc/os-release

Next step

After you've confirmed compatibility and met all the prerequisites, you're ready to install Agent Control.