newrelic-agent-control

Agent Control Configuration

Agent control will load the configuration from the file local_config.yaml in the corresponding directory (/etc/newrelic-agent-control/local-data/agent-control/ or /opt/homebrew/var/lib/newrelic-agent-control/local-data/agent-control/).

Additionally, any configuration field can be set as an environment variable with the NR_AC prefix, using __ to separate keys. Examples:

# Set log level to debug
NR_AC_LOG__LEVEL=DEBUG
# Set 'client_id' for the authentication config in the Fleet Control communication
NR_AC_FLEET_CONTROL__AUTH_CONFIG__CLIENT_ID="some-client-id"

Environment Variables file (on-host)

Agent Control can load environment variables from a YAML file named environment_variables.yaml placed in the local configuration directory (/etc/newrelic-agent-control/, C:\Program Files\New Relic\newrelic-agent-control\).

Format: the file must be a flat YAML map of string keys to string values.

# Example environment variables file
MY_ENV_VAR: "env var value"
HTTPS_PROXY: "http://proxy.local:8443"
NR_AC_LOG__LEVEL: "DEBUG"

Validation rules:

Keys must match the regex ^[A-Za-z_][A-Za-z0-9_]*$ (letters, digits, and underscore; must start with a letter or underscore).
Values must not contain NUL (\0) characters.
Invalid entries cause startup to fail with an error.

Notes:

This file is not watched; changes require restarting Agent Control.
Use the NR_AC_* variables to override configuration fields via environment variables.
Variables will be inherited by the Agents processes.

Configuration fields

agents

List of agents configured locally. Check of DEVELOPMENT for more information regarding agents and their corresponding local configuration.

Example:

agents:
  nrdot: "newrelic/com.newrelic.opentelemetry.collector:0.1.0"

logs

Logs can be configured as follows:

log:
  format:
    target: true # Defaults to false, includes extra information for debugging purposes
    timestamp: "%Y-%m-%dT%H:%M%S" # Defaults to "%Y-%m-%dT%H:%M%S", details in <https://docs.rs/chrono/0.4.40/chrono/format/strftime/index.html#fn7>
    ansi_colors: true # Defaults to false, set up ansi-colors in the stderr logs output.
    formatter: json # Defaults to "json". It accepts "json" (newline delimited JSON logs) or "pretty" (human-readable, single-line logs)
  level: debug # Defines the log level, defaults to "info".
  insecure_fine_grained_level: debug # Enables logs for external dependencies and sets its level. This cannot be considered secure since external dependencies may leek secrets. If this is set the 'level' field does not apply.
  file:
    enabled: true # Enabled logging to files.
    path: /some/path/logs.log # Optional path to write logs to, if not set it will use 'newrelic-agent-control.log' in the application logging directory.
  show_spans: false # Show spans information as logs. It includes additional details which may be useful for debugging purposes.

Notice that rotation and retention cannot be configured and is fixed to be daily with 30 days of retention.

fleet_control

This configuration field enables and sets up the remote configuration features of Agent Control.

fleet_control:
  endpoint: https://opamp.service.newrelic.com/v1/opamp # Fleet control endpoint.
  auth_config:
    token_url: https://system-identity-oauth.service.newrelic.com/oauth2/token # Endpoint to obtain access token
    client_id: "some-client-id" # Auth client id associated with the private key
    provider: "local" # Local auth provider which will load the provided key from 'private_key_path'
    private_key_path: "/private/key/path" # Path to the private key corresponding to the client-id.
    retries: 3 # Number of retries if the authentication fails.
  fleet_id: "some-id" # Fleet identifier.
  signature_validation:
    enabled: true # Defaults to true, allows disabling the signature validation.
    public_key_server_url: "https://publickeys.newrelic.com/signing/blob-management/global/agentconfiguration" # Server to obtain the public key for signature validation.

proxy

Agent Control will use the system proxy (configured through the standard HTTP_PROXY / HTTPS_PROXY environment variables) but proxy options can also be configured using the proxy configuration field. If both are set, the precedence works as follows:

proxy configuration field
HTTP_PROXY environment variable
HTTPS_PROXY environment variable

