Managing configurations

visualização

Ainda estamos trabalhando nesse recurso, mas adoraríamos que você experimentasse!

Atualmente, esse recurso é fornecido como parte de um programa de visualização de acordo com nossas políticas de pré-lançamento.

Importante

Agent Control currently only supports Kubernetes. The configurations and examples provided in this document are specific to this environment.

Agent Control provides two methods for managing agent configurations:

Local configuration: A comprehensive values.yaml file used during the initial Helm installation.
Remote configuration: A centralized, YAML-based configuration you create in New Relic Control that is remotely deployed to your entire fleet.

Remote configuration is the recommended method for day-to-day management. It ensures consistent agent behavior across your environment, simplifies change management, and enables you to scale without manually updating local YAML files on each host.

Dica

The values-newrelic.yaml file, which traditionally defined New Relic agent settings, now also includes configuration for Agent Control. The parameters you define in this file determine how both Agent Control and its managed agents operate. This file is referred to as the local configuration.

Understanding the two layers of configuration

Agent Control's configuration is structured in two layers:

Agent Control's core configuration: These are the top-level settings that control how Agent Control operates, such as its connection to New Relic, its identity, and fleet management details.
Managed agents' configurations: These are the individual chart_values for each subagent (e.g., Infrastructure Agent, Fluent Bit) that Agent Control deploys and manages.

When a local and remote configuration are both present, Agent Control applies the following logic:

Remote configuration takes precedence. Any settings defined in a remote configuration from New Relic Control will override the corresponding settings in the local values.yaml file.
To intentionally override remote settings with your local configuration, you can deploy an empty remote configuration via New Relic Control. This change will apply to all clusters in the selected fleet.

Kubernetes configuration

These instructions and examples apply to Agent Control running on a Kubernetes cluster.

Local `values.yaml` configuration for Kubernetes

The local configuration file for Kubernetes, used during installation, contains all the settings for Agent Control and its managed agents.

This example shows the two layers of configuration within a single file.

# Layer 1: Agent Control's Core Configuration
global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"
  userKey: "YOUR_USER_KEY"

# Values related to the agent control's Helm chart release.
# `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
      fleet_id: ""
      auth:
        # New Relic organization ID where agent will connect to.
        organizationId: "YOUR_ORGANIZATION_ID"

    # Layer 2: Managed Agents' Configurations
    # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
          chart_values:
            newrelic-infrastructure:
            enableProcessMetrics: true
      logs:
        type: newrelic/io.fluentbit:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
          chart_values:
            newrelic-logging:
              sendMetrics: true
      agent-operator:
        type: com.newrelic.k8s_agent_operator:0.1.0
        content:
          chart_version: "*"

O exemplo demonstra como configurar o Agent Control junto com dois agentes gerenciados: o agente de infraestrutura Kubernetes e Fluent Bit para encaminhamento de logs. Por exemplo, se você não quiser enviar métricas de saúde para seu coletor de log Fluent Bit , basta definir sendMetrics: false no arquivo YAML antes de executar o comando de instalação.

Remote configuration for Kubernetes

A configuração remota garante um comportamento consistente do agente em todo o seu ambiente, simplifica o gerenciamento de alterações e permite que você dimensione a observabilidade sem gerenciar manualmente os arquivos YAML locais.

Para implantar a configuração centralmente no cluster, defina esse mesmo conteúdo YAML na seção Configurations do Controle de Agentes. Você pode então aplicar a configuração a uma frota inteira de clusters como parte de uma implantação remota. Isso é chamado de arquivo de configuração remota .

callout.warning

When you define a configuration in the New Relic Control UI, the YAML structure is different. You only provide the YAML that corresponds to the content block for a single agent.

Sample configurations: Agent Control on Kubernetes

Os exemplos a seguir mostram como configurar o Agent Control para gerenciar diferentes conjuntos de agentes. Essas configurações podem ser utilizadas durante a instalação inicial ou como parte de uma configuração remota no Controle de Agentes.

Para explorar todas as configurações disponíveis, consulte values-newrelic.yaml.

The following examples show how to configure Agent Control with a set of subagents using the local values.yaml file.

