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 or Linux 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

  Copia

  $
  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

  Copia

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

  Copia

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