Setup and Install Agent Control

Overview

Agent Control simplifies the management of your instrumentation agents. This guide will walk you through the process of installing and uninstalling Agent Control on your Kubernetes clusters, Linux hosts, or Windows hosts using different methods.

Install Agent Control

Guided install

1. Log in to New Relic.
2. Ensure the correct account is selected.

3. In Integrations & Agents, click Install Agent Control or search for Agent Control.

   

4. Follow the steps to complete the installation and configuration process.

5. Download the generated configuration to your computer and run the provided command in your terminal to install Agent Control. After installation, click Continue.
6. Test the connection to confirm the installation was successful. This step may take 5-10 minutes to complete.

Note about Authentication

New Relic Control requires the use of system identities, which are non-human identities used to authenticate and establish trust between services and applications.

During the Agent Control guided installation process, the first system identity is created using client credentials, which are included in the Helm chart's values. The credentials for this system identity expire after 12 hours. When they expire, the Agent Control Helm chart deployment will fail to authenticate with the Fleet Control service, resulting in the following error:

Error getting system identity auth token. The API endpoint returned 400: Expired client secret.

In this case, the Helm chart must be updated with new system identity credentials.

global:
  cluster: "cluster-name"
  licenseKey: "*************************"
agentControlDeployment:
  chartValues:
    systemIdentity:
      organizationId: "00000000-0000-0000-0000-000000000000"
      parentIdentity:
        clientId: "CLIENT_ID"
        clientSecret: "CLIENT_SECRET"
    config:
      fleet_control:
        fleet_id: "SAMPLE_FLEET_ID"
      agents:
        ...

Verify Installation

Now that Agent Control is installed and running, you're ready to configure and manage your agents or deploy changes to your agents using Fleet Control](/docs/new-relic-control/fleet-control/overview).

Kubernetes

1. Run the following commands to check the status of your pods:

   Agent Control installs subagents in a different namespace for security reasons. To verify that everything is working, check that the Agent Control pods are running in the newrelic-agent-control namespace and the subagent pods are running in a different namespace, such as newrelic.

$
kubectl get pods -n newrelic-agent-control    # Check Agent Control pods
$
kubectl get pods -n newrelic                  # Check subagent pods

2. Log in to New Relic, and go to Fleet Control.
3. Go to the Fleets page and select the fleet you chose during installation.
4. In the Entities table, confirm that your Kubernetes cluster appears in the list.
5. Verify that the instrumentation status for your cluster is healthy.

Support for existing Flux installations

By default, the Agent Control Helm chart leverages an embedded instance of Flux CD to manage the lifecycle of your agents in Kubernetes. However, if your organization already utilizes Flux v2 for GitOps, you can configure Agent Control to leverage your existing installation.

This approach decouples Agent Control from the embedded continuous delivery engine, allowing you to maintain a single Flux instance for your cluster operations while still benefiting from Agent Control's management capabilities.

Requirements and compatibility

To use an external Flux installation with Agent Control, your environment must meet the following requirements. Configurations that deviate from these specifications are not validated.

• Flux Version: Flux v2 or higher.
• Required Components: Your Flux installation must include:
  • Helm Controller: With the HelmRelease CRD (helm.toolkit.fluxcd.io/v2).
  • Source Controller: With the HelmRepository CRD (source.toolkit.fluxcd.io/v1).
• Namespace Scope: Your Flux instance must be configured to watch the namespace where Agent Control will be installed (or configured to watch all namespaces).

Configuration

To enable this mode, you must explicitly disable the bundled Flux components in the Agent Control Helm chart configuration.

In your values.yaml file, set agentControlCd.enabled to false:

global:
  cluster: "<YOUR_CLUSTER_NAME>"
  licenseKey: "<YOUR_LICENSE_KEY>"

# Disable the embedded Flux instance
agentControlCd:
  enabled: false

agentControlDeployment:
  chartValues:
    # ... other configurations ...

Permissions for external Flux

When using your own Flux installation, the Flux Service Account in your cluster is responsible for applying the configurations generated by Agent Control. Therefore, your existing Flux instance requires specific permissions to deploy New Relic resources. We highly recommend one of the approaches below:

