Managing configurations

Important

Agent Control and New Relic Control are now generally available for Kubernetes! Support for Linux hosts and Windows hosts is also in public preview program, pursuant to our pre-release policies.

Agent Control provides a seamless approach for configuration independenlty of the environment where it is deployed. Two methods for managing agent configurations are available:

Local configuration: A comprehensive values.yaml file used during the initial Helm installation.
Remote configuration: A centralized, YAML-based configuration you create in New Relic Control that is remotely deployed to your entire fleet.

Remote configuration is the recommended method for day-to-day management. It ensures consistent agent behavior across your environment, simplifies change management, and enables you to scale without manually updating local YAML files on each host.

Tip

The values-newrelic.yaml file, which traditionally defined New Relic agent settings, now also includes configuration for Agent Control. The parameters you define in this file determine how both Agent Control and its managed agents operate. This file is referred to as the local configuration.

Understanding the two layers of configuration

Agent Control's configuration is structured in two layers:

Agent Control's core configuration: These are the top-level settings that control how Agent Control operates, such as its connection to New Relic, its identity, and fleet management details.
Managed agents' configurations: These are the individual chart_values for each subagent (for example., Infrastructure Agent, Fluent Bit) that Agent Control deploys and manages.

When a local and remote configuration are both present, Agent Control applies the following logic:

Remote configuration takes precedence. Any settings defined in a remote configuration from New Relic Control will override the corresponding settings in the local values.yaml file.
To intentionally override remote settings with your local configuration, you can deploy an empty remote configuration via New Relic Control. This change will apply to all clusters in the selected fleet.

Kubernetes configuration

These instructions and examples apply to Agent Control running on a Kubernetes cluster.

Local `values.yaml` configuration for Kubernetes

The local configuration file for Kubernetes, used during installation, contains all the settings for Agent Control and its managed agents.

This example shows the two layers of configuration within a single file.

# Layer 1: Agent Control's Core Configuration
global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

# Values related to the Agent Control's Helm chart release.
# `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control-bootstrap/values.yaml`
agentControlDeployment:
  chartValues:
    systemIdentity:
      organizationId: "****"
      parentIdentity:
        clientId: "****"
        clientSecret: "****"
    config:
      fleet_control:
        # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
        fleet_id: "****"

      # Layer 2: Managed Agents' Configurations
      # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
      agents:
        infrastructure:
          agent_type: newrelic/com.newrelic.infrastructure:0.1.0
        logs:
          agent_type: newrelic/io.fluentbit:0.1.0
        agent-operator:
          agent_type: com.newrelic.k8s_agent_operator:0.1.0

    agentsConfig:
      infrastructure:
        # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle`
        # Recommended: check and define an explicit chart version (latest stable)
        chart_version: "*"
        chart_values:
          newrelic-infrastructure:
          enableProcessMetrics: true
      logs:
        # 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:
        chart_version: "*"

The sample demonstrates how to configure Agent Control along with two managed agents: the Kubernetes infrastructure agent and Fluent Bit for log forwarding. For example, if you don't want to send health metrics for your Fluent Bit log collector, simply set sendMetrics: false in the YAML file before running the install command.

Remote configuration for Kubernetes

Remote configuration ensures consistent agent behavior across your environment, simplifies change management, and enables you to scale observability without manually managing local YAML files.

To deploy configurations centrally across clusters, define this same YAML content in the Configurations section of Fleet Control. You can then apply the configuration to an entire fleet of clusters as part of a remote deployment. This is referred to as the remote configuration file.

Tip

When you define a configuration in the New Relic Control UI, the YAML structure is different. You only provide the YAML that corresponds to the content block for a single agent.

Sample configurations: Agent Control on Kubernetes

configurations: Agent Control on Kubernetes The following examples show how to configure Agent Control to manage different sets of agents. These configurations can be used either during initial installation or as part of a remote configuration in Fleet Control.

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

