에이전트 유형

Agent Control 자체에는 특정 에이전트에 대한 기본 지식이 없습니다. 인프라 에이전트를 시작하거나, OpenTelemetry Collector 구성을 렌더링하거나, 레디스 통합 바이너리를 검색하는 방법을 알지 못합니다. 에이전트 유형 정의가 이를 알려줍니다. 이는 Agent Control이 하나의 플랫폼에서 한 종류의 에이전트를 식별, 다운로드, 구성 및 실행하는 방법을 설명하는 YAML 파일입니다. 이를 통해 새로운 에이전트가 추가될 때마다 코드를 변경하지 않고도 증가하는 에이전트 카탈로그를 관리할 수 있습니다.

하위 에이전트는 해당 정의의 명명된 인스턴스입니다(예: newrelic/com.newrelic.infrastructure:0.1.0을(를) 참조하는 nr-infra-agent). 이것이 실제로 추가, 제거 또는 재설정하는 대상입니다. 에이전트 컨트롤은 이를 정의에서 설명하는 런타임 아티팩트(예: 호스트의 프로세스 및 해당 파일 또는 클러스터의 Kubernetes 객체)로 변환하고, 하위 에이전트의 설정이 변경될 때마다 동기화 상태를 유지합니다.

모든 에이전트 유형 정의는 세 가지 주요 섹션: metadata, variables, deployment와 파일이 작성된 스키마 언어의 버전을 지정하는 최상위 protocol_version 필드로 구성됩니다.

프로토콜 버전

protocol_version 에이전트 유형의 버전을 선언하는 최상위 필드입니다. 이는 에이전트 유형 version (정의의 시맨틱 버전) 및 Agent Control 릴리스 버전 모두와 분리되어 있습니다.

따옴표로 묶인 MAJOR.MINOR 문자열입니다(예: "1.0")

이것은 문서의 나머지 부분이 해석되기 전에 자체적으로 구문 분석되고 검증되므로, 메타데이터나 다른 섹션에서 이 에이전트 컨트롤이 이해하지 못하는 형태를 사용하는 파일을 제어할 수 있습니다. 각 에이전트 컨트롤 릴리스는 단일 최대 프로토콜 버전을 이해하며, protocol_version은(는) 단일 정렬된 MAJOR.MINOR 값으로 처리됩니다. 호환성 규칙은 다음과 같습니다:

• 지원되는 것보다 최신(더 높은 major, 또는 더 높은 minor를 가진 동일한 major): 거부됨 ― 파일이 이 Agent Control이 이해하는 것보다 최신입니다.
• 지원되는 버전과 같거나 이전 버전: 허용됨 ― 에이전트 컨트롤은 지원되는 버전을 포함하여 그 이전의 모든 프로토콜 버전을 이해합니다.

예를 들어, 1.6을(를) 지원하는 에이전트 컨트롤은 1.6 까지의 모든 항목(0.9 및 1.0..=1.6 포함)을 수락하고 더 새로운 항목(1.7, 2.0, ...)은 거부합니다.

메타데이터

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

변수

변수 섹션은 운영자가 설정에 하위 에이전트를 추가할 때 설정할 수 있는 구성 가능한 입력을 선언합니다. 각 변수에는 다음 필드가 있습니다:

• description: 사람이 읽을 수 있는 변수에 대한 설명입니다.
• type: 이 변수가 허용하는 데이터 유형입니다(예: string, bool, number, yaml 또는 string_map).
• required: 운영자가 변수를 설정해야 하는지 여부입니다(false로 설정된 경우 에이전트 컨트롤은 default의 값으로 대체합니다).
• default (선택 사항): required이(가) false 이고 운영자가 값을 설정하지 않을 때 사용되는 값입니다.
• classification (선택 사항): config 또는 multi-config와 같이 변수가 보유하는 값의 종류를 설명하는 레이블입니다. 에이전트 컨트롤은 이 필드를 수락하고 무시하며, 플릿 컨트롤이 이를 읽어 운영자에게 변수가 표시되는 방식을 결정합니다.
• deprecated (선택 사항): 변수를 더 이상 사용되지 않음(deprecated: true)으로 표시합니다. Agent Control은 이 필드도 허용하고 무시합니다 ― 런타임 동작을 수행하지 않으며 확인, 유효성 검사 또는 기본값에 영향을 주지 않습니다.

변수는 ${nr-var:variable_name}을(를) 사용하여 배포 섹션 전체에서 참조됩니다.

전개

배포 섹션에서는 에이전트 컨트롤이 에이전트를 설치하고 실행하는 방법을 설명합니다. 그 형태는 에이전트 유형의 메타데이터에 선언된 타겟 platform에 따라 완전히 다릅니다.

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

Kubernetes에 배포

Kubernetes에서 에이전트 컨트롤은 Kubernetes 객체를 관리합니다. 배포 섹션은 다음과 같이 구성됩니다:

• objects: 에이전트 컨트롤이 생성하고 최신 상태로 유지하는 Kubernetes 객체입니다.
• health: 명시적인 검사 목록으로, 각각 name, namespace 및 kind을(를) 통해 하나의 Kubernetes 리소스를 대상으로 합니다.

