Tipos de agente

O Agent Control em si não possui conhecimento integrado de nenhum agente específico. Ele não sabe como iniciar o agente de infraestrutura, renderizar uma configuração do OpenTelemetry Collector ou descobrir um binário de integração do Redis. Uma definição de tipo de agente é o que o ensina. É um arquivo YAML que descreve como o Agent Control deve identificar, baixar, configurar e executar um tipo de agente, em uma plataforma. Isso é o que permite que ele gerencie um catálogo crescente de agentes sem uma alteração de código sempre que um novo é adicionado.

O subagente é uma instância nomeada dessa definição, por exemplo, nr-infra-agent referenciando newrelic/com.newrelic.infrastructure:0.1.0. É isso que você realmente adiciona, remove ou reconfigura. O Agent Control transforma isso nos artefatos de tempo de execução que a definição descreve, por exemplo, um processo e seus arquivos em um host ou objetos do Kubernetes em um cluster, e os mantém sincronizados sempre que a configuração do subagente muda.

Cada definição de tipo de agente consiste em três seções principais: metadata, variables e deployment, além de um campo protocol_version de nível superior que versiona a linguagem de esquema na qual o arquivo é escrito.

Versão do protocolo

protocol_version é um campo de nível superior que declara a versão do tipo de agente. Ele é dissociado tanto do version do tipo de agente (o semver da definição) quanto da versão de lançamento do Agent Control.

É uma string MAJOR.MINOR entre aspas (por exemplo, "1.0").

Ele é analisado e validado por conta própria, antes que o restante do documento seja interpretado, para que possa controlar arquivos cujos metadados ou outras seções usem um formato que este Agent Control não entenderia de outra forma. Cada versão do Agent Control entende uma única versão máxima de protocolo, e o protocol_version é tratado como um único valor MAJOR.MINOR ordenado. As regras de compatibilidade são:

• Mais recente que o suportado (major maior, ou o mesmo major com um minor maior): rejeitado — o arquivo é mais recente do que este Controle do agente entende.
• Igual ou anterior à suportada: aceita — o Agent Control entende todas as versões de protocolo até a suportada, inclusive.

Por exemplo, um Agent Control que suporta 1.6 aceita tudo até 1.6 (incluindo 0.9 e 1.0..=1.6) e rejeita qualquer versão mais recente (1.7, 2.0,...).

Metadados

A seção de metadados identifica o tipo de agente: seu name, namespace, version, platform de destino (host ou kubernetes) e operating_system (necessário para tipos baseados em host). O Agent Control usa esses campos para endereçar de forma exclusiva a definição e enviá-la para o mecanismo de implantação correto.

Variáveis

A seção de variáveis declara as entradas configuráveis que os operadores podem definir ao adicionar um subagente à sua configuração. Cada variável possui estes campos:

• description: uma explicação legível por humanos da variável.
• type: o tipo de dados que esta variável aceita, como string, bool, number, yaml ou string_map.
• required: se os operadores devem definir a variável (quando definido como falso, o Agent Control recorre ao valor em default).
• default (opcional): o valor usado quando required é false e o operador não define um.
• classification (opcional): um rótulo que descreve o tipo de valor que a variável contém, como config ou multi-config. O Agent Control aceita e ignora este campo; ele é lido pelo Controle de Agentes para orientar como a variável é apresentada aos operadores.
• deprecated (opcional): marca a variável como descontinuada (deprecated: true). O Controle do agente aceita e ignora este campo também — ele não possui comportamento de tempo de execução e não afeta a resolução, a validação ou os padrões.

As variáveis são referenciadas em toda a seção de implantação usando ${nr-var:variable_name}.

Implantação

A seção de implantação descreve como o Agent Control instala e executa o agente. Seu formato é totalmente diferente dependendo do platform de destino declarado nos metadados do tipo de agente.

Para obter a referência completa do esquema e todos os campos disponíveis, consulte a Referência do esquema do tipo de agente.

Implantação no Kubernetes

No Kubernetes, o Controle do agente gerencia objetos do Kubernetes. A seção de implantação é composta por:

• objects: os objetos do Kubernetes que o Agent Control cria e mantém atualizados.
• health: uma lista explícita de verificações, cada uma direcionada a um recurso do Kubernetes por name, namespace e kind.

Como o Agent Control renderiza objects depende se o Flux está habilitado:

• Com o Flux (padrão ou com uma instalação existente do Flux): os tipos de agente declaram um objeto HelmRelease. O Agent Control renderiza suas variáveis de configuração nos valores do chart do Helm desse HelmRelease e cria ou atualiza o recurso. O Flux então reconcilia o chart e cria os recursos subjacentes Deployment, ConfigMap, Secret e outros.
• Sem o Flux: os tipos de agente declaram objetos simples do Kubernetes diretamente (por exemplo, um ConfigMap, Secret ou Deployment) em vez de um HelmRelease. O Agent Control aplica esses objetos ao próprio cluster. Não há chart do Helm ou reconciliação do Flux envolvidos. O usuário tem que gerenciar o ciclo de vida do agente nesse caso.

Implantação no host (Linux e Windows)

