Tipos de agentes

Agent Control itself has no built-in knowledge of any particular agent. It doesn't know how to start the Infrastructure Agent, render an OpenTelemetry Collector config, or discover a Redis integration binary. An agent type definition is what teaches it. It's a YAML file that describes how Agent Control should identify, download, configure, and run one kind of agent, on one platform. This is what lets it manage a growing catalog of agents without a code change every time a new one is added.

The sub-agent is a named instance of that definition, for example nr-infra-agent referencing newrelic/com.newrelic.infrastructure:0.1.0. That's what you actually add, remove, or reconfigure. Agent Control turns that into the runtime artifacts the definition describes, for example a process and its files on a host or Kubernetes objects on a cluster, and keeps them in sync whenever the sub-agent's configuration changes.

Every agent type definition consists of three main sections: metadata, variables, and deployment, plus a top-level protocol_version field that versions the schema language the file is written against.

Protocol version

protocol_version is a top-level field that declares the version of the agent-type. It is decoupled from both the agent type version (the definition's semver) and the Agent Control release version.

It is a quoted MAJOR.MINOR string (e.g. "1.0").

It is parsed and validated on its own, before the rest of the document is interpreted, so it can gate files whose metadata or other sections use a shape this Agent Control would not otherwise understand. Each Agent Control release understands a single maximum protocol version, and the protocol_version is treated as a single ordered MAJOR.MINOR value. The compatibility rules are:

• Newer than supported (higher major, or same major with a higher minor): rejected — the file is newer than this Agent Control understands.
• Equal to or older than supported: accepted — Agent Control understands every protocol version up to and including the supported one.

For example, an Agent Control supporting 1.6 accepts everything up to 1.6 (including 0.9 and 1.0..=1.6) and rejects anything newer (1.7, 2.0, ...).

Metadatos

La sección de metadatos identifica el tipo de agente: su name, namespace, version, platform objetivo (host o kubernetes) y operating_system (necesario para los tipos basados en host). Agent Control utiliza estos campos para direccionar de forma exclusiva la definición y enviarla al motor de despliegue correcto.

Variables

The variables section declares the configurable inputs that operators can set when adding a sub-agent to their configuration. Each variable has these fields:

• description: a human-readable explanation of the variable.
• type: the data type this variable accepts, such as string, bool, number, yaml, or string_map.
• required: whether operators must set the variable (when set to false, Agent Control fallbacks to the value in default).
• default (optional): the value used when required is false and the operator doesn't set one.
• classification (optional): a label describing the kind of value the variable holds, such as config or multi-config. Agent Control accepts and ignores this field; it's read by Fleet Control to drive how the variable is presented to operators.
• deprecated (optional): marks the variable as deprecated (deprecated: true). Agent Control accepts and ignores this field too — it carries no runtime behavior and doesn't affect resolution, validation, or defaults.

Variables are referenced throughout the deployment section using ${nr-var:variable_name}.

Despliegue

The deployment section describes how Agent Control installs and runs the agent. Its shape is entirely different depending on the target platform declared in the agent type's metadata.

Para obtener la referencia completa del esquema y todos los campos disponibles, consulte la Referencia del esquema de tipo de agente.

Deployment on Kubernetes

On Kubernetes, Agent Control manages Kubernetes objects. The deployment section is composed of:

• objects: the Kubernetes objects Agent Control creates and keeps up to date.
• health: an explicit list of checks, each targeting one Kubernetes resource by name, namespace, and kind.

How Agent Control renders objects depends on whether Flux is enabled:

• With Flux (default, or with an existing Flux installation): agent types declare a HelmRelease object. Agent Control renders your configuration variables into that HelmRelease's Helm chart values and creates or updates the resource. Flux then reconciles the chart and creates the underlying Deployment, ConfigMap, Secret, and other resources.
• Without Flux: agent types declare plain Kubernetes objects directly (for example a ConfigMap, Secret, or Deployment) instead of a HelmRelease. Agent Control applies those objects to the cluster itself. There's no Helm chart or Flux reconciliation involved. The user has to manage the agent lifecycle in that case.

Deployment on-host (Linux and Windows)

On hosts, Agent Control installs and runs the agent directly on the machine's operating system. The deployment section is composed of several sub-sections:

• executables: la lista de procesos que Agent Control iniciará, supervisará y reiniciará. Un tipo de agente sin esta sección se trata como una integración administrada (OHI): Agent Control maneja sus artefactos, pero delega la ejecución a otro agente.
• enable_file_logging: whether file logging is enabled.
• health: cómo Agent Control determina si el agente está en buen estado —mediante la presencia del proceso, una comprobación de extremo HTTP o ambos.
• filesystem: archivos o directorios individuales que Agent Control escribe en el host antes de iniciar el agente, como archivos de configuración o certificados.
• shared_filesystem: entradas escritas en una zona de depósito compartida accesible para otros agentes gestionados por la misma instancia de Agent Control. Utilizado por los tipos de agente OHI para entregar su configuración y binarios al agente de infraestructura.
• packages: artefactos de OCI para descargar antes de que se inicie el agente —por lo general, el binario del agente o el paquete de integración.

Agent state storage

On Kubernetes

State lives as Kubernetes objects, but what those objects are depends on whether Flux is enabled.

With Flux (default, or with an existing Flux installation), the agent type typically declares Flux custom resources like a HelmRepository pointing at the chart, and a HelmRelease holding your rendered configuration as Helm chart values. Agent Control doesn't create the agent's Deployment, ConfigMap, or Secret objects directly. It hands the HelmRelease to Flux, and Flux installs the chart and keeps those generated resources in sync with it.

• A configuration update patches the HelmRelease in place. Agent Control only re-applies the object if its content changed. Flux then reconciles the chart to match.
• Removing a sub-agent deletes every object labeled as owned by it — its HelmRelease, HelmRepository, and any Secret or ConfigMap created for it, and Flux/Helm finalizes cleanup of the workloads that chart had installed.

Without Flux, there's no HelmRelease or HelmRepository. The agent type declares plain Kubernetes objects directly, and Agent Control creates and updates them itself. There's no Helm chart or Flux reconciliation. In this mode, the user is responsible for the agent lifecycle. Agent Control doesn't install or upgrade the agent's Deployment, it only keeps the configuration objects it manages in sync.

• A configuration update patches the managed object (ConfigMap/Secret) in place. Agent Control only re-applies it if its content changed. Since there's no Flux reconciliation, nothing automatically restarts the agent to pick up the change unless the agent itself watches for it.
• Removing a sub-agent deletes every object labeled as owned by it — just its ConfigMap/Secret objects, since there's no HelmRelease, HelmRepository, or chart-installed workload to clean up.

En el host

On-host filesystem

Every sub-agent gets a dedicated directory on disk where Agent Control writes the files declared by its agent type's filesystem section.

Agent Control gets the content to create a file from variables of type yaml, and the content for multiple files inside a directory from variables of type string_map.

Ejemplo

/var/lib/newrelic-agent-control/filesystem/nr-infra-agent/
├── newrelic-infra.yaml     # content from variable of type `yaml`
└── logging.d/              # content from variable of type `string_map`
    ├── file1.yaml
    └── file2.yaml

How this directory behaves depends on the lifecycle event and on the variable type behind each path:

• A restart doesn't touch the directory. Agent Control doesn't rewrite anything unless the restart was triggered by a configuration update from Fleet Control.
• A configuration update rewrites yaml files in place, but fully regenerates string_map directories. For a yaml content, Agent Control only rewrites the file's contents. For a string_map content, Agent Control deletes the whole directory (like logging.d above) and recreates it from scratch, so any file you (or the sub-agent) added or edited inside it disappears on the next write.
• Files Agent Control doesn't manage are left alone. It only ever overwrites the exact paths the agent type declares; anything else the running agent creates on its own inside its directory (cache files, local state) is not touched.
• Removing a sub-agent removes its whole directory, including any files created by the sub-agent itself or by a user.

On-host shared filesystem

Most agent types are self-contained: Agent Control writes their configuration into a directory that belongs to them alone, and starts a process that reads from it. But some integrations have no execution model of their own. There is no process for Agent Control to start. They depend entirely on another already-running agent (for example, the Infrastructure Agent) to pick up their files and execute them. That dependency is why a second, shared location exists. It's a common drop zone that any sub-agent on the same host can write into and any other sub-agent can read from, used specifically to hand off artifacts between agents rather than to store an agent's own private state.

Use filesystem for anything an agent type's own process needs, and rely on shared_filesystem only when one agent type is deliberately handing files to another, like the on-host integrations described further below.

All sub-agents get a shared directory on disk where Agent Control writes the files declared by its agent type's shared_filesystem.

Since all sub-agents have access to that shared directory, they can see each other's files.

Ejemplo

/var/lib/newrelic-agent-control/shared_filesystem/
├── data/                  # All sub-agents can see `data` and `other-data` folders
│   └── file.yaml
└── other-data/
    └── file2.yaml

The shared directory follows the same rules as the per-agent filesystem directory on restarts, configuration updates, and unmanaged files. The behavior only changes when removing a sub-agent: its files are always removed, since each file is unequivocally owned by the sub-agent that wrote it, but folders are only removed once no other sub-agent is using them.

On-host linked agent types

Dos tipos de agente están vinculados cuando uno escribe artefactos (configuración, binarios u otros archivos) en el sistema de archivos compartido y el otro está configurado para leer desde esas mismas rutas. El escritor puede no tener una sección executables, Agent Control administra sus artefactos, pero nunca inicia un proceso para él. En su lugar, el agente lector tiene la lógica incorporada para descubrir y ejecutar binarios y configuración desde una ruta conocida en el sistema de archivos compartido, lo que ejecuta de manera efectiva el complemento en nombre del escritor.

Subdirectory names are chosen by convention between the linked agent types.

On-host integrations (OHI)

On-host integrations (OHIs) are the primary example of linked agent types. Where a regular sub-agent has a process that Agent Control starts and monitors, an OHI has none. Agent Control only manages its lifecycle (downloading, configuring, upgrading, and uninstalling it), while the Infrastructure Agent discovers and runs its binaries from the shared filesystem on its behalf.

La relación entre el agente de infraestructura y el agente de OHI

1. Cuando se instala un tipo de agente OHI, Agent Control descarga el binario de integración a través de OCI y escribe dos entradas en el sistema de archivos compartido:

   • Un archivo de configuración en infra-agent-ohi-configs/ (por ejemplo, nri-redis.yaml)
   • El binario de integración en infra-agent-ohi-binaries/ (por ejemplo, nri-redis)

2. El subagente del agente de infraestructura se configura con variables de entorno que lo apuntan a estos directorios compartidos:

   Variable	Ruta del sistema de archivos compartido	Objetivo
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	Descubrimiento de configuración de integración
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	Descubrimiento de binarios de integración
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	Ruta de ejecución de binarios permitida

3. El agente de infraestructura recoge la configuración y el binario en su siguiente ciclo de escaneo y comienza a ejecutar la integración.

   shared-filesystem/
   ├── infra-agent-ohi-configs/      # Integration YAML configs (read by NRIA_PLUGIN_DIR)
   │   ├── nri-redis.yaml
   │   └── nri-mysql.yaml
   └── infra-agent-ohi-binaries/     # Integration binaries (read by NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR)
       ├── nri-redis
       └── nri-mysql

   Copia

Fetching agent type definitions

Agent Control fetches agent type definitions from a remote OCI registry, identified by the namespace, name, and version declared in the definition's metadata section, taking into account the environment it's running in (Kubernetes, Linux, or Windows).

By default, Agent Control pulls from docker.io using the newrelic/agent-control-agent-types repository, after verifying the signature against New Relic's public key.

Agent type definitions can be pulled from a mirror, as explained in Configure an OCI registry mirror for Agent Control.

Tipos de agentes admitidos

Soporte actual

La siguiente tabla muestra qué tipos de agente admite Agent Control y su disponibilidad en los distintos entornos.

Permisos requeridos por tipo de agente

La siguiente tabla enumera los permisos clave que requiere cada tipo de agente y los entornos donde se aplica.

Configuración de Fluent Bit en hosts

En los hosts, Fluent Bit no se despliega como su propio tipo de agente de nivel superior (consulte la tabla de compatibilidad anterior). En su lugar, cuando se habilita el reenvío de logs, el propio agente de infraestructura de New Relic genera y administra Fluent Bit, de la misma manera que cuando se instala de forma independiente. Agent Control solo cambia dónde residen en el disco el agente de infraestructura, sus datos y el binario y el plug-in de Fluent Bit.

Para saber cómo configurar el reenvío de logs en sí (sintaxis de logging.d/*.yml, entradas, filtros, atributos, etc.), consulte:

• Activar administración de logs
• Reenvío de logs con Fluent Bit

Dónde colocar su configuración

El único detalle específico de Agent Control es a dónde van los archivos de reenvío de logs: terminan en la carpeta logging.d del subagente, una entrada por fuente de logs, a través del campo config_logging de la configuración del agente de infraestructura. Establézcalo directamente en la configuración del subagente (por ejemplo, su local_config.yaml) y envíelo a Agent Control:

config_logging:
  syslog.yaml: |
    logs:
      - name: syslog
        file: /var/log/syslog
        attributes:
          logtype: linux_syslog
  app.yaml: |
    logs:
      - name: app-log
        file: /var/log/app.log
        attributes:
          service: api
          env: production

Dónde reside Fluent Bit y cómo se actualiza