Configuration

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.

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.

Here's an example 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"

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

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.

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

Agent Control uses Kubernetes ConfigMaps to store and apply configuration settings. If both local and remote configurations are present, remote configuration takes precedence by default. To intentionally override remote settings and fall back to local configuration, you can deploy an empty remote configuration via Fleet Control. Keep in mind that this change will apply to all clusters in the selected fleet.

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

Sample configurations

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.

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: "*"

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

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

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

중요

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

Agent Control supports proxy configuration to route traffic through corporate proxies or network intermediaries. The proxy configuration 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 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

주의

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.

중요

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.

주의

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

Agent Control configuration

Sample configurations

New Relic infrastructure and Fluent Bit

Local config for infrastructure and Fluent Bit

OpenTelemetry with custom collector settings

OpenTelemetry configuration

Remote configuration: New Relic infrastructure

Infrastructure remote configuration

Remote configuration: Fluent Bit

Fluent Bit configuration

Remote configuration: Prometheus

Prometheus configuration

Remote configuration: OpenTelemetry

Prometheus configuration

중요

Proxy configuration

Proxy precedence

중요

Proxy configuration with self-signed certificates

Kubernetes proxy configuration example

Proxy configuration for managed agents

주의

Secrets management

Defining Secrets in Configuration

중요

Using Secrets in an Agent Configuration

Vault secrets

Kubernetes secrets

Private repository configuration

주의

1. Enable private repositories for agents

Enable private repositories

2. Set up authentication for private repositories

Basic authentication

TLS certificate authentication

Configuration

preview

Sample configurations.css-21sua1{background:none;border:none;width:0;padding:0;}

New Relic infrastructure and Fluent Bit

Local config for infrastructure and Fluent Bit

OpenTelemetry with custom collector settings

OpenTelemetry configuration

Remote configuration: New Relic infrastructure

Infrastructure remote configuration

Remote configuration: Fluent Bit

Fluent Bit configuration

Remote configuration: Prometheus

Prometheus configuration

Remote configuration: OpenTelemetry

Prometheus configuration

Proxy configuration

Proxy precedence

중요

Proxy configuration with self-signed certificates

Kubernetes proxy configuration example

Proxy configuration for managed agents

주의

Secrets management

Defining Secrets in Configuration

중요

Using Secrets in an Agent Configuration

Vault secrets

Kubernetes secrets

Private repository configuration

주의

1. Enable private repositories for agents

Enable private repositories

2. Set up authentication for private repositories

Basic authentication

TLS certificate authentication

Sample configurations