The following examples show how to configure Agent Control with a set of subagents using the local values.yaml file.

Agent Control with New Relic infrastructure and Fluent Bit

This example deploys Agent Control with infrastructure monitoring and Fluent Bit for log collection.

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

# See `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control-bootstrap/values.yaml`
agentControlDeployment:
  chartValues:
    systemIdentity:
      organizationId: "****"
      parentIdentity:
        clientId: "****"
        clientSecret: "****"
    config:
      fleet_control:
        # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
        fleet_id: "****"
      agents:
        infrastructure:
          agent_type: newrelic/com.newrelic.infrastructure:0.1.0
        logs:
          agent_type: newrelic/io.fluentbit:0.1.0
        agent-operator:
          agent_type: com.newrelic.k8s_agent_operator:0.1.0
    agentsConfig:
      infrastructure:
        # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle`
        # Recommended: check and define an explicit chart version (latest stable)
        chart_version: "*"

        #chart_values:
        #  newrelic-infrastructure:
        #    enableProcessMetrics: true
      logs:
        # 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:
        chart_version: "*"

Agent Control with OpenTelemetry and custom collector settings

with OpenTelemetry and custom collector settings This example deploys Agent Control with the New Relic distribution of OpenTelemetry (NRDOT) collector and disables the filelog receiver in the managed nr-k8s-otel-collector Helm chart.

Important

Security Best Practice: Do not store sensitive values like your license key directly in the configuration. We recommend using a Kubernetes secret. Agent Control can then securely pull these values from the secret at runtime.

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"
# Values related to the Agent Control's Helm chart release.
# `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control-bootstrap/values.yaml`
agentControlDeployment:
  chartValues:
    systemIdentity:
      organizationId: "****"
      parentIdentity:
        clientId: "****"
        clientSecret: "****"
    config:
      fleet_control:
        # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
        fleet_id: "****"

      # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
      agents:
        nr-otel-collector:
          agent_type: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"
    # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
    agentsConfig:
      nr-otel-collector:
        chart_version: "*"
        chart_values:
          nr-k8s-otel-collector: {}
          global: {}

Sample configurations: Remote Agent Configurations on Kubernetes

The following examples show how to configure individual agents remotely from the New Relic Control UI.

Remote configuration: New Relic infrastructure

This example shows how to remotely configure the New Relic infrastructure agent for Kubernetes using Fleet Control. It enables process metrics collection by setting enableProcessMetrics: true.

Remote configuration: Fluent Bit

This example configured Fluent Bit remotely via Fleet Control. It enables health metric reporting from the log collector by setting sendMetrics: true.

Remote configuration: Prometheus

This example configures the Prometheus agent remotely using Fleet Control. It enables low-data mode to reduce telemetry volume and disable default integrations.

Remote configuration: OpenTelemetry

This example configures the New Relic OpenTelemetry collector and enable lowDataMode as a valid option.

Important

Create a Kubernetes secret to securely store the New Relic license key and use it in the chart_values in replacement of the licenseKey value:

customSecretName: "your-secret-name"
customSecretLicenseKey: "your-secret-key"

We recommend using Fleet Control to define and deploy OpenTelemetry configuration across your fleets. To configure OpenTelemetry remotely, create a configuration in Fleet Control with the structure shown below. You can adjust values such as lowDataMode or receivers.filelog.enabled, and include any other relevant Helm chart settings based on your needs.

chart_version: "*"
chart_values:
  nr-k8s-otel-collector:
    lowDataMode: true

Proxy configuration for Kubernetes

Agent Control supports proxy configuration to route traffic through corporate proxies. Proxy settings can be set through environment variables or directly in the configuration file.

Proxy precedence

Agent Control will use proxy settings in the following order of precedence:

proxy configuration field in the Agent Control configuration
HTTP_PROXY environment variable
HTTPS_PROXY environment variable

Proxy configuration with self-signed certificates

For proxy setups using HTTPS authentication with self-signed certificates, you need to provide the CA certificate bundle and configure proxy authentication:

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