Agent Control with New Relic infrastructure and Fluent Bit

Este exemplo implanta Agent Control com monitoramento de infraestrutura e Fluent Bit para coleta de logs.

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"
  userKey: "YOUR_USER_KEY"

# See `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional
      # fleet_id: YOUR_FLEET_ENTITY_GUID
      auth:
        organizationId: "YOUR_ORGANIZATION_ID"
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"

          #chart_values:
          #  newrelic-infrastructure:
          #    enableProcessMetrics: true
      logs:
        type: newrelic/io.fluentbit:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"

          #chart_values:
          #  newrelic-logging:
          #    sendMetrics: true
      agent-operator:
        type: com.newrelic.k8s_agent_operator:0.1.0
        chart_version: "*"

Agent Control with OpenTelemetry and custom collector settings

Este exemplo implanta o Agent Control com a distribuição New Relic do OpenTelemetry (NRDOT) coleta e desabilita o receptor filelog no gráfico Helm gerenciadonr-k8s-otel-collector .

Importante

Security Best Practice: Do not store sensitive values like your license key directly in the configuration. We recommend using a Kubernetes secret. Agent Control can then securely pull these values from the secret at runtime.

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"
# Values related to the agent control's Helm chart release.
# `https://github.com/newrelic/helm-charts/blob/master/charts/agent-control/values.yaml`
agent-control-deployment:
  identityClientId: ""
  identityClientSecret: ""
  config:
    fleet_control:
      # Optional: Specify a fleet_id (entity guid) to automatically connect to an existing fleet.
      fleet_id: ""
      auth:
        # New Relic organization ID where agent will connect to.
        organizationId: "YOUR_ORGANIZATION_ID"

    # List of managed agents that will be deployed. The key represents the name of the agent and the value holds the configuration.
    subAgents:
      infrastructure:
        type: newrelic/com.newrelic.infrastructure:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/nri-bundle%60
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
      agent-operator:
        type: newrelic/com.newrelic.k8s_agent_operator:0.1.0
        content:
          chart_version: "*"
      fluentbit:
        type: newrelic/io.fluentbit:0.1.0
        content:
          # Ref: `https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-logging`
          # Recommended: check and define an explicit chart version (latest stable)
          chart_version: "*"
          chart_values:
            global:
              lowDataMode: true
      prometheus:
        type: newrelic/com.newrelic.prometheus:0.1.0
        content:
          chart_version: "*"
          chart_values:
            global:
              lowDataMode: true
            newrelic-prometheus-agent:
              config:
                kubernetes:
                  integrations_filter:
                    enabled: false

Sample configurations: Remote Agent Configurations on Kubernetes

The following examples show how to configure individual agents remotely from the New Relic Control UI.

Configuração remota: New Relic Infrastructure

Este exemplo mostra como configurar remotamente o agente da New Relic Infrastructure para Kubernetes usando o Controle de Agentes. Ele permite a coleta de métricas do processo definindo enableProcessMetrics: true.

Configuração remota: Fluent Bit

Este exemplo configurou Fluent Bit remotamente via Controle de Agentes. Ele habilita relatórios métricos de saúde do coletor de logs definindo sendMetrics: true.

Configuração remota: Prometheus

Este exemplo configura o agente Prometheus remotamente usando o Controle de Agentes. Ele permite que low-data mode reduza o volume de telemetria e desabilite a integração padrão.

Configuração remota: OpenTelemetry

This example configures the New Relic OpenTelemetry collector and enable lowDataMode as a valid option.

Importante

Crie um segredo do Kubernetes para armazenar com segurança a chave de licença do New Relic e usá-la em chart_values em substituição ao valor licenseKey :

customSecretName: "your-secret-name"
customSecretLicenseKey: "your-secret-key"

Recomendamos utilizar o Controle de Agentes para definir e implantar a configuração OpenTelemetry em suas frotas. Para configurar OpenTelemetry remotamente, crie uma configuração no Controle de Agentes com a estrutura mostrada abaixo. Você pode ajustar valores como lowDataMode ou receivers.filelog.enabled e incluir quaisquer outras configurações relevantes do gráfico Helm com base em suas necessidades.

