--- title: Agent types source: https://docs.newrelic.com/docs/new-relic-control/agent-control/agent-types --- > #### ⚠️ IMPORTANT > > Agent Control and New Relic Control are **generally available** for Kubernetes. Support for Linux and Windows hosts is in **public preview** program, pursuant to our [pre-release policies](https://docs.newrelic.com/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy). 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`, ...). ## Metadata The metadata section identifies the agent type: its `name`, `namespace`, `version`, target `platform` (`host` or `kubernetes`), and `operating_system` (required for host-based types). Agent Control uses these fields to uniquely address the definition and dispatch it to the correct deployment engine. ## 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}`. ## Deployment 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. For the full schema reference and all available fields, see [Agent type schema reference](https://github.com/newrelic/newrelic-agent-control/blob/main/docs/agent_type.md). ### 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. > #### ⚠️ IMPORTANT > > Without Flux, a configuration change from Fleet Control only updates the `ConfigMap`/`Secret` object it manages. Agent Control doesn't restart or redeploy the agent for you. ### 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`**: the list of processes Agent Control will start, monitor, and restart. An agent type without this section is treated as a managed integration (OHI): Agent Control handles its artifacts but delegates execution to another agent. - **`enable_file_logging`**: whether file logging is enabled. - **`health`**: how Agent Control determines whether the agent is healthy — via process presence, an HTTP endpoint check, or both. - **`filesystem`**: individual files or directories that Agent Control writes to the host before starting the agent, such as configuration files or certificates. - **`shared_filesystem`**: entries written into a shared drop zone accessible to other agents managed by the same Agent Control instance. Used by OHI agent types to hand their configuration and binaries to the Infrastructure Agent. - **`packages`**: OCI artifacts to download before the agent starts — typically the agent binary or integration package. ## 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. ### On-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. | OS | Path | | ------- | ----------------------------------------------------------------------- | | Linux | `/var/lib/newrelic-agent-control/filesystem/` | | Windows | `C:\ProgramData\New Relic\newrelic-agent-control\filesystem\` | 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`. Example ``` /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`. | OS | Path | | ------- | ------------------------------------------------------------------- | | Linux | `/var/lib/newrelic-agent-control/shared-filesystem` | | Windows | `C:\ProgramData\New Relic\newrelic-agent-control\shared-filesystem` | Since all sub-agents have access to that shared directory, they can see each other's files. Example ``` /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 Two agent types are **linked** when one writes artifacts (configuration, binaries, or other files) into the shared filesystem and the other is configured to read from those same paths. The writer may have no `executables` section, Agent Control manages its artifacts but never starts a process for it. Instead, the reader agent has the built-in logic to discover and execute binaries and configurations from a well-known path in the shared filesystem, effectively running the add-on on the writer's behalf. 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. ### The Infrastructure Agent and OHI agent relationship 1. When an OHI agent type is installed, Agent Control downloads the integration binary via OCI and writes two entries into the shared filesystem: - A config file under `infra-agent-ohi-configs/` (e.g. `nri-redis.yaml`) - The integration binary under `infra-agent-ohi-binaries/` (e.g. `nri-redis`) 2. The Infrastructure Agent sub-agent is configured with environment variables that point it at these shared directories: | Variable | Shared filesystem path | Purpose | | ------------------------------------- | ---------------------------- | ----------------------------- | | `NRIA_PLUGIN_DIR` | `…/infra-agent-ohi-configs` | Integration config discovery | | `NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR` | `…/infra-agent-ohi-binaries` | Integration binary discovery | | `NRIA_SAFE_BIN_DIR` | `…/infra-agent-ohi-binaries` | Allowed binary execution path | 3. The Infrastructure Agent picks up the config and binary on its next scan cycle and begins running the integration. ``` 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 ``` > #### ⚠️ IMPORTANT > > OHI agent types have no process of their own and depend entirely on the Infrastructure Agent to > execute. You must have `com.newrelic.infrastructure` configured as a sub-agent in the same Agent > Control instance before deploying any OHI agent type. ## 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](https://docs.newrelic.com/docs/new-relic-control/agent-control/mirror-setup). ## Supported agent types ### Current support The following table shows which agent types Agent Control supports and their availability across environments. | Agent type | Kubernetes support | Linux host support | Windows host support | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------ | -------------------- | | [**New Relic infrastructure agent**](https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/new-relic-guided-install-overview/) | ✅ Yes | Public Preview | Public Preview | | [**Apache**](https://docs.newrelic.com/install/apache/) | ✅ Yes | Public Preview | Public Preview | | [**Flex**](https://docs.newrelic.com/docs/infrastructure/host-integrations/host-integrations-list/flex-integration-tool-build-your-own-integration/) | ✅ Yes | Public Preview | Public Preview | | [**Memcached**](https://docs.newrelic.com/install/memcached/) | ✅ Yes | Public Preview | Public Preview | | [**MySQL**](https://docs.newrelic.com/install/mysql/) | ✅ Yes | Public Preview | Public Preview | | [**NGINX**](https://docs.newrelic.com/install/nginx/) | ✅ Yes | Public Preview | Public Preview | | [**PostgreSQL**](https://docs.newrelic.com/install/postgresql/) | ✅ Yes | Public Preview | Public Preview | | [**Redis**](https://docs.newrelic.com/docs/infrastructure/host-integrations/host-integrations-list/redis/redis-integration/) | ✅ Yes | Public Preview | Public Preview | | [**New Relic OpenTelemetry Collector (NRDOT)**](https://docs.newrelic.com/docs/opentelemetry/nrdot/nrdot-intro/) | ✅ Yes | ✅ Yes | ⚠️ Experimental | | [**Fluent Bit**](https://docs.newrelic.com/docs/logs/forward-logs/forward-your-logs-using-infrastructure-agent/) | ✅ Yes | 🚫 No | 🚫 No | | [**New Relic Prometheus agent**](https://docs.newrelic.com/docs/infrastructure/prometheus-integrations/get-started/send-prometheus-metric-data-new-relic/) | ✅ Yes | 🚫 No | 🚫 No | | [**New Relic eBPF agent**](https://docs.newrelic.com/docs/ebpf/overview/) | ✅ Yes | ⚠️ Experimental | 🚫 No | | [**APM agents (.NET, Java, Node, Python, Ruby)**](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/introduction-apm/) | 🚫 No | 🚫 No | 🚫 No | > #### ⚠️ IMPORTANT > > Agent-specific permissions: Agent Control is designed to provide you with flexible permissions management. While Agent Control itself requires a certain level of access to function, the permissions it grants to individual agents are tailored to their specific needs. Below, you can find a breakdown of the permissions required for each agent type. ## Required permissions per agent type The following table lists the key permissions each agent type requires and the environments where it applies. | Agent type | Key permissions required | Environment | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | **New Relic infrastructure agent** | Host-level access for system metrics and Kubernetes API access for cluster data. | Kubernetes / host-based | | **Apache** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **Flex** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **Memcached** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **MySQL** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **NGINX** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **PostgreSQL** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **Redis** | Executed by infra-agent with the same permissions. | Kubernetes / host-based | | **New Relic OpenTelemetry Collector (NRDOT)** | Permissions depend on specific receivers and exporters. Often requires Kubernetes API access for service discovery. | Kubernetes / host-based | | **Fluent Bit** | Read access to pod and container logs. | Kubernetes | | **New Relic Prometheus agent** | Permissions to discover and access service endpoints within the cluster for scraping metrics. | Kubernetes | | **New Relic eBPF agent** | Elevated privileges (for example, `CAP_SYS_ADMIN`) to load eBPF programs on the host kernel. | Kubernetes, Linux hosts (experimental) | | **APM agents (.NET, Java, Node, Python, Ruby)** | _Not currently supported by Agent Control._ | N/A | > #### ⚠️ NRDOT ON WINDOWS HOSTS IS EXPERIMENTAL > > The New Relic OpenTelemetry Collector (NRDOT) on Windows is available but not officially tested or documented by the NRDOT team. The default bundled configuration is designed for Linux and may produce warnings or errors on Windows (for example, from `filelogreceiver` paths). No default configuration is bundled for Windows — you must supply your own collector configuration. Use NRDOT on Windows only in non-critical or testing environments. > #### ⚠️ EBPF ON LINUX HOSTS IS EXPERIMENTAL > > The New Relic eBPF agent requires kernel-level dependencies (such as `linux-headers` matching the running kernel version) that Agent Control cannot automatically resolve on Linux hosts. If these dependencies are missing or mismatched, deployment may fail without a clear error. eBPF support on Linux hosts is available for Kubernetes environments only in production. Use eBPF on Linux hosts only in non-critical or testing environments. > > eBPF is **not supported** on Windows hosts. ## Configuring Fluent Bit on hosts On hosts, Fluent Bit isn't deployed as its own top-level agent type (see the support table above). Instead, when log forwarding is enabled, Fluent Bit is spawned and managed by the **New Relic infrastructure agent** itself, the same way as when it's installed standalone. Agent Control only changes _where_ the infrastructure agent, its data, and the Fluent Bit binary and plugin live on disk. For how to configure log forwarding itself (`logging.d/*.yml` syntax, inputs, filters, attributes, and so on), see: - [Enable log management](https://docs.newrelic.com/docs/logs/forward-logs/enable-log-management-new-relic) - [Forward logs with Fluent Bit](https://docs.newrelic.com/docs/logs/forward-logs/logs-fluent-bit) ### Where to put your configuration The only Agent-Control-specific detail is where log forwarding files go: they land in the sub-agent's `logging.d` folder, one entry per log source, via the `config_logging` field of the infrastructure agent's config. Set it directly in the sub-agent's config (for example, its `local_config.yaml`) and send that to Agent Control: ```yaml 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 ``` ### Where Fluent Bit lives, and how it's updated | OS | Details | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Linux | Installed by your distro's package manager as a dependency of the agent-control package, so it's updated the same way as any other OS package, independently of Agent Control and infrastructure agent version bumps. | | Windows | Ships bundled with the infrastructure agent. It's updated whenever Agent Control updates the infrastructure agent — there's nothing separate to install or upgrade. |