agentControlDeployment:
  proxy:
    url: https://proxy-service:8080

  # Mount CA certificate bundle to Agent Control
  extraVolumeMounts:
    - mountPath: /etc/ssl/certs/
      name: ca-certs
  extraVolumes:
    - name: ca-certs
      secret:
        secretName: ca-certs

# Configure Flux components to use proxy
agentControlCd:
  flux2:
    sourceController:
      extraEnv:
        # Configure Flux source-controller to proxy all requests
        - name: HTTPS_PROXY
          value: https://proxy-service:8080
        # Except for in-cluster requests
        - name: "NO_PROXY"
          value: ".cluster.local.,.cluster.local,cluster.local,.svc,127.0.0.0/8,10.0.0.0/8"
      volumeMounts:
        # Mount CA certificate bundle to source-controller trust root store. The bundle should contain the
        # proxy CA cert.
        - mountPath: /etc/ssl/certs/
          name: ca-certs
      volumes:
        - name: ca-certs
          secret:
            secretName: ca-certs

Proxy configuration for managed agents

Caution

Configuring a proxy in Agent Control does not automatically configure the same proxy settings for the agents it manages. Each agent has its own proxy configuration that must be set separately according to that agent's specific configuration format and requirements.

When using a proxy, you must also configure proxy settings for each managed agent individually. Refer to each agent's specific documentation for proxy configuration options.

Secrets management

Agent Control provides a robust mechanism for managing sensitive data, such as passwords and API keys, by retrieving them from dedicated secret providers. This ensures that sensitive information is not hard-coded directly into configuration files. The system currently supports the providers described in Value providers.

Private repository configuration

Agent Control supports configuring private Helm repositories to deploy both Agent Control itself and the managed agents. This enables environments where the New Relic Helm charts are not directly accessible.

Caution

When using private Helm repositories, the charts need to be compatible and the referenced images within the charts must be reachable. If not, the agents will not work as expected.

1. Enable private repositories for agents

For security reasons, only explicitly enabled repositories are allowed in remote configurations. To enable specific repositories, update the Agent Control configuration as follows:

# values-newrelic.yaml

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

# ...

agentControlDeployment:
  config:
    allowedChartRepositoryUrl:
      - https://my-private-repository-1
      - https://my-private-repository-2
    # ...

The allowed repository configurations can then be used in your remote configurations within New Relic Control. Example:

chart_version: "1.2.3"
chart_repository:
  url: "https://my-private-repository-1"
  name: "my-chart-name" # Optional: use only if the chart name doesn't match New Relic's chart name

Additionally, you need to configure Agent Control's Helm installation to use your private repository if the agent-control-bootstrap chart itself is in a private repository. This is separate from the configuration for managed agents. Refer to the agent-control-bootstrap Helm chart values.yaml to configure the installationJob section as follows:

chartRepositoryUrl: The URL containing your repository location.
chartName: The chart name if using a different chart name.
repositorySecretReferenceName and repositoryCertificateSecretReferenceName: The secrets required for authenticating to your repository. See the authentication section below for details.

2. Set up authentication for private repositories

You need to set up additional resources to enable authentication for accessing your private repository as follows:

To authenticate using basic authentication (username and password), you need to create a secret in the Agent Control namespace containing the expected values in data.username and data.password.

Example:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
stringData:
  username: "myUser"
  password: "myPassword"

For more details, see the Flux documentation.

When using basic authentication, the remote configuration should be configured as follows:

chart_repository:
  url: "https://my-private-repository-1"
  secret_reference:
    name: my-secret

To authenticate using TLS, you need to create a secret containing:

tls.crt and tls.key: client certificate and private key used for TLS client authentication
ca.crt: CA certificate used to verify the server (required if the server uses a self-signed certificate)
The Secret should be of type Opaque or kubernetes.io/tls. All files in the Secret are expected to be PEM-encoded.
Example:
```
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  namespace: newrelic-agent-control
type: kubernetes.io/tls # or Opaque
data:
  tls.crt: <BASE64>
  tls.key: <BASE64>
  # NOTE: Can be supplied without the above values
  ca.crt: <BASE64>
```
For more details, see the Flux documentation.
When using TLS certificate authentication, the remote configuration should be configured as follows:
```
chart_repository:
  url: "https://my-private-repository-1"
  certificate_secret_reference:
    name: my-secret
```

Linux configuration

These are the default paths for Agent Control configuration:

Local configuration file: /etc/newrelic-agent-control/config.yaml
Remote configuration file: /var/lib/newrelic-agent-control/config.yaml (if enabled via Fleet Control deployment)
Service definition: /lib/systemd/system/newrelic-agent-control.service
Service environment file: /etc/newrelic-agent-control/newrelic-agent-control.conf

By default, the agent might orchestrate the infrastructure agent and the OpenTelemetry collector:

# Configures the integration with Fleet Control
fleet_control:
  # EU region? Use: https://opamp.service.eu.newrelic.com/v1/opamp
  # JP region? Use: https://opamp.service.jp.newrelic.com/v1/opamp
  endpoint: https://opamp.service.newrelic.com/v1/opamp
  headers:
    api-key: YOUR_INGEST_KEY
  auth_config:
    # EU region? Use: https://system-identity-oauth.service.eu.newrelic.com/oauth2/token
    # JP region? Use: https://system-identity-oauth.service.jp.newrelic.com/oauth2/token
    token_url: "https://system-identity-oauth.service.newrelic.com/oauth2/token"
    client_id: "YOUR_CLIENT_ID
    provider: "local"
    private_key_path: "path/to/key"

# Configures the agents to be supervised by Agent Control
agents:
  # Agent name (RFC-1035 valid label)
  nr-infra-agent:
    # The supported agent type and agent type version
    agent_type: "newrelic/com.newrelic.infrastructure:0.1.0"
  nr-otel-collector:
    agent_type: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"

You can rename or remove either agent based on your observability requirements. Agent name must be a valid RFC-1035 label name.

You can also use environment variables to define the agent settings:

Use the NR_ (single underscore) prefix to target the main Agent Control configuration.
Use __ (double underscores) to target the available settings in Agent Control. This is required to avoid collisions with configuration keys that contain underscores.
Environment variables only have predencende over the local configuration file. If remote configuration is enabled, then environment variables are not considered.
For example, to define a dynamic configuration for the fleet_control::endpoint add the NR_FLEET_CONTROL__ENDPOINT=https://opamp.service.newrelic.com/v1/opamp in the service definition file.

Configure the agents

Agent Control can currently manage the following pre-defined on-host agent types:

New Relic infrastructure agent: newrelic/com.newrelic.infrastructure. All existing features in the infrastructure agent are supported, including orchestrating on-host integrations and our log forwarder integration based on FluentBit.
New Relic distribution for OpenTelemetry: newrelic/com.newrelic.opentelemetry.collector

Each agent type offers a set of optional variables that can be customized to tailor its behavior. To customize the agent local configuration:

Create a values.yml file: This file will contain your desired configuration values.
Place the values.yml file in the /etc/newrelic-agent-control/fleet/agents.d/YOUR-AGENT-NAME/values/ directory. Here, YOUR-AGENT-NAME is the actual name of your agent (for example, nr-infra-agent).

Here's a list of available variables for the latest agent type versions:

New Relic infrastructure agent: 0.1.0
New Relic distribution for OpenTelemetry: 0.1.0