chart_version: "*"
chart_values:
  newrelic-prometheus-agent:
    lowDataMode: true

Proxy configuration for Kubernetes

Agent Control supports proxy configuration to route traffic through corporate proxies. Proxy settings can be set through environment variables or directly in the configuration file.

Precedência de proxy

Agent Control usará as configurações de proxy na seguinte ordem de precedência:

proxy Campo de configuração na configuração de Agent Control
HTTP_PROXY variável de ambiente
HTTPS_PROXY variável de ambiente

Importante

A configuração do proxy atualmente não é compatível com a busca do certificado para validação da assinatura. Se precisar configurar um proxy, você tem estas opções:

Adicione uma exceção firewall a https://newrelic.com para que requests para esse endpoint possam ignorar o proxy (recomendado)
Use um certificado local por meio de fleet_control.signature_validation.certificate_pem_file_path (a rotação do certificado deve ser tratada manualmente)
Desabilite a validação de assinatura definindo fleet_control.signature_validation.enabled: false (altamente desencorajado por motivos de segurança)

Configuração de proxy com certificados autoassinados

Para configurações de proxy usando autenticação HTTPS com certificados autoassinados, você precisa fornecer o pacote de certificado da CA e configurar a autenticação de proxy:

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

agent-control-deployment:
  config:
    agentControl:
      content:
        proxy:
          url: https://proxy-service:8080
    subAgents: {}

  # Mount CA certificate bundle to Agent Control
  extraVolumeMounts:
    - mountPath: /etc/ssl/certs/
      name: ca-certs
  extraVolumes:
    - name: ca-certs
      secret:
        secretName: ca-certs

# Configure Flux components to use proxy
agent-control-cd:
  flux2:
    sourceController:
      extraEnv:
        # Configure Flux source-controller to proxy all requests
        - name: HTTPS_PROXY
          value: https://proxy-service:8080
        # Except for in-cluster requests
        - name: "NO_PROXY"
          value: ".cluster.local.,.cluster.local,cluster.local,.svc,127.0.0.0/8,10.0.0.0/8"
      volumeMounts:
        # Mount CA certificate bundle to source-controller trust root store. The bundle should contain the
        # proxy CA cert.
        - mountPath: /etc/ssl/certs/
          name: ca-certs
      volumes:
        - name: ca-certs
          secret:
            secretName: ca-certs

Configuração de proxy para agente gerenciado

Cuidado

Configurar um proxy no Agent Control não configura automaticamente as mesmas configurações de proxy para o agente que ele gerencia. Cada agente tem sua própria configuração de proxy, que deve ser definida separadamente, de acordo com o formato de configuração e os requisitos específicos do agente.

Ao usar um proxy, você também deve configurar as definições de proxy para cada agente gerenciado individualmente. Consulte a documentação específica de cada agente para obter opções de configuração de proxy.

Gerenciamento de segredos

O agente Control fornece um mecanismo robusto para gerenciar dados confidenciais, como senhas e chaves de API, recuperando-os de provedores secretos dedicados. Isso garante que informações confidenciais não sejam codificadas diretamente em arquivos de configuração. O sistema atualmente suporta os seguintes provedores secretos:

HashiCorp Vault: referido como nr-vault na configuração.
Secrets Kubernetes : referidos como nr-kubesec na configuração.

Definindo segredos na configuração

Para utilizar segredos, defina-os no arquivo YAML de configuração do agente-Control seguindo estas etapas:

Defina a seção secrets_providers : configure seus provedores secretos centralmente nesta seção. Certifique-se de que cada entrada corresponda a um provedor suportado.
Configurar fontes secretas: para cada provedor, especifique uma ou mais fontes. Uma fonte inclui os detalhes de configuração necessários (por exemplo, URL, token) para que o agente de controle se conecte e recupere um grupo de segredos.
Utilize o espaço reservado na configuração do agente: Em vez dos dados confidenciais reais, utilize uma string de espaço reservado na configuração do seu agente. O agente de controle substitui automaticamente esses espaços reservados pelos segredos recuperados durante o processo de renderização.

