Set up 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.

   Important

   To install Agent Control, it is mandatory to have a fleet. If you haven't yet created a fleet for this managed entity, you can create a fleet during the installation in the Guided Install or complete the fleet creation process in Fleet Control, and then return to this guided installation step.

   Fleet type requirement: Fleets are separated by type. You must select the right type for your hosts (Windows or Linux) or k8s. Using a fleet of a different type will cause installation or operation issues.

   Templates and configurations in different environments may require adjustments for compatibility.

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.

7. 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.

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/cluster 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 host/cluster in the Entities table
3. Deploy agents (Infrastructure Agent, NRDOT, etc.) to your host/cluster using Fleet Control
4. Wait 5-10 minutes for deployed agents to start and send telemetry to New Relic

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 or the host command. The credentials for this system identity expire after 12 hours. When they expire, the Agent Control Helm chart deployment or host command 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 or host command must be updated with new system identity credentials. Helm chart example:

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:
        ...

Advanced Kubernetes configuration

By default, the Agent Control Helm chart leverages an embedded instance of Flux CD to manage the lifecycle of your agents in Kubernetes. Depending on your ecosystem requirements, you can configure Agent Control to leverage an existing custom Flux v2 installation or bypass the continuous delivery infrastructure components entirely.

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.

Install Agent Control without Flux

You can install Agent Control without Flux when its role is limited to delivering configuration to managed agents and not installing or upgrading them. In this mode, Agent Control cannot manage agent lifecycle—it does not install or upgrade agents and only pushes configurations via Fleet Control. You are responsible for installing and upgrading Agent Control and any managed agents yourself. The primary use case is the Pipeline Control gateway: Agent Control delivers Pipeline Control gateway configuration changes.

To install Agent Control without Flux, set agentControlCd.enabled to false in your Helm values. Agent Control will not create or monitor any Flux objects.

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

agentControlCd:
  enabled: false

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

When you install the Pipeline Control gateway through New Relic's guided install, the generated values file already sets agentControlCd.enabled: false. You do not need to edit it manually.

Verify installation

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.

   bash

   Copy

   $
   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.

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 CLI install command from the guided installation and run it again. This enables verbose logging for the installation script and may provide 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

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

   Open PowerShell with Administrator privileges and run:

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

   Copy

   Expected output when healthy:

   Status    : Running
   StartType : Automatic

   Copy

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.

If the Agent Control service doesn't connect to Fleet Control within 2-3 minutes, see Windows hosts troubleshooting.

Uninstall Agent Control

Kubernetes

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

$
helm list --all-namespaces

Linux hosts

To uninstall Agent Control from your Linux host:

1. Run the uninstall script:

   bash

   Copy

   $
   sudo sh /usr/lib/newrelic-agent-control/uninstall.sh

   This script will:

   • Stop the newrelic-agent-control service
   • Detect the package manager
   • Execute the package manager purge so all the Agent Control files are removed from the system

Windows hosts

To uninstall Agent Control from your Windows host:

1. Open PowerShell with Administrator privileges.

2. Run the uninstall script:

   PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\New Relic\newrelic-agent-control\uninstall.ps1"

   Copy

   This script will:

   • Stop the newrelic-agent-control service
   • Remove the service registration
   • Delete the Agent Control directories and files