From 73631757b04e06ad1d59889291afe02295611f60 Mon Sep 17 00:00:00 2001 From: Paolo Gallina Date: Thu, 9 Jul 2026 11:08:27 +0200 Subject: [PATCH] chore(custom-agents): improve docs --- docs/INTEGRATING_AGENTS.md | 2 +- .../README.md => docs/agent_type.md | 61 ++++++++++++++++++- 2 files changed, 61 insertions(+), 2 deletions(-) rename agent-control/src/agent_type/README.md => docs/agent_type.md (88%) diff --git a/docs/INTEGRATING_AGENTS.md b/docs/INTEGRATING_AGENTS.md index 4ebc5a31ba..da53885ea4 100644 --- a/docs/INTEGRATING_AGENTS.md +++ b/docs/INTEGRATING_AGENTS.md @@ -901,7 +901,7 @@ Before AC can create a sub-agent, it must resolve the agent type referenced in y Only definitions that target the environment of the running binary are considered: the on-host binary only sees `host` definitions matching its operating system, and the Kubernetes binary only sees `kubernetes` definitions (see [Agent Type Metadata](#agent-type-metadata)). A definition that targets a different platform is treated as not found, so the lookup falls through to the next source. -This precedence is what makes the custom directory useful for development: you can add a brand-new agent type, or iterate on and override an existing one, simply by dropping a file there — without rebuilding AC or editing the embedded registry — while still falling back to the built-in and remote sources for everything else. For a step-by-step walkthrough of adding a custom on-host agent type, see the [development guide in the agent type overview](../agent-control/src/agent_type/README.md#development). +This precedence is what makes the custom directory useful for development: you can add a brand-new agent type, or iterate on and override an existing one, simply by dropping a file there — without rebuilding AC or editing the embedded registry — while still falling back to the built-in and remote sources for everything else. For a step-by-step walkthrough of adding a custom on-host agent type, see the [development guide in the agent type overview](./agent_type.md#development-custom-agent-types). ## Applying configurations diff --git a/agent-control/src/agent_type/README.md b/docs/agent_type.md similarity index 88% rename from agent-control/src/agent_type/README.md rename to docs/agent_type.md index 2eec5e59a9..e7724fe717 100644 --- a/agent-control/src/agent_type/README.md +++ b/docs/agent_type.md @@ -387,7 +387,17 @@ deployment: initial_delay: 10s # Defaults to 30s. ``` -## Development +## Development Custom agent types + +Agent Control ships a set of embedded agent types (see +[`agent-control/agent-type-registry/newrelic/`](../agent-control/agent-type-registry/newrelic)). You can add your own — +or override an embedded one — by placing the definition YAML in the *dynamic agent types* directory. Custom definitions +take precedence over embedded ones with the same id. + +The current layout expects **a directory** at `/etc/newrelic-agent-control/dynamic-agent-types/` containing one file per +agent type. + +### On-host This guideline shows how to build a custom agent type and integrate it with the agent control on-host. The [telegraf agent](https://www.influxdata.com/time-series-platform/telegraf/) is used as a reference. @@ -460,3 +470,52 @@ This guideline shows how to build a custom agent type and integrate it with the ``` 5. Restart Agent Control. + +### Kubernetes + +In-cluster, the same `/etc/newrelic-agent-control/dynamic-agent-types/` directory is populated by mounting a ConfigMap. +Each ConfigMap key becomes a file inside the directory, so a single ConfigMap can carry multiple agent types. + +1. Create the ConfigMap in the namespace where Agent Control runs. The `--from-file==` form names each + entry; that `` is the file name that will appear under the mount: + + ```sh + kubectl create configmap dynamic-agent \ + --from-file=dynamic-agent-type=./agent-control/agent-type-registry/newrelic/kubernetes-com.newrelic.infrastructure-0.1.0.yaml \ + -n newrelic-agent-control + ``` + + For multiple types, append more `--from-file==` — one per file. + +2. Mount that ConfigMap on the Agent Control pod through the deployment chart values, matching the layout used in the + dynamic-agent-type k8s e2e ([`test/k8s-e2e/dynamic/ac-values-dynamic.yml`](../test/k8s-e2e/dynamic/ac-values-dynamic.yml)): + + ```yaml + agentControlDeployment: + chartValues: + # [...] + extraVolumeMounts: + - name: dynamic + mountPath: /etc/newrelic-agent-control/dynamic-agent-types + readOnly: true + extraVolumes: + - name: dynamic + configMap: + name: dynamic-agent + ``` + +3. Reference the type by its id in the AC config and supply variable values through `agentsConfig`. Each key under an + agent's `agentsConfig` entry maps to a variable declared by the type: + + ```yaml + agentControlDeployment: + chartValues: + config: + agents: + infra: + agent_type: "newrelic/com.newrelic.infrastructure:0.1.0" + # [...] + ``` + + To pick up a fresh ConfigMap, `helm upgrade` (or restart the AC pod). +