Agent type	Variable	Type	Default
`com.newrelic.infrastructure`	`config_agent`	A YAML containing infrastructure agent configurations	(empty)
`com.newrelic.infrastructure`	`config_integrations`	A YAML map (keys are file names) containing on-host integration configurations	(empty)
`com.newrelic.infrastructure`	`config_logging`	A YAML map (keys are file names) containing log forwarding configurations	(empty)
`com.newrelic.infrastructure`	`health_port`	Port for the infrastructure agent local status server	`/health/status`
`com.newrelic.opentelemetry.collector`	`config`	OpenTelemetry collector configuration (in YAML format)	(empty)
`com.newrelic.opentelemetry.collector`	`health_check.path` `health_check.port`	Path and port for the OTel collector health check extension local http endpoint	`localhost:13133/health/status`
All managed agents	`backoff_delay`	Time until next retry if collector fails to start (in seconds).	`20s`

Tip

You can configure the infrastructure agent settings and OpenTelemetry collector settings as needed following the supported configurations.

Sample configurations

Remote Configuration with Fleet Control

The following examples contain common use cases that are ready to copy and paste as valid configurations for Agent Control and managed agents.

Infrastructure agent settings, Redis integration settings and Log forwarding settings for our FluentBit integration. The config_agent with a valid license_key is always mandatory. Other sections are optional (remove or update as needed):

config_agent:
  license_key: YOUR_LICENSE_KEY
  custom_attributes:
    env: demo
config_integrations:
  nri-redis-example.yml:
    integrations:
      - name: nri-redis
        env:
          hostname: localhost
          port: 6380
          keys: '{"0":["<KEY_1>"],"1":["<KEY_2>"]}'
          remote_monitoring: true
config_logging:
  fluentbit-example.yml:
    logs:
      - name: syslog
        file: /var/log/syslog
        attributes:
          logtype: linux_syslog

Basic host monitoring using the OTel collector (process monitoring disabled) and OTLP receiver enabled to receive traces, metrics and logs from APM services:

config:
  receivers:
    otlp:
      protocols:
        grpc:
        http:

    hostmetrics:
      collection_interval: 20s
      scrapers:
        cpu:
          metrics:
            system.cpu.time:
              enabled: false
            system.cpu.utilization:
              enabled: true
        load:
        memory:
          metrics:
            system.memory.utilization:
              enabled: true
        paging:
          metrics:
            system.paging.utilization:
              enabled: false
            system.paging.faults:
              enabled: false
        filesystem:
          metrics:
            system.filesystem.utilization:
              enabled: true
        disk:
          metrics:
            system.disk.merged:
              enabled: false
            system.disk.pending_operations:
              enabled: false
            system.disk.weighted_io_time:
              enabled: false
        network:
          metrics:
            system.network.connections:
              enabled: false

    filelog:
      include:
        - /var/log/syslog

  processors:
    # group system.cpu metrics by cpu
    metricstransform:
      transforms:
        - include: system.cpu.utilization
          action: update
          operations:
            - action: aggregate_labels
              label_set: [ state ]
              aggregation_type: mean
        - include: system.paging.operations
          action: update
          operations:
            - action: aggregate_labels
              label_set: [ direction ]
              aggregation_type: sum
    # remove system.cpu metrics for states
    filter/exclude_cpu_utilization:
      metrics:
        datapoint:
          - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"'
          - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"'
          - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"'
    filter/exclude_memory_utilization:
      metrics:
        datapoint:
          - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"'
          - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"'
          - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"'
          - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"'
          - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"'
    filter/exclude_memory_usage:
      metrics:
        datapoint:
          - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"'
          - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"'
    filter/exclude_filesystem_utilization:
      metrics:
        datapoint:
          - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"'
    filter/exclude_filesystem_usage:
      metrics:
        datapoint:
          - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"'
          - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"'
    filter/exclude_filesystem_inodes_usage:
      metrics:
        datapoint:
          - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"'
          - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"'
    filter/exclude_system_disk:
      metrics:
        datapoint:
          - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true'
          - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true'
          - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true'
          - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true'
          - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true'
    filter/exclude_system_paging:
      metrics:
        datapoint:
          - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"'
          - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"'
    filter/exclude_network:
      metrics:
        datapoint:
          - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"'

    attributes/exclude_system_paging:
      include:
        match_type: strict
        metric_names:
          - system.paging.operations
      actions:
        - key: type
          action: delete

    transform:
      trace_statements:
        - context: span
          statements:
            - truncate_all(attributes, 4095)
            - truncate_all(resource.attributes, 4095)
      log_statements:
        - context: log
          statements:
            - truncate_all(attributes, 4095)
            - truncate_all(resource.attributes, 4095)

    # used to prevent out of memory situations on the collector
    memory_limiter:
      check_interval: 1s
      limit_mib: 100

    batch:

    resourcedetection:
      detectors: ["env", "system"]
      system:
        hostname_sources: ["os"]
        resource_attributes:
          host.id:
            enabled: true

    resourcedetection/cloud:
      detectors: ["gcp", "ec2", "azure"]
      timeout: 2s
      ec2:
        resource_attributes:
          host.name:
            enabled: false

  exporters:
    otlp:
      endpoint: otlp.nr-data.net:4317
      headers:
        api-key: ${NEW_RELIC_LICENSE_KEY}

  service:
    pipelines:
      metrics:
        receivers: [otlp, hostmetrics]
        processors:
          - memory_limiter
          - metricstransform
          - filter/exclude_cpu_utilization
          - filter/exclude_memory_utilization
          - filter/exclude_memory_usage
          - filter/exclude_filesystem_utilization
          - filter/exclude_filesystem_usage
          - filter/exclude_filesystem_inodes_usage
          - filter/exclude_system_disk
          - filter/exclude_network
          - attributes/exclude_system_paging
          - batch
          - resourcedetection
          - resourcedetection/cloud
        exporters: [otlp]
      traces:
        receivers: [otlp]
        processors: [transform, resourcedetection, resourcedetection/cloud, batch]
        exporters: [otlp]
      logs:
        receivers: [otlp, filelog]
        processors: [transform, resourcedetection, resourcedetection/cloud, batch]
        exporters: [otlp]