Em hosts, o Agent Control instala e executa o agente diretamente no sistema operacional da máquina. A seção de implantação é composta por várias subseções:

• executables: a lista de processos que o Agent Control iniciará, monitorará e reiniciará. Um tipo de agente sem esta seção é tratado como uma integração gerenciada (OHI): o Agent Control lida com seus artefatos, mas delega a execução para outro agente.
• enable_file_logging: se o logging de arquivos está habilitado.
• health: como o Agent Control determina se o agente está íntegro — por meio da presença do processo, de uma verificação de endpoint HTTP ou de ambos.
• filesystem: arquivos ou diretórios individuais que o Agent Control grava no host antes de iniciar o agente, como arquivos de configuração ou certificados.
• shared_filesystem: entradas gravadas em uma zona de depósito compartilhada acessível a outros agentes gerenciados pela mesma instância do Agent Control. Usado por tipos de agente OHI para entregar sua configuração e binários ao agente de infraestrutura.
• packages: artefatos OCI para baixar antes que o agente inicie — normalmente o binário do agente ou o pacote de integração.

Armazenamento de estado do agente

No Kubernetes

O estado reside como objetos do Kubernetes, mas o que esses objetos são depende se o Flux está habilitado.

Com o Flux (padrão, ou com uma instalação existente do Flux), o tipo de agente normalmente declara recursos personalizados do Flux, como um HelmRepository apontando para o chart, e um HelmRelease contendo sua configuração renderizada como valores do chart do Helm. O Agent Control não cria os objetos Deployment, ConfigMap ou Secret do agente diretamente. Ele entrega o HelmRelease ao Flux, e o Flux instala o chart e mantém esses recursos gerados sincronizados com ele.

• Uma atualização de configuração aplica um patch no HelmRelease no local. O controle do agente só reaplica o objeto se o seu conteúdo for alterado. O Flux então reconcilia o chart para corresponder.
• A remoção de um subagente exclui todos os objetos rotulados como de sua propriedade — seu HelmRelease, HelmRepository e qualquer Secret ou ConfigMap criado para ele, e o Flux/Helm finaliza a limpeza do workload que o chart havia instalado.

Sem o Flux, não há HelmRelease ou HelmRepository. O tipo de agente declara objetos simples do Kubernetes diretamente, e o próprio Agent Control os cria e atualiza. Não há chart do Helm ou reconciliação do Flux. Neste modo, o usuário é responsável pelo ciclo de vida do agente. O Agent Control não instala nem atualiza o Deployment do agente, ele apenas mantém os objetos de configuração que gerencia sincronizados.

• Uma atualização de configuração aplica um patch no objeto gerenciado (ConfigMap/Secret) no local. O Agent Control só o reaplica se o seu conteúdo for alterado. Como não há reconciliação do Flux, nada reinicia automaticamente o agente para aplicar a alteração, a menos que o próprio agente a observe.
• A remoção de um subagente exclui todos os objetos rotulados como pertencentes a ele — apenas seus objetos ConfigMap/Secret, já que não há HelmRelease, HelmRepository ou workload instalado por chart para limpar.

No host

Sistema de arquivos no host

Cada subagente recebe um diretório dedicado no disco onde o Agent Control grava os arquivos declarados pela seção filesystem do seu tipo de agente.

O controle do agente obtém o conteúdo para criar um arquivo a partir de variáveis do tipo yaml, e o conteúdo para vários arquivos dentro de um diretório a partir de variáveis do tipo string_map.

Exemplo

/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

Como esse diretório se comporta depende do evento de ciclo de vida e do tipo de variável por trás de cada caminho:

• Uma reinicialização não afeta o diretório. O Controle do Agente não reescreve nada, a menos que a reinicialização tenha sido acionada por uma atualização de configuração do Controle de Agentes.
• Uma atualização de configuração reescreve os arquivos yaml no local, mas regenera totalmente os diretórios string_map. Para um conteúdo yaml, o Controle do Agente reescreve apenas o conteúdo do arquivo. Para um conteúdo string_map, o Controle do Agente exclui todo o diretório (como logging.d acima) e o recria do zero, de modo que qualquer arquivo que você (ou o subagente) tenha adicionado ou editado dentro dele desaparece na próxima gravação.
• Os arquivos que o Agent Control não gerencia são deixados intactos. Ele apenas substitui os caminhos exatos que o tipo de agente declara; qualquer outra coisa que o agente em execução crie por conta própria dentro de seu diretório (arquivos de cache, estado local) não é tocada.
• A remoção de um subagente remove todo o seu diretório, incluindo quaisquer arquivos criados pelo próprio subagente ou por um usuário.

Sistema de arquivos compartilhado no host

A maioria dos tipos de agente é autossuficiente: o Agent Control grava sua configuração em um diretório que pertence apenas a eles e inicia um processo que lê a partir dele. Mas algumas integrações não têm modelo de execução próprio. Não há processo para o Agent Control iniciar. Elas dependem inteiramente de outro agente já em execução (por exemplo, o agente de infraestrutura) para pegar seus arquivos e executá-los. Essa dependência é o motivo pelo qual existe um segundo local compartilhado. É uma zona de depósito comum na qual qualquer subagente no mesmo host pode gravar e qualquer outro subagente pode ler, usada especificamente para transferir artefatos entre agentes em vez de armazenar o próprio estado privado de um agente.