Importante

Se o controle do agente falhar ao recuperar um segredo, a renderização da configuração falhará e o agente não será executado. Este é um recurso de segurança crítico para evitar que o agente seja executado com configuração incompleta ou incorreta.

O exemplo de configuração de controle de agente a seguir demonstra como configurar a recuperação de segredos de duas fontes do Vault dentro da seção secrets_providers :

secrets_providers:
  vault:
    sources:
      local-instance:
        url: http://localhost:8200/v1/
        token: root
        engine: kv2
      remote:
        url: http://my-remote-server:8200/v1/
        token: root
        engine: kv1

fleet_control:
  ...

agents:
  ...

Usando segredos em uma configuração de agente

Depois que as fontes forem definidas, em uma configuração de agente, você poderá referenciar o vault usando uma sintaxe de espaço reservado específica com o caminho correto. O controle do agente recupera o segredo e o usa para renderizar o arquivo de configuração final que o agente irá usar.

Exemplo de configuração de agente utilizando espaço reservado do vault:

config_agent: |+
  enable_process_metrics: true
  custom_attributes:
    username: "${nr-vault:local-instance:secret:my_secret:username}"
    organization: "${nr-vault:remote:my_mount:my_path:organization}"

Neste exemplo:

O espaço reservado ${nr-vault:local-instance:secret:my_secret:username} instrui o agente de controle a recuperar o valor associado à chave username do segredo no caminho secret/my_secret usando a fonte do vault local-instance. O espaço reservado ${nr-vault:remote:my_mount:my_path:organization} também recupera o valor da chave da organização da fonte remota.

Após a recuperação bem-sucedida, o controle do agente renderiza esses segredos da origem e do caminho especificados, armazenando o resultado em um segredo do K8s ou em um arquivo de configuração privado para uso pelo agente correspondente.

Segredos do cofre

Configure as fontes do vault com as seguintes configurações:

Chave YAML	Descrição
`url`	URL para solicitar dados
`token`	Usado para autenticar no endpoint.
`engine`	Especifique `kv1` ou `kv2`.

No arquivo de configuração, cada segredo armazenado no Vault pode ser acessado definindo um espaço reservado com:

source_name: O nome da origem do Vault definida em secrets_providers.
mount: O nome da montagem do mecanismo secreto.
path: O caminho específico para o segredo.
specific key: a chave específica dentro do segredo a ser recuperada.

Exemplo de formato de espaço reservado completo:

"${nr-vault:source_name:my_mount:my_path:my_value}"

Segredos do Kubernetes

Se o pod de controle do agente tiver permissões, como por meio de uma conta de serviço e controle de acesso baseado em função (RBAC), para acessar os segredos e o namespace necessários, o controle do agente poderá acessar os segredos diretamente da API Kubernetes sem precisar de uma configuração de fontes separada.

No arquivo de configuração do agente, recupere cada valor secreto usando um espaço reservado especificando:

namespace: o namespace do Kubernetes onde o segredo está localizado.
name: O nome do objeto secreto do Kubernetes.
specific key: a chave específica dentro do segredo da qual recuperar o valor.

Por exemplo, use o formato de espaço reservado:

"${nr-kubesec:my_namespace:my_secret:my_value}"

Configuração de repositório privado

O agente Control suporta a configuração do repositório Helm privado para implantar o próprio agente Control e o agente gerenciado. Isso permite ambientes onde os gráficos do New Relic Helm não são diretamente acessíveis.

Cuidado

Ao usar o repositório privado Helm, os gráficos precisam ser compatíveis e as imagens referenciadas dentro dos gráficos devem ser acessíveis. Caso contrário, o agente não trabalhará como esperado.

1. Habilite repositório privado para agente

Por razões de segurança, somente o repositório explicitamente habilitado será permitido na configuração remota. Para habilitar repositório específico, é necessário atualizar a configuração do agente Control:

# values-newrelic.yaml

global:
  cluster: "YOUR_CLUSTER_NAME"
  licenseKey: "YOUR_LICENSE_KEY"

# ...

