Agent Control setup with Terraform

New Relic Agent Control with Terraform provides a powerful, declarative solution for managing fleets of agents at scale. By using Terraform and Helm together, you can ensure a consistent, repeatable, and scalable approach to deploying New Relic instrumentation across your entire infrastructure, especially when dealing with multiple Kubernetes clusters.

Prerequisites

Before you begin, ensure you have the following:

• Required Tools:

  • Terraform installed on your machine.
  • Helm 3 installed on your machine. For installation instructions, see Installing Helm.
  • Terraform Helm Provider included in your Terraform configuration script for the installation to work.

• New Relic Credentials:

  • New Relic license key: You'll need a New Relic license key to report telemetry to your New Relic account.
  • New Relic user key: You'll need your New Relic user key if you haven't already pulled your clientID key and secret.

• Configuration Details:

  • New Relic Organization ID: The New Relic OrgId will identify which organization you are getting your client ID key and secret from.
  • User permissions: Your user needs the correct permissions to create a System Identity. This typically requires the Authentication Domain Manager and Org Product Admin roles.
  • Kubernetes cluster name: Have the name of your Kubernetes cluster ready, as it will be referenced during the installation process.

Kubernetes Compatibility

To find out which Kubernetes versions are compatible with this solution, refer to the compatibility section in the overview.

Install

If you don't have your clientId and clientSecret, use the following NerdGraph API call to generate them. This requires your New Relic Admin User Key and Organization ID.

$
curl -X POST \
>
      https://api.newrelic.com/graphql \
>
      -H 'Content-Type: application/json' \
>
      -H 'x-api-key: [INSERT_USER_API_KEY]' \
>
      --data-raw '{"query": "mutation SICreate { systemIdentityCreate(name: \"User Key for Agent Control\" organizationId: \"[INSERT_YOUR_ORG_ID]\") { clientId clientSecret } }"}' \
>
      --compressed

In the command, replace the placeholder values with your organizationId and user key. This returns the required credentials that you'll use in your configuration file.

Step 1: Create Your Project Directory

Create a directory for your project and place your main.tf file inside it. This is where you'll define your Terraform resources. Confirm that you have added the Helm provider to your Terraform file.

Step 2: Configure Terraform with the Helm Release

Configure your Terraform script with a Helm release that uses New Relic's charts for Agent Control. The following example shows a basic configuration:

provider "helm" {
 kubernetes {
   config_paths = [
       "~/.kube/config"
   ]
 }
}


resource "helm_release" "newrelic" {
   name = "agent-control"
   repository = "https://newrelic.github.io/helm-charts/"
   chart = "agent-control"
   namespace = "newrelic"
   create_namespace = "true"


   values = [
       file("./values-newrelic.yaml")
   ]
}

Note that the Terraform script references a values-newrelic.yaml file. This is the New Relic Agent Control configuration file that will be used for setting up Agent Control. It does not need to be in the same directory as the Terraform script. You can reference it from any location by providing the correct path in the file() function within the values attribute of the helm_release resource.

Or, if you place the values-newrelic.yaml file directly in the Terraform project directory, the main.tf script will automatically reference it.

Here is an example of a basic values-newrelic.yaml file with no additional configuration included:

global:
 cluster: [YOUR_CLUSTER_NAME]
 licenseKey: [YOUR_INGEST_LICENSE_KEY]


agent-control-deployment:
 identityClientId: [YOUR_IDENTITY_CLIENT_ID]
 identityClientSecret: [YOUR_IDENTITY_CLIENT_SECRET]
 config:
   fleet_control:
   # optional
     fleet_id: [YOUR_FLEET_ENTITY_GUID]
     auth:
       organizationId: [ORG_ID]
   agentControl:
     content:
       log:
         level: trace

To explore all available configuration settings, refer to values-newrelic.yaml.

Step 3: Run Terraform Commands

Initialize Terraform, review the plan, and apply the changes.

$
# Initialize Terraform
$
    terraform init

$
# Review the changes before applying
$
    terraform plan

$
# Apply the changes to your cluster
$
    terraform apply

Step 5: Verify the Installation

Check to make sure the Agent Control pods and any configured agents are running correctly in their respective namespaces.

$
# Check Agent Control pods
$
    kubectl get pods -n newrelic

$
# Check pods in the agent namespace, e.g., 'newrelic-agents'
$
    kubectl get pods -n newrelic-agents

Configuration

In the values-newrelic.yaml file, you can configure you can configure Agent Control to deploy multiple monitoring agents. Here's an example showing the deployment of several agents, including:

• Infrastructure: New Relic's infrastructure agent
• Logs: Fluent Bit logs agent
• OpenTelemetry: The New Relic distribution of the OpenTelemetry Collector
• Gateway: New Relic Pipeline Control gateway agent

agent-control-deployment:
  identityClientId: [YOUR_IDENTITY_CLIENT_ID]
  identityClientSecret: [YOUR_IDENTITY_CLIENT_SECRET]
  config:
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          chart_version: "*"  
          chart_values:
            newrelic-infrastructure:
              enableProcessMetrics: true
      logs:
        type: newrelic/io.fluentbit:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
            chart_values:
              newrelic-logging:
                sendMetrics: true
      agent-operator:
        type: com.newrelic.k8s_agent_operator:0.1.0
        content:
          chart_version: "*"
      open-telemetry:
        type: newrelic/io.opentelemetry.collector:0.1.0
        content:
            # Ref: `https://github.com/newrelic/helm-charts/blob/master/charts/nr-k8s-otel-collector/values.yaml`
            # Recommended: check and define an explicit chart version (latest stable)
            chart_version: "*"
              chart_values:
                nr-k8s-otel-collector:
                  receivers.filelog.enabled: false
      gateway:
        type: newrelic/com.newrelic.pipeline_control_gateway:0.1.0
        content:
          chart_version: "*"
          chart_values:
            gateway:
              autoscaling:
                minReplicas: 2
                maxReplicas: 10
                targetCPUUtilizationPercentage: 70

Uninstall

To uninstall Agent Control:

1. Remove the helm_release resource block for newrelic_agent_control from your main.tf file.
2. Run terraform plan to review the changes. Carefully examine the plan output to ensure that only the intended resources are marked for deletion.
3. Run terraform apply and confirm the execution to uninstall the release. This will implement the planned changes, effectively removing the specified Helm release from your environment.

Confirm the execution when prompted to complete the uninstallation process.