Use filesystem para qualquer coisa que o próprio processo de um tipo de agente precise e dependa de shared_filesystem apenas quando um tipo de agente estiver deliberadamente entregando arquivos a outro, como a integração no host descrita mais abaixo.

Todos os subagentes obtêm um diretório compartilhado no disco onde o Agent Control grava os arquivos declarados pelo shared_filesystem do seu tipo de agente.

Como todos os subagentes têm acesso a esse diretório compartilhado, eles podem ver os arquivos uns dos outros.

Exemplo

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

O diretório compartilhado segue as mesmas regras que o diretório do sistema de arquivos por agente em reinicializações, atualizações de configuração e arquivos não gerenciados. O comportamento só muda ao remover um subagente: seus arquivos são sempre removidos, já que cada arquivo pertence inequivocamente ao subagente que o gravou, mas as pastas só são removidas quando nenhum outro subagente as estiver usando.

Tipos de agente vinculados no host

Dois tipos de agente são vinculados quando um grava artefatos (configuração, binários ou outros arquivos) no sistema de arquivos compartilhado e o outro é configurado para ler desses mesmos caminhos. O gravador pode não ter uma seção executables, o Agent Control gerencia seus artefatos, mas nunca inicia um processo para ele. Em vez disso, o agente leitor tem a lógica integrada para descobrir e executar binários e configurações de um caminho conhecido no sistema de arquivos compartilhado, executando efetivamente o complemento em nome do gravador.

Os nomes dos subdiretórios são escolhidos por convenção entre os tipos de agente vinculados.

Integrações no host (OHI)

As integrações no host (OHIs) são o principal exemplo de tipos de agente vinculados. Enquanto um subagente regular tem um processo que o Agent Control inicia e monitora, uma OHI não tem nenhum. O Agent Control gerencia apenas seu ciclo de vida (baixando, configurando, atualizando e desinstalando-o), enquanto o agente de infraestrutura descobre e executa seus binários a partir do sistema de arquivos compartilhado em seu nome.

A relação entre o agente de infraestrutura e o agente OHI

1. Quando um tipo de agente OHI é instalado, o Agent Control baixa o binário de integração via OCI e grava duas entradas no sistema de arquivos compartilhado:

   • Um arquivo de configuração em infra-agent-ohi-configs/ (por exemplo, nri-redis.yaml)
   • O binário de integração em infra-agent-ohi-binaries/ (por exemplo, nri-redis)

2. O subagente do agente de infraestrutura é configurado com variáveis de ambiente que o apontam para esses diretórios compartilhados:

   Variável	Caminho do sistema de arquivos compartilhado	Propósito
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	Descoberta de configuração de integração
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	Descoberta de binário de integração
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	Caminho de execução de binário permitido

3. O agente de infraestrutura pega a configuração e o binário em seu próximo ciclo de verificação e começa a executar a integração.

   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

   Copiar

Buscando definições de tipo de agente

O Agent Control busca definições de tipo de agente de um registro OCI remoto, identificado por namespace, name e version declarados na seção de metadados da definição, levando em consideração o ambiente em que está sendo executado (Kubernetes, Linux ou Windows).

Por padrão, o Controle do agente extrai de docker.io usando o repositório newrelic/agent-control-agent-types, após verificar a assinatura com a chave pública da New Relic.

As definições de tipo de agente podem ser baixadas de um espelho, conforme explicado em Configurar um espelho de registro OCI para o Agent Control.

Tipos de agentes suportados

Suporte atual

A tabela a seguir mostra quais tipos de agente o Agent Control suporta e sua disponibilidade nos ambientes.

Permissões necessárias por tipo de agente

A tabela a seguir lista as principais permissões que cada tipo de agente exige e os ambientes onde ele se aplica.

Configuração do Fluent Bit em hosts

Em hosts, o Fluent Bit não é implantado como seu próprio tipo de agente de nível superior (consulte a tabela de suporte acima). Em vez disso, quando o encaminhamento de logs está ativado, o Fluent Bit é gerado e gerenciado pelo próprio agente de infraestrutura do New Relic, da mesma forma que quando é instalado de forma independente. O Agent Control altera apenas onde o agente de infraestrutura, seus dados e o binário e o plug-in do Fluent Bit residem no disco.

Para saber como configurar o próprio encaminhamento de logs (sintaxe logging.d/*.yml, entradas, filtros, atributos e assim por diante), consulte:

• Habilitar gerenciamento de logs
• Encaminhar logs com o Fluent Bit

Onde colocar sua configuração

O único detalhe específico do Agent-Control é para onde vão os arquivos de encaminhamento de logs: eles chegam na pasta logging.d do subagente, uma entrada por fonte de log, por meio do campo config_logging da configuração do agente de infraestrutura. Defina-o diretamente na configuração do subagente (por exemplo, seu local_config.yaml) e envie-o para o 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

Onde o Fluent Bit reside e como ele é atualizado