agent-control-deployment:
  config:
    allowedChartRepositoryUrl:
      - https://my-private-repository-1
      - https://my-private-repository-2
    # ...

A configuração do repositório permitida pode então ser usada em sua configuração remota dentro do New Relic Control. Exemplo:

chart_version: "1.2.3"
chart_repository:
  url: "https://my-private-repository-1"
  name: "my-chart-name" # Optional: use only if the chart name doesn't match New Relic's chart name

Além disso, você precisa configurar a instalação Helm do agente Control para usar seu repositório privado se o próprio gráfico agent-control estiver em um repositório privado. Isso é separado da configuração do agente gerenciado. Consulte agent-control Helm chart values.yaml para configurar a seção installationJob. Especificamente:

chartRepositoryUrl contendo a URL do seu repositório
name se estiver usando um nome de gráfico diferente
repositorySecretReferenceName e repositoryCertificateSecretReferenceName para autenticação (veja a seção de autenticação abaixo para detalhes)

2. Configure autenticação para repositório privado

Você precisa configurar recursos adicionais para habilitar a autenticação para acessar seu repositório privado:

Para autenticar usando autenticação básica (nome de usuário e senha), você precisa criar um segredo no namespace do agente Control contendo os valores esperados em data.username e data.password.

Exemplo:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
stringData:
  username: "myUser"
  password: "myPassword"

Para mais detalhes, consulte a documentação do Flux.

Ao usar a autenticação básica, a configuração remota deve ser definida da seguinte maneira:

chart_repository:
  url: "https://my-private-repository-1"
  secret_reference:
    name: my-secret

Para autenticar usando TLS, você precisa criar um segredo contendo:

tls.crt e tls.key: certificado do cliente e chave privada usados para autenticação do cliente TLS
ca.crt: Certificado CA usado para verificar o servidor (obrigatório se o servidor usar um certificado autoassinado)
O segredo deve ser do tipo Opaque ou kubernetes.io/tls. Espera-se que todos os arquivos no Secret sejam codificados em PEM.
Exemplo:
```
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
  namespace: newrelic-agent-control
type: kubernetes.io/tls # or Opaque
data:
  tls.crt: <BASE64>
  tls.key: <BASE64>
  # NOTE: Can be supplied without the above values
  ca.crt: <BASE64>
```
Para mais detalhes, consulte a documentação do Flux.
Ao usar a autenticação de certificado TLS, a configuração remota deve ser definida da seguinte maneira:
```
chart_repository:
  url: "https://my-private-repository-1"
  certificate_secret_reference:
    name: my-secret
```

Esta tradução de máquina é fornecida para sua comodidade.

visualização

Importante

Dica

Understanding the two layers of configuration.css-21sua1{background:none;border:none;width:0;padding:0;}

Kubernetes configuration

Local values.yaml configuration for Kubernetes

Remote configuration for Kubernetes

callout.warning

Sample configurations: Agent Control on Kubernetes

Agent Control with New Relic infrastructure and Fluent Bit

Configuração local para infraestrutura e Fluent Bit

Agent Control with OpenTelemetry and custom collector settings

Importante

Configuração OpenTelemetry

Sample configurations: Remote Agent Configurations on Kubernetes

Configuração remota: New Relic Infrastructure

configuração remota de infraestrutura

Configuração remota: Fluent Bit

Configuração Fluent Bit

Configuração remota: Prometheus

Configuração do Prometheus

Configuração remota: OpenTelemetry

Importante

OpenTelemetry remote configuration

Proxy configuration for Kubernetes

Precedência de proxy

Importante

Configuração de proxy com certificados autoassinados

Exemplo de configuração de proxy do Kubernetes

Configuração de proxy para agente gerenciado

Cuidado

Gerenciamento de segredos

Definindo segredos na configuração

Importante

Usando segredos em uma configuração de agente

Segredos do cofre

Segredos do Kubernetes

Configuração de repositório privado

Cuidado

1. Habilite repositório privado para agente

Habilitar repositório privado

2. Configure autenticação para repositório privado

Autenticação básica

Autenticação de certificado TLS

Understanding the two layers of configuration

Local `values.yaml` configuration for Kubernetes