에이전트 컨트롤이 objects을(를) 렌더링하는 방법은 Flux 활성화 여부에 따라 다릅니다:

• Flux 사용(기본값 또는 기존 Flux 설치 사용): 에이전트 유형은 HelmRelease 객체를 선언합니다. 에이전트 컨트롤은 설정 변수를 해당 HelmRelease의 Helm 차트 값으로 렌더링하고 리소스를 생성하거나 업데이트합니다. 그런 다음 Flux는 차트를 조정하고 기본 Deployment, ConfigMap, Secret 및 기타 리소스를 생성합니다.
• Flux가 없는 경우: 에이전트 유형은 HelmRelease 대신 일반 Kubernetes 객체(예: ConfigMap, Secret 또는 Deployment)를 직접 선언합니다. 에이전트 컨트롤은 해당 객체를 클러스터 자체에 적용합니다. Helm 차트나 Flux 조정은 개입되지 않습니다. 그 경우에는 사용자가 에이전트 수명 주기를 관리해야 합니다.

온호스트 배포(Linux 및 Windows)

호스트에서 에이전트 컨트롤은 머신의 운영 시스템에 직접 에이전트를 설치하고 실행합니다. 배포 섹션은 여러 하위 섹션으로 구성됩니다:

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

에이전트 상태 저장소

Kubernetes에서

상태는 Kubernetes 객체로 존재하지만, 해당 객체가 무엇인지는 Flux 활성화 여부에 따라 다릅니다.

Flux(기본값 또는 기존 Flux 설치)를 사용하면 에이전트 유형은 일반적으로 차트를 가리키는 HelmRepository 및 렌더링된 설정을 Helm 차트 값으로 유지하는 HelmRelease과 같은 Flux 사용자 지정 리소스를 선언합니다. 에이전트 컨트롤은 에이전트의 Deployment, ConfigMap 또는 Secret 객체를 직접 생성하지 않습니다. HelmRelease을(를) Flux에 전달하면, Flux는 차트를 설치하고 생성된 리소스를 해당 차트와 동기화된 상태로 유지합니다.

• 설정 업데이트는 제자리에서 HelmRelease을(를) 패치합니다. 에이전트 컨트롤은 내용이 변경된 경우에만 객체를 다시 적용합니다. 그런 다음 Flux는 일치하도록 차트를 조정합니다.
• 하위 에이전트를 제거하면 해당 에이전트가 소유한 것으로 레이블이 지정된 모든 객체가 삭제됩니다 — 해당 HelmRelease, HelmRepository 및 이를 위해 생성된 모든 Secret 또는 ConfigMap이(가) 삭제되며, Flux/Helm은 해당 차트가 설치한 워크로드의 정리를 완료합니다.

Flux가 없으면 HelmRelease 또는 HelmRepository이 없습니다. 에이전트 유형은 일반 Kubernetes 객체를 직접 선언하며, 에이전트 컨트롤이 이를 직접 생성하고 업데이트합니다. Helm 차트나 Flux 조정이 없습니다. 이 모드에서는 사용자가 에이전트 수명 주기를 책임집니다. 에이전트 컨트롤은 에이전트의 Deployment을(를) 설치하거나 업그레이드하지 않으며, 관리하는 설정 객체만 동기화 상태로 유지합니다.

• 설정 업데이트는 관리형 객체(ConfigMap/Secret)를 기존 위치에서 패치합니다. 에이전트 컨트롤은 콘텐츠가 변경된 경우에만 이를 다시 적용합니다. Flux 조정이 없으므로, 에이전트 자체가 이를 감시하지 않는 한 변경 사항을 적용하기 위해 에이전트를 자동으로 다시 시작하는 것은 없습니다.
• 하위 에이전트를 제거하면 해당 에이전트가 소유한 것으로 레이블이 지정된 모든 객체가 삭제됩니다 — 정리할 HelmRelease, HelmRepository 또는 차트 설치 워크로드가 없으므로 해당 ConfigMap/Secret 객체만 삭제됩니다.

온호스트

온호스트 파일 시스템

모든 하위 에이전트는 디스크에 전용 디렉터리를 할당받으며, 에이전트 컨트롤은 해당 에이전트 유형의 filesystem 섹션에 선언된 파일을 이 디렉터리에 기록합니다.

Agent Control은 yaml 유형의 변수에서 파일을 생성할 콘텐츠를 가져오고, 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

이 디렉터리가 작동하는 방식은 수명 주기 이벤트와 각 경로 뒤에 있는 변수 유형에 따라 다릅니다:

• 재시작은 디렉터리를 건드리지 않습니다. 에이전트 컨트롤은 플릿 컨트롤의 설정 업데이트로 인해 재시작이 트리거되지 않는 한 아무것도 다시 쓰지 않습니다.
• 설정 업데이트는 제자리에서 yaml 파일을 다시 쓰지만, string_map 디렉터리는 완전히 다시 생성합니다. yaml 콘텐츠의 경우, 에이전트 컨트롤은 파일의 콘텐츠만 다시 씁니다. string_map 콘텐츠의 경우, 에이전트 컨트롤은 전체 디렉터리(위의 logging.d와 같이)를 삭제하고 처음부터 다시 생성하므로, 사용자(또는 하위 에이전트)가 그 안에 추가하거나 편집한 파일은 다음 쓰기 시 사라집니다.
• 에이전트 컨트롤이 관리하지 않는 파일은 그대로 유지됩니다. 에이전트 유형이 선언한 정확한 경로만 덮어쓰며, 실행 중인 에이전트가 디렉터리 내에 자체적으로 생성한 다른 모든 항목(캐시 파일, 로컬 상태)은 변경하지 않습니다.
• 하위 에이전트를 제거하면 하위 에이전트 자체나 사용자가 생성한 모든 파일을 포함하여 전체 디렉터리가 제거됩니다.

온호스트 공유 파일 시스템

대부분의 에이전트 유형은 독립적입니다: 에이전트 컨트롤은 해당 에이전트 전용 디렉터리에 설정을 기록하고, 이를 읽는 프로세스를 시작합니다. 그러나 일부 통합에는 자체 실행 모델이 없습니다. 에이전트 컨트롤이 시작할 프로세스가 없습니다. 이들은 파일을 가져와 실행하기 위해 이미 실행 중인 다른 에이전트(예: 인프라 에이전트)에 전적으로 의존합니다. 이러한 의존성 때문에 두 번째 공유 위치가 존재합니다. 이 위치는 동일한 호스트의 모든 하위 에이전트가 기록할 수 있고 다른 모든 하위 에이전트가 읽을 수 있는 공용 드롭 존으로, 에이전트의 자체 비공개 상태를 저장하기보다는 에이전트 간에 아티팩트를 전달하는 데 특별히 사용됩니다.

에이전트 유형 자체의 프로세스에 필요한 모든 항목에는 filesystem을(를) 사용하고, 아래에 설명된 온-호스트 통합과 같이 한 에이전트 유형이 다른 에이전트 유형에 의도적으로 파일을 전달하는 경우에만 shared_filesystem에 의존하십시오.

모든 하위 에이전트는 에이전트 컨트롤이 해당 에이전트 유형의 shared_filesystem에서 선언한 파일을 기록하는 디스크 상의 공유 디렉터리를 할당받습니다.

모든 하위 에이전트는 해당 공유 디렉터리에 액세스할 수 있으므로, 서로의 파일을 볼 수 있습니다.

예시

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

공유 디렉터리는 재시작, 설정 업데이트 및 관리되지 않는 파일에 대해 에이전트별 파일 시스템 디렉터리와 동일한 규칙을 따릅니다. 하위 에이전트를 제거할 때만 동작이 변경됩니다: 각 파일은 해당 파일을 작성한 하위 에이전트가 명확하게 소유하므로 항상 제거되지만, 폴더는 다른 하위 에이전트가 사용하지 않을 때만 제거됩니다.

온-호스트 연결 에이전트 유형

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

하위 디렉터리 이름은 연결된 에이전트 유형 간의 관례에 따라 선택됩니다.

온호스트 통합(OHI)

온-호스트 통합(OHI)은 연결된 에이전트 유형의 주요 예입니다. 일반 하위 에이전트에는 에이전트 컨트롤이 시작하고 모니터하는 프로세스가 있지만 OHI에는 없습니다. 에이전트 컨트롤은 수명 주기(다운로드, 설정, 업그레이드 및 제거)만 관리하는 반면, 인프라 에이전트는 공유 파일 시스템에서 바이너리를 검색하고 대신 실행합니다.

에이전트 컨트롤은 통합이 상태를 보고할 때 온-호스트 통합의 상태를 보고합니다. 통합이 상태를 보고하지 않으면 에이전트 컨트롤은 unknown을(를) 보고합니다. unknown 상태는 통합이 실패하고 있다는 것이 아니라 상태 데이터를 보내지 않고 있음을 의미합니다. 이유를 알아보려면 인프라 에이전트의 로그를 확인하십시오. 에이전트 로깅 문제 진단을 참조하십시오.

인프라 에이전트 및 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

   카피

에이전트 유형 정의 가져오기

에이전트 컨트롤은 실행 중인 환경(Kubernetes, Linux 또는 Windows)을 고려하여, 정의의 메타데이터 섹션에 선언된 namespace, name 및 version로 식별되는 원격 OCI 레지스트리에서 에이전트 유형 정의를 가져옵니다.

기본적으로 에이전트 컨트롤은 뉴렐릭의 공개 키로 서명을 확인한 후 newrelic/agent-control-agent-types 저장소를 사용하여 docker.io에서 가져옵니다.

에이전트 유형 정의는 에이전트 컨트롤용 OCI 레지스트리 미러 구성에 설명된 대로 미러에서 가져올 수 있습니다.

지원되는 에이전트 유형

현재 지원

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

에이전트 유형별 필수 권한

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

호스트에서 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의 위치 및 업데이트 방법