A valid config for Agent Control itself showing how to disable agents, for example, the OTel collector:

agents:
  nr-infra-agent:
    agent_type: "newrelic/com.newrelic.infrastructure:0.1.0"
  #nr-otel-collector:
  #  agent_type: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"

Windows configuration

These are the default paths for Agent Control configuration on Windows:

Local configuration file: C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml
Remote configuration file: C:\ProgramData\New Relic\newrelic-agent-control\fleet-data\agent-control\remote_config.yaml (synced from Fleet Control)
Service executable: C:\Program Files\New Relic\newrelic-agent-control\newrelic-agent-control.exe
Log directory: C:\ProgramData\New Relic\newrelic-agent-control\logs\

By default, Agent Control on Windows can orchestrate the infrastructure agent and the OpenTelemetry collector:

# Configures the integration with Fleet Control
fleet_control:
  endpoint: https://opamp.service.newrelic.com/v1/opamp
  headers:
    api-key: YOUR_INGEST_KEY
  auth_config:
    token_url: "https://system-identity-oauth.service.newrelic.com/oauth2/token"
    client_id: "YOUR_CLIENT_ID"
    provider: "local"
    private_key_path: "path\\to\\key"

# Configures the agents to be supervised by Agent Control
agents:
  # Agent name (RFC-1035 valid label)
  nr-infra-agent:
    # The supported agent type and agent type version
    agent_type: "newrelic/com.newrelic.infrastructure:0.1.0"
  nr-otel-collector:
    agent_type: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"

Tip

For regional accounts, use the appropriate endpoint and token_url:

EU region: https://opamp.service.eu.newrelic.com/v1/opamp and https://system-identity-oauth.service.eu.newrelic.com/oauth2/token
JP region: https://opamp.service.jp.newrelic.com/v1/opamp and https://system-identity-oauth.service.jp.newrelic.com/oauth2/token

