Managing configurations

preview

We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview program pursuant to our pre-release policies.

Importante

Agent Control currently only supports Kubernetes. The configurations and examples provided in this document are specific to this environment.

Agent Control provides two methods for managing agent configurations:

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.

Dica

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 (e.g., 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"
  userKey: "YOUR_USER_KEY"

# Values related to the agent control's Helm chart release.
# `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
      fleet_id: ""
      auth:
        # New Relic organization ID where agent will connect to.
        organizationId: "YOUR_ORGANIZATION_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.
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # 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:
        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: "*"

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.

callout.warning

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

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"
  userKey: "YOUR_USER_KEY"

# See `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional
      # fleet_id: YOUR_FLEET_ENTITY_GUID
      auth:
        organizationId: "YOUR_ORGANIZATION_ID"
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # 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:
        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
        chart_version: "*"

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

Importante

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/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
      fleet_id: ""
      auth:
        # New Relic organization ID where agent will connect to.
        organizationId: "YOUR_ORGANIZATION_ID"

    # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle%60
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
      agent-operator:
        type: newrelic/com.newrelic.k8s_agent_operator:0.1.0
        content:
          chart_version: "*"
      fluentbit:
        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:
            global:
              lowDataMode: true
      prometheus:
        type: newrelic/com.newrelic.prometheus:0.1.0
        content:
          chart_version: "*"
          chart_values:
            global:
              lowDataMode: true
            newrelic-prometheus-agent:
              config:
                kubernetes:
                  integrations_filter:
                    enabled: false

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.

Importante

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:
  newrelic-prometheus-agent:
    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

Importante

Proxy configuration is currently not compatible with fetching the certificate for signature validation. If you need to setup a proxy, you have these options:

Add a firewall exception to https://newrelic.com so requests to that endpoint can skip the proxy (recommended)
Use a local certificate through fleet_control.signature_validation.certificate_pem_file_path (certificate rotation must be handled manually)
Disable signature validation by setting fleet_control.signature_validation.enabled: false (highly discouraged for security reasons)

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"

agent-control-deployment:
  config:
    agentControl:
      content:
        proxy:
          url: https://proxy-service:8080
    subAgents: {}

  # 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
agent-control-cd:
  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

Cuidado

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 following secret providers:

HashiCorp Vault: referred to as nr-vault in configurations.
Kubernetes Secrets: referred to as nr-kubesec in configurations.

Defining Secrets in Configuration

To utilize secrets, define them within your Agent-Control configuration YAML file by following these steps:

Define the secrets_providers section: Configure your secret providers centrally in this section. Ensure each entry corresponds to a supported provider.
Configure secret sources: For each provider, specify one or more sources. A source includes the necessary configuration details (e.g., URL, token) for Agent control to connect to and retrieve a group of secrets.
Use placeholders in agent configurations: Instead of the actual sensitive data, Use a placeholder string within your agent's configuration. Agent control automatically replaces these placeholders with the retrieved secrets during the rendering process.

Importante

If Agent control fails to retrieve a secret, the configuration rendering will fail, and the agent will not be executed. This is a critical security feature to prevent agents from running with incomplete or incorrect configurations.

The following agent-control configuration example demonstrates how to configure for retrieving secrets from two Vault sources within the secrets_providers section:

secrets_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

fleet_control:
  ...

agents:
  ...

Using Secrets in an Agent Configuration

After the sources are defined, in an agent configuration, you can reference the vault using a specific placeholder syntax with the correct path. Agent control retrieves the secret and uses it to render the final configuration file that the agent is going to use.

Example of agent configuration using vault placeholders:

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}"

In this example:

The placeholder ${nr-vault:local-instance:secret:my_secret:username} instructs Agent control to retrieve the value associated with the key username from the secret at the path secret/my_secret using the local-instance vault source. The placeholder ${nr-vault:remote:my_mount:my_path:organization} similarly retrieves the value for the organization key from the remote source.

After successful retrieval, Agent control renders these secrets from the specified source and path, storing the result in a K8s secret or private config file for use by the corresponding agent.

Vault secrets

Set up the vault sources with the following settings:

YAML key	Description
`url`	URL to request data from
`token`	Used to authenticate to the endpoint.
`engine`	Specify `kv1` or `kv2`.

In the configuration file, each secret stored in Vault can be accessed by setting a placeholder with:

source_name: The name of the Vault source defined in secrets_providers.
mount: The name of the secrets engine mount.
path: The specific path to the secret.
specific key: The specific key within the secret to be retrieved.

Example of full placeholder format:

"${nr-vault:source_name:my_mount:my_path:my_value}"

Kubernetes secrets

If the agent-control pod has permissions, such as through a Service Account and Role-Based Access Control (RBAC), to access the required secrets and namespaces, Agent control can directly access secrets from the Kubernetes API without needing a separate sources configuration.

In the agent configuration file, retrieve each secret value using a placeholder specifying:

namespace: The Kubernetes namespace where the secret is located.
name: The name of the Kubernetes secret object.
specific key: The specific key within the secret from which to retrieve the value.

For example, use the placeholder format:

"${nr-kubesec:my_namespace:my_secret:my_value}"

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.

Cuidado

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 will be allowed in remote configurations. To enable specific repositories, you need to update the Agent Control configuration:

# values-newrelic.yaml

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

# ...

agent-control-deployment:
  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 chart itself is in a private repository. This is separate from the configuration for managed agents. Refer to the agent-control Helm chart values.yaml to set up the installationJob section. Specifically:

chartRepositoryUrl containing your repository URL
name if using a different chart name
repositorySecretReferenceName and repositoryCertificateSecretReferenceName for authentication (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:

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

preview

Importante

Dica

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

callout.warning

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

Importante

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

Importante

OpenTelemetry remote configuration

Proxy configuration for Kubernetes

Proxy precedence

Importante

Proxy configuration with self-signed certificates

Kubernetes proxy configuration example

Proxy configuration for managed agents

Cuidado

Secrets management

Defining Secrets in Configuration

Importante

Using Secrets in an Agent Configuration

Vault secrets

Kubernetes secrets

Private repository configuration

Cuidado

1. Enable private repositories for agents

Enable private repositories

2. Set up authentication for private repositories

Basic authentication

TLS certificate authentication

Understanding the two layers of configuration

Local `values.yaml` configuration for Kubernetes