에이전트 유형

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, ...).

메타데이터

메타데이터 섹션은 에이전트 유형, 즉 name, namespace, version, 타겟 platform (host 또는 kubernetes) 및 operating_system (호스트 기반 유형에 필요)을 식별합니다. 에이전트 컨트롤은 이러한 필드를 사용하여 정의를 고유하게 지정하고 올바른 배포 엔진으로 전달합니다.

변수

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

전개

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.

전체 스키마 참조 및 사용 가능한 모든 필드는 에이전트 유형 스키마 참조를 확인해 주십시오.

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: 에이전트 컨트롤이 시작, 모니터 및 다시 시작할 프로세스 목록입니다. 이 섹션이 없는 에이전트 유형은 관리형 통합(OHI)으로 처리되며, 에이전트 컨트롤은 해당 아티팩트를 처리하지만 실행은 다른 에이전트에 위임합니다.
• enable_file_logging: whether file logging is enabled.
• health: 에이전트 컨트롤이 에이전트의 정상 여부를 결정하는 방법 ― 프로세스 존재 여부, HTTP 엔드포인트 확인 또는 둘 다를 통해 결정합니다.
• filesystem: 설정 파일이나 인증서와 같이 에이전트를 시작하기 전에 에이전트 제어가 호스트에 쓰는 개별 파일 또는 디렉터리입니다.
• shared_filesystem: 동일한 에이전트 컨트롤 인스턴스에서 관리하는 다른 에이전트가 액세스할 수 있는 공유 드롭 존에 기록된 항목입니다. OHI 에이전트 유형이 설정 및 바이너리를 인프라 에이전트에 전달하는 데 사용됩니다.
• packages: 에이전트가 시작되기 전에 다운로드할 OCI 아티팩트 ― 일반적으로 에이전트 바이너리 또는 통합 패키지입니다.

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

예시

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

예시

/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

한 에이전트 유형이 공유 파일 시스템에 아티팩트(설정, 바이너리 또는 기타 파일)를 쓰고 다른 에이전트 유형이 동일한 경로에서 읽도록 설정된 경우 두 에이전트 유형이 연결 됩니다. 작성자에게는 executables 섹션이 없을 수 있으며, 에이전트 컨트롤은 아티팩트를 관리하지만 이를 위한 프로세스를 시작하지는 않습니다. 대신, 리더 에이전트에는 공유 파일 시스템의 잘 알려진 경로에서 바이너리 및 설정을 검색하고 실행하는 기본 제공 로직이 있어 작성자를 대신하여 애드온을 효과적으로 실행합니다.

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.

인프라 에이전트 및 OHI 에이전트 관계

1. OHI 에이전트 유형이 설치되면 Agent Control은 OCI를 통해 통합 바이너리를 다운로드하고 공유 파일 시스템에 두 개의 항목을 기록합니다:

   • infra-agent-ohi-configs/ 아래의 설정 파일(예: nri-redis.yaml)
   • infra-agent-ohi-binaries/ 아래의 통합 바이너리(예: nri-redis)

2. 인프라 에이전트 하위 에이전트는 이러한 공유 디렉터리를 가리키는 환경 변수로 구성됩니다:

   변하기 쉬운	공유 파일 시스템 경로	목적
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	통합 설정 검색
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	통합 바이너리 검색
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	허용된 바이너리 실행 경로

3. 인프라 에이전트는 다음 스캔 주기에서 구성 및 바이너리를 가져와 통합 실행을 시작합니다.

   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

   카피

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.

지원되는 에이전트 유형

현재 지원

다음 표는 에이전트 제어가 지원하는 에이전트 유형과 환경 전반의 가용성을 보여줍니다.

에이전트 유형별 필수 권한

다음 표에는 각 에이전트 유형에 필요한 주요 권한과 해당 권한이 적용되는 환경이 나열되어 있습니다.

호스트에서 Fluent Bit 구성

호스트에서 Fluent Bit는 자체 최상위 에이전트 유형으로 배포되지 않습니다(위의 지원 표 참조). 대신 로그 포워딩이 활성화되면, 독립 실행형으로 설치될 때와 동일한 방식으로 뉴렐릭 인프라 에이전트 자체에서 Fluent Bit를 생성하고 관리합니다. 에이전트 컨트롤은 인프라 에이전트, 해당 데이터, Fluent Bit 바이너리 및 플러그인이 디스크에 상주하는 위치만 변경합니다.

로그 포워딩 자체(logging.d/*.yml 구문, 입력, 필터, 속성 등)를 구성하는 방법은 다음을 참조하십시오:

• 로그 관리 활성화
• Fluent Bit로 로그 포워딩

설정 위치

에이전트 컨트롤과 관련된 유일한 세부 사항은 로그 포워딩 파일이 저장되는 위치입니다. 이 파일은 인프라 에이전트 설정의 config_logging 필드를 통해 로그 소스당 하나의 항목으로 하위 에이전트의 logging.d 폴더에 저장됩니다. 하위 에이전트의 설정(예: local_config.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

Fluent Bit의 위치 및 업데이트 방법