You can rename or remove either agent based on your observability requirements. Agent name must be a valid RFC-1035 label name.

Windows-specific configuration notes

File paths use backslashes (\\) and Windows-style paths (for example, C:\\ProgramData\\...)
Agent binaries use .exe extensions
The service runs as LocalSystem — ensure configuration files have restricted write permissions
Templates and configurations from Linux environments may require path adjustments for Windows compatibility

Configure agents

Agent Control on Windows can currently manage the following agent types:

New Relic infrastructure agent: newrelic/com.newrelic.infrastructure. Supports on-host integrations and log forwarding via the built-in Fluent Bit.
New Relic distribution for OpenTelemetry: newrelic/com.newrelic.opentelemetry.collector

To customize agent local configuration, place a values.yml file in the agent's values directory. The available variables are the same as for Linux hosts.

Sample configurations

Remote configuration with Fleet Control

Infrastructure agent settings with Windows log forwarding. The config_agent with a valid license_key is always mandatory:

config_agent:
  license_key: YOUR_LICENSE_KEY
  custom_attributes:
    env: production
config_logging:
  windows-event-log.yml:
    logs:
      - name: windows-security
        winlog:
          channel: Security
          collect-eventids:
            - 4624
            - 4625
        attributes:
          logtype: windows_security

A valid configuration for Agent Control itself on Windows, showing how to manage agents:

agents:
  nr-infra-agent:
    agent_type: "newrelic/com.newrelic.infrastructure:0.1.0"
  #nr-otel-collector:
  #  agent_type: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"

Value providers

Value providers allow Agent Control resolve values from external sources when a configuration is rendered, so sensitive data such as license keys, tokens, or passwords doesn't need to be hard-coded in your configuration files.

Values are referenced with the ${NAMESPACE:NAME} placeholder syntax inside agent configurations. Agent Control resolves them every time a configuration is applied, including remote configuration updates, so rotated values are picked up without restarting Agent Control.

Important

If Agent Control fails to resolve a value, the configuration rendering fails and the agent isn't started. This prevents agents from running with incomplete or incorrect configurations.

After a successful resolution, Agent Control stores the rendered result in a Kubernetes secret or in a private configuration file for use by the corresponding agent.

Supported value providers

Provider	Placeholder namespace	Requires configuration
Environment variables	`nr-env`	No
HashiCorp Vault	`nr-vault`	Yes
Local files	`nr-file`	No
Kubernetes secrets	`nr-kubesec`	No
Kubernetes ConfigMaps	`nr-kubecm`	No

Configuring value providers

Only HashiCorp Vault requires explicit configuration. Define it under the value_providers key of the Agent Control configuration. The legacy key secrets_providers is still accepted as an alias.

value_providers:
  vault:
    sources:
      local-instance:
        url: http://localhost:8200/v1/
        token: root
        engine: kv2
      remote:
        url: http://my-remote-server:8200/v1/
        token: root
        engine: kv1
    client_timeout: 10s

fleet_control:
  ...

agents:
  ...

Each entry under sources defines a named Vault source with the following settings:

YAML key	Required	Description
`url`	Yes	Full Vault URL, including the `/v1` path.
`token`	Yes	Token used to authenticate against the endpoint.
`engine`	Yes	Secrets engine version: `kv1` or `kv2`.
`client_timeout`	No	HTTP timeout for Vault requests. Defaults to `30s`. Set at the `vault` level, not per source.

Environment variables: `nr-env`

Reads a value from the host environment (available to Agent Control process).

config_agent:
  license_key: "${nr-env:NEW_RELIC_LICENSE_KEY}"

HashiCorp Vault: `nr-vault`

Reads a key from a Vault KV secret. Requires the value_providers.vault configuration described above.

The placeholder uses this format:

"${nr-vault:SOURCE_NAME:MOUNT:PATH:KEY}"

SOURCE_NAME: name of the Vault source defined in value_providers.
MOUNT: name of the secrets engine mount.
PATH: path to the secret.
KEY: key within the secret to retrieve.