• Cluster Admin (recommended): The simplest configuration is to ensure your Flux instance runs with cluster-admin privileges. This is the standard configuration for the Flux community chart and ensures it can manage all necessary resources (Deployments, DaemonSets, Services, etc.) required by New Relic agents.
• Least Privilege Configuration: If your security policies restrict the use of cluster-admin, you must create a specific ClusterRole ensuring your Flux Service Account has the permissions required by the Source Controller, Helm Controller, Agent Control, and every specific agent you plan to install.

Below is an example ClusterRole demonstrating the minimum permissions required for Agent Control and Flux components to interoperate:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: external-flux-agent-control-role
rules:
  # Permissions required by Flux to operate Agent Control components
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["customresourcedefinitions"]
    verbs: ["get"]
  - apiGroups: ["coordination.k8s.io"]
    resources: ["leases"]
    verbs: ["get", "create", "update"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["clusterroles", "rolebindings"]
    verbs: ["get", "create", "delete"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["create"]
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "create", "delete"]
  - apiGroups: [""]
    resources: ["services"]
    verbs: ["get", "create"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["create"]
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "create"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["get", "list", "watch", "create", "delete"]
  
  # Permissions required by Agent Control logic
  - apiGroups: ["helm.toolkit.fluxcd.io", "newrelic.com", "source.toolkit.fluxcd.io"]
    resources: ["*"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "create", "patch", "update", "delete", "deletecollection"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get"]
  - apiGroups: ["apps"]
    resources: ["daemonsets", "deployments", "statefulsets"]
    verbs: ["get", "list", "watch"]

Support boundaries

When using an external Flux installation, New Relic support is limited to Agent Control software (the generation of valid configuration manifests). In this mode, you have to consider a shared responsibility schema as the following:

• New Relic Responsibility: We ensure that Agent Control correctly interacts with the New Relic backend and generates valid HelmRelease and HelmRepository definitions.
• Customer Responsibility: You are responsible for the health, version maintenance, networking, and troubleshooting of your own Flux installation. Issues arising specifically from the configuration or failure of the external Flux controllers are outside the scope of Agent Control support.

Linux

• Check the status of the newrelic-agent-control service:

  bash

  Copy

  $
  sudo systemctl status newrelic-agent-control

  If the service appears in Failed or Stopped state, this means the agent got installed but there's an issue preventing its normal operation. Check the agent services logs using journalctl (or any similar Linux tool):

  bash

  Copy

  $
  journalctl -u newrelic-agent-control

  If no insights are available, check how to run the agent in debug mode to access detailed logs to get more insight into why the service cannot be started.

• If the service is not installed, try appending --debug at the end of the install command and run it again. This will enable verbose logging for the installation script. See if the verbose output has additional context explaining the error.

• Optionally, answer yes when asked to send logs to New Relic to help troubleshooting the installation. Once submitted, logs can be accessed with the following NRQL query:

  SELECT * FROM Log WHERE hostname = `your-host-name`

  Copy

Windows

Pre-installation checklist

Before installing Agent Control on Windows, verify these prerequisites:

• Administrator privileges - Right-click PowerShell and select "Run as Administrator"
• PowerShell version - Verify PowerShell 5.0 or higher:

  $PSVersionTable.PSVersion

  Copy
• Port availability - Ensure port 51200 is not in use:

  netstat -ano | findstr :51200

  Copy
  If the command returns no output, the port is available.
• Infrastructure Agent removed - Uninstall the Infrastructure Agent if already installed:

  Get-Service -Name newrelic-infra -ErrorAction SilentlyContinue

  Copy
  If this returns a service, uninstall the Infrastructure Agent first. APM agents can remain installed.
• Fleet created - Create a fleet with "Host - Windows" type in Fleet Control
• Network connectivity - Test access to New Relic services:

  Test-NetConnection -ComputerName download.newrelic.com -Port 443

  Copy
• Antivirus configuration - Add exclusions (see security software notes below)

Verify Installation

1. Check the status of the newrelic-agent-control service:

   Open PowerShell with Administrator privileges and run:

   Get-Service -Name newrelic-agent-control

   Copy

   The service should show status Running. If the service appears in Stopped state or does not exist, proceed with troubleshooting below.

2. Verify the Agent Control health endpoint:

   Invoke-WebRequest -Uri "http://localhost:51200/status" -UseBasicParsing

   Copy

   A healthy Agent Control should return a JSON response with "healthy": true.

3. Log in to New Relic, and go to Fleet Control.

4. Go to the Fleets page and select the fleet you chose during installation.

5. In the Entities table, confirm that your Windows host appears in the list.

6. Verify that the instrumentation status for your host is healthy.

What to expect after installation

After running the installation script, Agent Control sets up the supervisor service only. No instrumentation agents are deployed automatically.

Immediate (0-2 minutes):

• 0-30 seconds: Agent Control service registers and starts
• 30-60 seconds: First connection to Fleet Control established
• 1-2 minutes: Configuration synchronization completes and host appears in Fleet Control

Next steps required: After Agent Control is installed and connected to Fleet Control, you must manually deploy agents to begin collecting telemetry:

1. Log in to New Relic and navigate to Fleet Control
2. Select your fleet and locate your Windows host in the Entities table
3. Deploy agents (Infrastructure Agent, NRDOT, etc.) to your host using Fleet Control
4. Wait 5-10 minutes for deployed agents to start and send telemetry to New Relic

If the Agent Control service doesn't connect to Fleet Control within 2-3 minutes, check the troubleshooting section below.

Service management commands

Manage the Agent Control Windows service with these PowerShell commands (run as Administrator):

Start the service:

Start-Service -Name newrelic-agent-control

Stop the service:

Stop-Service -Name newrelic-agent-control

Restart the service:

Restart-Service -Name newrelic-agent-control

Check service status:

Get-Service -Name newrelic-agent-control | Format-List Status, StartType

Expected output when healthy:

Status    : Running
StartType : Automatic

View service configuration:

Get-WmiObject -Class Win32_Service -Filter "Name='newrelic-agent-control'" | Format-List Name, State, StartMode, StartName

Directory structure

Agent Control creates the following directory structure on Windows:

Program Files (Executables):

C:\Program Files\New Relic\newrelic-agent-control\
├── newrelic-agent-control.exe       # Main service executable
├── uninstall.ps1                     # Uninstallation script
└── local-data\
    └── agent-control\
        └── local_config.yaml         # Local configuration file

Program Data (Runtime data):

C:\ProgramData\New Relic\newrelic-agent-control\
├── fleet-data\
│   └── agent-control\
│       └── remote_config.yaml        # Configuration synced from Fleet Control
├── logs\
│   └── newrelic-agent-control.log    # Service logs
├── filesystem\                       # Managed agent configurations and data
└── packages\                         # Downloaded agent packages (cached)

Get-ChildItem "C:\ProgramData\New Relic\newrelic-agent-control\logs\" -Filter "newrelic-agent-control.log.*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 100

Windows-specific features

Log collection: Windows hosts can collect logs through the Infrastructure Agent's integrated Fluent Bit. The Infrastructure Agent package includes Fluent Bit binaries for Windows, enabling you to configure log forwarding using the config_logging parameter in your agent configuration. Log configurations work similarly to Linux hosts but use Windows-specific paths and formats.

Configuration notes:

• File paths in Windows configurations use backslashes (\\) and Windows-style paths (e.g., C:\\ProgramData\\...)
• Environment variables are set using Windows conventions
• Agent binaries use .exe extensions
• Configuration files are stored in the locations shown in the directory structure above

Configuration parameters

Key configuration parameters for Agent Control on Windows:

View current configuration:

Get-Content "C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml"

Verify service configuration:

Get-WmiObject -Class Win32_Service -Filter "Name='newrelic-agent-control'" | Format-List PathName, StartName, State

Uninstall Agent Control

Kubernetes

To uninstall Agent Control from your Kubernetes cluster, run the following commands:

$
helm list --all-namespaces

Linux hosts

$
sudo apt-get remove newrelic-agent-control

$
sudo zypper -n remove newrelic-infra

$
sudo yum remove newrelic-agent-control

Windows hosts

To uninstall Agent Control from your Windows host:

1. Open PowerShell with Administrator privileges.

2. Navigate to the Agent Control installation directory:

   cd "C:\Program Files\New Relic\newrelic-agent-control"

   Copy

3. Run the uninstall script:

   .\uninstall.ps1

   Copy

   This script will:

   • Stop the newrelic-agent-control service
   • Remove the service registration
   • Delete the Agent Control executable

4. (Optional) Manually remove configuration directories if you want to completely remove all Agent Control data:

   Remove-Item -Path "C:\Program Files\New Relic\newrelic-agent-control" -Recurse -Force
   Remove-Item -Path "C:\ProgramData\New Relic\newrelic-agent-control" -Recurse -Force

   Copy