proxy:
  url: https://proxy.url:8080 # Proxy url in format '<protocol>://<user>:<password>@<host>:<port>'
  ca_bundle_dir: /some/dir # System path with CA certificates in PEM format (all '.pem' files in the directory will be read).
  ca_bundle_file: /some/pem/file # System path with CA certificates in PEM format.
  ignore_system_proxy: false # Default to false, if set to true HTTP_PROXY and HTTPS_PROXY environment variables will be ignored.

⚠️ Proxy configuration for 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.

The only exception is the infrastructure agent, which will inherit the proxy settings from Agent Control whenever the configuration is generated via the Cli.

server

Agent Control status server allows consulting the status of Agent Control and any controlled agent. It can be configured as follows:

server:
  port: 51200 # Port for the status server. Defaults to 51200.
  host: "127.0.0.1" # Host for the status server. Defaults to '127.0.0.1'.
  enabled: true # The status server is enabled by default

health_check

Configuration fields to set-up Agent Control health-check

health_check:
  interval: 120s # Defaults to 30s
  initial_delay: 120s # Defaults to 30s

self_instrumentation

Agent Control can be configured to instrument itself and report logs and metrics through OpenTelemetry. If proxy is configured globally it will also apply to self-instrumentation.

self_instrumentation:
  opentelemetry:
    insecure_level: "newrelic_agent_control=info,off" # It is considered insecure because setting it up for external dependencies could potentially leak secrets. The default `newrelic_agent_control=debug,opamp_client=debug,off` disables external dependencies and can be considered secure.
    endpoint: https://otlp.nr-data.net:4318 # HTTPS endpoint to report instrumentation to.
    headers:  # Headers that will be included in any request to the endpoint
      api-key: LICENSE_KEY # This header is required to send data to NR 
    client_timeout: 10s # Timeout for performing requests, defaults to 30s.
    custom_attributes: {} # Attributes to be decorated in all metrics and logs
    metrics:
      enabled: true # Defaults to false.
      interval: 120s # Interval to report metrics, it defaults to 60s.
    logs:
      enabled: true # Defaults to false.
      batch_config:
        scheduled_delay: 30s # Set the scheduled delay for batch export of logs. Defaults to 30s.
        max_size: 512 # Se the maximum number of logs to process in a single batch. Defaults to 512.

host_id

If the host_id is set it will be used to identify the host in Fleet Control instead of trying to fetch the identifier from the host where Agent Control is running. Order of precedence:

Configured host_id.
Cloud instance id.
Machine id.

This applies for on-host environments only:

host_id: "some-host-id" # Defaults to "" (no host set).

k8s

The k8s configuration field applies for k8s environments only and are automatically set up through the corresponding helm chart:

k8s:
  cluster_name: "some-cluster-name" # Required, used to identify the cluster in Fleet Control.
  namespace: "default" # Required, namespace where all resources managed by Agent Control will be created.
  namespace_agents: "default-agents" # Required, namespace where all sub-agents managed by Agent Control will be created.
  current_chart_version: "0.0.50-dev" # Chart version used to deploy agent-control, it will be reported to Fleet Control and used to check if a remote update should be applied.
  ac_remote_update: true # When disabled remote updates for Agent Control are ignored.
  ac_release_name: agent-control-deployment # Informs of the 'Agent Control' release name that needs to be updated on remote updates and when checking health. If it is empty, the healthiness of Agent Control will not be checked.
  cd_remote_update: true # When disabled remote updates for the Agent Control CD are ignored. Besides, the health of this component is not checked.
  cd_release_name: agent-control-cd  # Informs of the 'Agent Control CD' release name that needs to be updated on remote updates and when checking health. If it is empty, the healthiness of Agent Control CD will not be checked.

Notice that some of the fields in k8s are passed by the corresponding helm chart via Environment Variable to avoid race conditions. If set via config, after a failed upgrade we could have the “old” pod loading the new config and reading the new chart version, while the image is still the old one.

value_providers

The value_providers configuration field sets the configuration for the supported value providers. Users can use the values stored in secrets in their remote configurations. The legacy key secrets_providers is still accepted as an alias for backward compatibility. See all possible providers

vault

Reads values from a HashiCorp Vault KV secret. Multiple named sources can be defined to target different Vault clusters or engine versions.