For example:

config_agent:
  enable_process_metrics: true
  custom_attributes:
    username: "${nr-vault:local-instance:secret:my_secret:username}"
    organization: "${nr-vault:remote:my_mount:my_path:organization}"

Here, ${nr-vault:local-instance:secret:my_secret:username} retrieves the value of the username key from the secret at secret/my_secret using the local-instance source, and ${nr-vault:remote:my_mount:my_path:organization} retrieves the organization key from the remote source.

Local files: `nr-file`

Reads the contents of a local file, trimming leading and trailing whitespace.

The placeholder takes the absolute path to the file:

config_agent:
  license_key: "${nr-file:/etc/newrelic/license.key}"

Kubernetes secrets: `nr-kubesec`

Reads a key from a Kubernetes secret. Available on Kubernetes only, and requires no additional configuration as long as the Agent Control pod has permissions, through a service account and RBAC, to access the required secrets and namespaces.

The placeholder uses this format:

"${nr-kubesec:NAMESPACE:SECRET_NAME:KEY}"

NAMESPACE: namespace where the secret is located.
SECRET_NAME: name of the Kubernetes secret object.
KEY: key within the secret to retrieve.

Kubernetes ConfigMaps: `nr-kubecm`

Reads a key from a Kubernetes ConfigMap. Available on Kubernetes only, and requires no additional configuration as long as the Agent Control pod has permissions to access the required ConfigMaps and namespaces.

The placeholder uses this format:

"${nr-kubecm:NAMESPACE:CONFIGMAP_NAME:KEY}"

NAMESPACE: namespace where the ConfigMap is located.
CONFIGMAP_NAME: name of the Kubernetes ConfigMap object.
KEY: key within the ConfigMap to retrieve.

Important

Tip

Understanding the two layers of configuration.css-21sua1{background:none;border:none;width:0;padding:0;}

Kubernetes configuration

Local values.yaml configuration for Kubernetes

Remote configuration for Kubernetes

Tip

Sample configurations: Agent Control on Kubernetes

Agent Control with New Relic infrastructure and Fluent Bit

Local config for infrastructure and Fluent Bit

Agent Control with OpenTelemetry and custom collector settings

Important

OpenTelemetry configuration

Sample configurations: Remote Agent Configurations on Kubernetes

Remote configuration: New Relic infrastructure

Infrastructure remote configuration

Remote configuration: Fluent Bit

Fluent Bit configuration

Remote configuration: Prometheus

Prometheus configuration

Remote configuration: OpenTelemetry

Important

OpenTelemetry remote configuration

Proxy configuration for Kubernetes

Proxy precedence

Proxy configuration with self-signed certificates

Kubernetes proxy configuration example

Proxy configuration for managed agents

Caution

Secrets management

Private repository configuration

Caution

1. Enable private repositories for agents

Enable private repositories

2. Set up authentication for private repositories

Basic authentication

TLS certificate authentication

Linux configuration

Configure the agents

Tip

Sample configurations

Remote Configuration with Fleet Control

Infrastucture agent, on-host integrations, and log forwarder (built-in FluentBit)

New Relic OTel collector

New Relic Agent Control

Windows configuration

Tip

Windows-specific configuration notes

Configure agents

Sample configurations

Remote configuration with Fleet Control

Infrastructure agent with log forwarding

Agent Control configuration

Value providers

Important

Supported value providers

Configuring value providers

Environment variables: nr-env

HashiCorp Vault: nr-vault

Local files: nr-file

Kubernetes secrets: nr-kubesec

Kubernetes ConfigMaps: nr-kubecm

Understanding the two layers of configuration

Local `values.yaml` configuration for Kubernetes

Environment variables: `nr-env`

HashiCorp Vault: `nr-vault`

Local files: `nr-file`

Kubernetes secrets: `nr-kubesec`

Kubernetes ConfigMaps: `nr-kubecm`