value_providers:
  vault:
    sources:
      <source-name>:
        url: <vault-url-including-/v1>   # required
        token: <vault-token>             # required
        engine: kv1 | kv2               # required
    client_timeout: <duration>           # optional (default: 30s)

Field	Required	Description
`sources`	Yes	Map of named Vault sources
`sources.<name>.url`	Yes	Full Vault URL including `/v1` path
`sources.<name>.token`	Yes	Vault token for authentication
`sources.<name>.engine`	Yes	Secret engine version: `kv1` or `kv2`
`client_timeout`	No	HTTP timeout for Vault requests (default `30s`)

azure_key_vault

Reads secret values from one or more Azure Key Vault instances. Multiple named sources can be defined to target different vaults or use different authentication methods.

value_providers:
  azure_key_vault:
    sources:
      <source-name>:
        vault_url: <azure-key-vault-url>   # required
        auth:                              # optional (default: managed_identity)
          type: managed_identity
          # or:
          # type: service_principal
          # tenant_id: <tenant-id>
          # client_id: <client-id>
          # client_secret: <client-secret>
    client_timeout: <duration>             # optional (default: 30s)

Field	Required	Description
`sources`	Yes	Map of named Azure Key Vault sources
`sources.<name>.vault_url`	Yes	Azure Key Vault endpoint URL (e.g. `https://my-vault.vault.azure.net/`)
`sources.<name>.auth.type`	No	Authentication method: `managed_identity` (default) or `service_principal`
`sources.<name>.auth.tenant_id`	If `service_principal`	Azure tenant (directory) ID
`sources.<name>.auth.client_id`	If `service_principal`	Service principal application (client) ID
`sources.<name>.auth.client_secret`	If `service_principal`	Service principal client secret
`client_timeout`	No	HTTP timeout for all sources (default `30s`)

aws_secrets_manager

Reads secret values from one or more AWS Secrets Manager regions or accounts. Multiple named sources can be defined to target different regions or use different authentication methods.

value_providers:
  aws_secrets_manager:
    sources:
      <source-name>:
        region: <aws-region>               # required
        endpoint: <url>                    # optional (default: https://secretsmanager.<region>.amazonaws.com/)
        auth:                              # optional (default: instance_profile)
          type: instance_profile
          # or:
          # type: access_key
          # access_key_id: <access-key-id>
          # secret_access_key: <secret-access-key>
    client_timeout: <duration>             # optional (default: 30s)

Field	Required	Description
`sources`	Yes	Map of named AWS Secrets Manager sources
`sources.<name>.region`	Yes	AWS region of the secrets (e.g. `us-east-1`)
`sources.<name>.endpoint`	No	Overrides the regional endpoint, e.g. to use a VPC endpoint
`sources.<name>.auth.type`	No	Authentication method: `instance_profile` (default) or `access_key`
`sources.<name>.auth.access_key_id`	If `access_key`	AWS access key id
`sources.<name>.auth.secret_access_key`	If `access_key`	AWS secret access key
`client_timeout`	No	HTTP timeout for all sources (default `30s`)

self_update

Configures the on-host self-update mechanism.

self_update:
  enabled: false # Defaults to false. When true, Agent Control will attempt to self-update when Fleet Control pushes a new version.
  signature_verification_enabled: true # Defaults to true. When false, package signature verification is skipped (not recommended for production).
  package:
    download:
      oci:
        repository: "newrelic/agent-control-artifacts" # OCI repository for Agent Control packages.
        public_key_url: "https://..." # JWKS endpoint used to verify package signatures.

agent_packages

This field configures packages behaviour.

agent_packages:
  signature_verification_enabled: # Optional, enabled by default, sets whether packages signatures will be verified or not, when set to false a warning is logged

oci

The oci configuration field sets the OCI registry used to pull packages.

oci:
  registry: "docker.io" # OCI registry hostname or URL. Defaults to "docker.io".
  auth: # Optional authentication for the registry (defaults to Anonymous authentication). If set, specify exactly one of 'basic' or 'bearer'.
    basic:
      username: "my-user" # Username for basic authentication.
      password: "my-pass" # Password for basic authentication.
    # bearer:
    #   token: "my-token" # Token for bearer authentication.

This site is open source. Improve this page.