• /
  • EnglishEspañolFrançais日本語한국어Português
  • 로그인지금 시작하기

사용자의 편의를 위해 제공되는 기계 번역입니다.

영문본과 번역본이 일치하지 않는 경우 영문본이 우선합니다. 보다 자세한 내용은 이 페이지를 방문하시기 바랍니다.

문제 신고

대규모 에이전트 컨트롤 설치를 자동화하십시오.

|View as Markdown (English)

안내 설치를 통해 에이전트 컨트롤을 설치하면, 시스템 ID가 생성되고 클라이언트 ID와 클라이언트 시크릿이 표시됩니다. 해당 시크릿은 발급 후 12시간이 지나면 만료되며, 단일 설치의 경우 문제없이 작동합니다. Terraform, Ansible, Chef, Puppet 또는 CI/CD 파이프라인을 사용하여 설치를 자동화하는 경우는 다릅니다. 자격 증명이 발급된 지 12시간이 지난 후에 실행되는 모든 작업은 자격 증명이 이미 만료되었기 때문에 실패합니다. 이 문제를 해결하려면 UI로 돌아가서 안내 설치를 다시 실행하여 새 자격 증명을 받아야 합니다.

이 페이지에서는 수동 단계 없이 설치를 자동화하는 두 가지 방법을 다룹니다. 두 방법 모두 뉴렐릭 사용자 API 키 로 newrelic-auth-cli 인증되며, 안내 설치 자체에서 의존하는 것과 동일한 도구인 을(를) 사용합니다.

다음 접근 방식에는 두 가지 규칙이 적용됩니다:

  • 각 호스트 또는 설치 타겟은 여전히 자체 ID를 가지며, 이는 해당 대상을 위해 새로 생성됩니다.
  • 프라이빗 키는 생성된 머신 외부로 절대 이동하지 않습니다. 다른 ID 생성을 승인하는 재사용 가능한 ID(이 가이드의 뒷부분에서 설명하는 재사용 가능한 ID 접근 방식)를 하나 설정하면, 해당 프라이빗 키는 자동화를 제어하는 머신에 유지됩니다. 해당 키에서 파생된 수명이 짧은 액세스 토큰만 다른 곳으로 전달되며, 키 자체는 절대 전달되지 않습니다.

아래의 어떤 접근 방식을 사용하든 각 호스트에서 실행되는 ID는 만료되지 않습니다. 이는 안내 설치가 생성하는 만료되지 않는 ID와 동일합니다. 이 페이지의 두 접근 방식 모두 런타임 ID가 무엇인지 변경하지 않으며, 생성되는 방식만 변경합니다.

가끔씩 수행하는 설치를 위해 수명이 짧은 자격 증명을 생성하십시오.

재사용 가능한 ID를 관리해야 할 만큼 자주 설치하지 않는 경우, 이것이 가장 간단한 방법입니다. 파이프라인은 API 키로 인증하여 일회용 자격 증명을 생성하고, 이를 한 번 사용하여 일반적인 newrelic install 명령을 실행하며, 인스톨러는 에이전트 컨트롤이 실제로 실행되는 장기 ID를 생성합니다. 사용자가 직접 해당 장기 ID를 보거나 저장하지 않습니다. 인스톨러가 이를 호스트에 직접 기록합니다.

Ansible, Chef, Puppet은 모두 뉴렐릭에서 유지 관리하는 자체 공식 역할, 쿡북 또는 모듈을 통해 동일한 설치 명령을 사용하며, 각각 임의의 환경 변수를 해당 명령에 직접 전달합니다. 먼저 자격 증명을 생성한 다음, 라이선스 키를 전달하는 것과 동일한 방식으로 환경 변수로 설치 작업에 전달하십시오.

bash
$
#!/bin/bash
$
set -e
$
$
# Set these from your CI secrets store. NEW_RELIC_API_KEY should be a User API
$
# key (NRAK-...). It's used once below and never written to disk.
$
: "${NEW_RELIC_API_KEY:?}" "${NEW_RELIC_ACCOUNT_ID:?}" "${NEW_RELIC_ORGANIZATION:?}" \
>
"${NEW_RELIC_REGION:?}" "${NR_CLI_FLEET_ID:?}"
$
$
# 1. Download the latest auth CLI. GitHub's /releases/latest/download/ redirect
$
# always resolves to the newest release, so there's no version to update here.
$
curl -sS -L \
>
"https://github.com/newrelic/newrelic-auth-rs/releases/latest/download/newrelic-auth-cli_amd64.tar.gz" \
>
-o /tmp/newrelic-auth-cli.tar.gz
$
tar -xzf /tmp/newrelic-auth-cli.tar.gz -C /tmp
$
/tmp/newrelic-auth-cli --version >&2
$
$
# 2. Create a fresh, throwaway credential for this install only. NR_AUTH_API_KEY
$
# is the env var newrelic-auth-cli itself reads, same value as
$
# NEW_RELIC_API_KEY above, just under the name this specific tool expects.
$
BOOTSTRAP=$(NR_AUTH_API_KEY="$NEW_RELIC_API_KEY" /tmp/newrelic-auth-cli create-bootstrap-identity secret \
>
--name "bootstrap-$(hostname)-$(date +%s)" \
>
--organization-id "$NEW_RELIC_ORGANIZATION" \
>
--environment "$NEW_RELIC_REGION")
$
$
NEW_RELIC_AUTH_CLIENT_ID=$(echo "$BOOTSTRAP" | jq -r '.client_id')
$
NEW_RELIC_AUTH_CLIENT_SECRET=$(echo "$BOOTSTRAP" | jq -r '.identity_type.L1.client_secret')
$
$
# 3. Install the New Relic CLI, then Agent Control. The installer generates
$
# this host's long-lived identity itself and writes it locally.
$
curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash
$
$
sudo NEW_RELIC_CLI_SKIP_CORE=1 \
>
NEW_RELIC_REGION="${NEW_RELIC_REGION}" \
>
NEW_RELIC_ACCOUNT_ID="${NEW_RELIC_ACCOUNT_ID}" \
>
NEW_RELIC_ORGANIZATION="${NEW_RELIC_ORGANIZATION}" \
>
NEW_RELIC_API_KEY="${NEW_RELIC_API_KEY}" \
>
NEW_RELIC_AUTH_CLIENT_ID="${NEW_RELIC_AUTH_CLIENT_ID}" \
>
NEW_RELIC_AUTH_CLIENT_SECRET="${NEW_RELIC_AUTH_CLIENT_SECRET}" \
>
NR_CLI_FLEET_ID="${NR_CLI_FLEET_ID}" \
>
/usr/local/bin/newrelic install -y -n agent-control
$
$
rm -f /tmp/newrelic-auth-cli.tar.gz /tmp/newrelic-auth-cli

여기의 어떤 것도 권한이 있는 사용자나 상시 액세스 권한이 있는 서비스 계정으로 실행할 필요가 없습니다. API 키는 이 한 번의 설치를 위해 이 하나의 스크립트에만 사용됩니다.

하나의 플레이북 실행으로 여러 호스트에 설치하는 경우, Ansible 컨트롤러에서 일회용 자격 증명을 한 번 생성한 다음 newrelic.newrelic_install 역할을 통해 해당 실행의 모든 호스트 작업에 전달하십시오. 각 호스트는 여전히 고유하고 수명이 긴 자체 ID를 갖게 됩니다. 설치를 승인하는 데 사용되는 일회용 자격 증명만 해당 단일 실행의 호스트 간에 공유되며, 실행이 끝나면 폐기됩니다.

# site.yml
---
- name: Create a throwaway bootstrap credential for this run
hosts: localhost
gather_facts: false
tasks:
- name: Download the latest newrelic-auth-cli
ansible.builtin.get_url:
# GitHub's /releases/latest/download/ redirect always resolves to the
# newest release, so there's no version variable to keep in sync here.
url: "https://github.com/newrelic/newrelic-auth-rs/releases/latest/download/newrelic-auth-cli_amd64.tar.gz"
dest: /tmp/newrelic-auth-cli.tar.gz
mode: "0644"
- name: Extract newrelic-auth-cli
ansible.builtin.unarchive:
src: /tmp/newrelic-auth-cli.tar.gz
dest: /tmp/
remote_src: true
- name: Record the newrelic-auth-cli version used for this run
ansible.builtin.command:
cmd: /tmp/newrelic-auth-cli --version
register: nr_auth_cli_version
changed_when: false
- name: Show the newrelic-auth-cli version used for this run
ansible.builtin.debug:
msg: "{{ nr_auth_cli_version.stdout }}"
- name: Create the bootstrap credential
ansible.builtin.command:
cmd: >
/tmp/newrelic-auth-cli create-bootstrap-identity secret
--name "ansible-bootstrap-{{ ansible_date_time.epoch }}"
--organization-id {{ newrelic_organization }}
--environment {{ newrelic_region }}
environment:
NR_AUTH_API_KEY: "{{ newrelic_api_key }}"
register: bootstrap_output
no_log: true
- name: Save the bootstrap credential for the install play below
ansible.builtin.set_fact:
nr_bootstrap_client_id: "{{ (bootstrap_output.stdout | from_json).client_id }}"
nr_bootstrap_client_secret: "{{ (bootstrap_output.stdout | from_json).identity_type.L1.client_secret }}"
no_log: true
- name: Install Agent Control
hosts: all
become: true
roles:
- role: newrelic.newrelic_install
vars:
targets:
- agent-control
environment:
NEW_RELIC_API_KEY: "{{ newrelic_api_key }}"
NEW_RELIC_ACCOUNT_ID: "{{ newrelic_account_id }}"
NEW_RELIC_REGION: "{{ newrelic_region }}"
NEW_RELIC_ORGANIZATION: "{{ newrelic_organization }}"
NEW_RELIC_AUTH_CLIENT_ID: "{{ hostvars['localhost']['nr_bootstrap_client_id'] }}"
NEW_RELIC_AUTH_CLIENT_SECRET: "{{ hostvars['localhost']['nr_bootstrap_client_secret'] }}"
NR_CLI_FLEET_ID: "{{ newrelic_fleet_id }}"

이 역할은 NEW_RELIC_API_KEY 및 NEW_RELIC_ACCOUNT_ID이(가) 플레이의 environment: 블록에 설정되어 있는지 확인하고 누락된 경우 실패하지만, 동일한 블록에 있는 다른 모든 변수를 설치 명령으로 바로 전달하며, 이 명령은 부트스트랩 자격 증명과 조직 ID를 전달하는 역할을 합니다. 이 실행 중에는 newrelic_api_key 또는 부트스트랩 자격 증명의 어떤 내용도 파일에 기록되지 않으며, no_log: true은(는) 두 가지 모두 Ansible의 자체 로그에 남지 않도록 합니다.

chef-install 쿡북의 newrelic_install 리소스는 기본 설치 명령으로 바로 전달되는 env 해시를 허용하며, 이는 Linux 및 Ansible 예제에서 사용하는 것과 동일한 메커니즘입니다. 리소스를 선언하기 전에 레시피에서 부트스트랩 자격 증명을 생성한 다음, env을(를) 통해 출력을 전달하십시오:

require 'json'
# GitHub's /releases/latest/download/ redirect always resolves to the newest
# release, so there's no version to keep in sync with this recipe.
newrelic_auth_cli_url = 'https://github.com/newrelic/newrelic-auth-rs/releases/latest/download/newrelic-auth-cli_amd64.tar.gz'
system("curl -sS -L '#{newrelic_auth_cli_url}' -o /tmp/newrelic-auth-cli.tar.gz && tar -xzf /tmp/newrelic-auth-cli.tar.gz -C /tmp")
Chef::Log.info("newrelic-auth-cli version: #{`/tmp/newrelic-auth-cli --version`.strip}")
bootstrap = JSON.parse(`NR_AUTH_API_KEY=#{node['newrelic']['api_key']} /tmp/newrelic-auth-cli create-bootstrap-identity secret \
--name "chef-bootstrap-#{node.name}-#{Time.now.to_i}" \
--organization-id #{node['newrelic']['organization']} \
--environment #{node['newrelic']['region']}`)
newrelic_install 'agent-control' do
action :install
new_relic_api_key node['newrelic']['api_key']
new_relic_account_id node['newrelic']['account_id']
new_relic_region node['newrelic']['region']
targets ['agent-control']
env(
'NEW_RELIC_ORGANIZATION' => node['newrelic']['organization'],
'NEW_RELIC_AUTH_CLIENT_ID' => bootstrap['client_id'],
'NEW_RELIC_AUTH_CLIENT_SECRET' => bootstrap.dig('identity_type', 'L1', 'client_secret'),
'NR_CLI_FLEET_ID' => node['newrelic']['fleet_id']
)
end

Chef 레시피는 일반 루비로 위에서 아래로 평가되기 때문에 이 방법이 작동합니다. newrelic_install이(가) 선언될 때쯤이면 bootstrap은(는) 나중에 컴퓨트되는 것이 아니라 이미 실제 값을 보유하고 있습니다.

puppet-install 모듈의 newrelic_installer::install 클래스도 environment_variables 해시를 설치 명령으로 바로 전달하지만, Puppet은 카탈로그의 리소스 파라미터를 적용하기 전에 컴파일하므로 클래스 파라미터는 Chef의 일반 루비 레시피처럼 동일한 실행에서 이전 리소스가 생성한 값을 보유할 수 없습니다. 이 특정 사례의 경우, Linux 탭의 동일한 생성 후 설치 시퀀스를 하나의 스크립트로 래핑하고, 모듈 파일로 포함한 다음, 알려진 값을 환경 변수로 전달하여 실행하십시오:

# Save the Linux tab's script as files/agent-control-automated-install.sh
# in this module, then:
class profile::agent_control_install (
String $newrelic_api_key,
String $newrelic_account_id,
String $newrelic_organization,
String $newrelic_region = 'US',
String $newrelic_fleet_id = '',
) {
file { '/opt/newrelic-agent-control-install.sh':
ensure => file,
mode => '0700',
source => 'puppet:///modules/profile/agent-control-automated-install.sh',
}
-> exec { 'run newrelic-agent-control-install':
command => '/opt/newrelic-agent-control-install.sh',
path => ['/usr/bin', '/bin', '/usr/local/bin'],
environment => [
"NEW_RELIC_API_KEY=${newrelic_api_key}",
"NEW_RELIC_ACCOUNT_ID=${newrelic_account_id}",
"NEW_RELIC_ORGANIZATION=${newrelic_organization}",
"NEW_RELIC_REGION=${newrelic_region}",
"NR_CLI_FLEET_ID=${newrelic_fleet_id}",
'NEW_RELIC_CLI_SKIP_CORE=1',
],
unless => 'test -f /etc/newrelic-agent-control/keys/agent-control-identity.key',
logoutput => true,
}
}

실행할 때마다 새로운 ID를 사용하는 대신 각각 고유한 재사용 가능한 ID가 필요한 호스트 플릿을 관리하는 경우, 이 페이지의 두 번째 접근 방식(동일한 environment_variables 해시를 통해 전달되는 토큰)이 실행별 부트스트랩 자격 증명보다 Puppet의 모델에 더 직접적으로 부합합니다. 새로 생성된 자격 증명과 달리 토큰은 컴파일 시 알려진 값으로 Hiera에서 가져올 수 있기 때문입니다.

Linux와 동일한 형태이며, install.sh 대신 newrelic-auth-cli 및 install.ps1의 Windows 빌드를 사용합니다.

대규모 설치 또는 Terraform에서의 설치를 위해 재사용 가능한 ID를 하나 설정하십시오.

호스트 또는 클러스터에서 에이전트 컨트롤을 관리하는 Terraform 리소스는 매 실행마다 새로운 일회용 자격 증명이 아니라 plan 및 apply 주기 전반에 걸쳐 안정적인 것이 필요합니다. 한 번에 하나의 호스트가 아니라 시간이 지남에 따라 여러 호스트를 설치하는 모든 파이프라인에도 동일하게 적용됩니다. 이를 위해 재사용 가능한 "상위" ID를 한 번 설정하고, 프라이빗 키를 다른 곳으로 이동하지 않고 이후의 모든 설치를 승인하는 데 사용하십시오.

중요

이 섹션에서는 newrelic-auth-cli을(를) 직접 호출하는 방법을 설명합니다. 특히 Terraform으로 이를 설정하는 경우, Terraform을 사용한 에이전트 컨트롤 설정도 참조하십시오.

1단계: 상위 ID 한 번 생성

두 번째 상위 ID가 필요한 경우에만 이 단계를 반복하며, 설치할 때마다 반복하지는 않습니다. create-bootstrap-identity key은(는) 로컬에서 키 쌍을 생성하고 공개 키 부분만 뉴렐릭에 전송하며 새 ID에 다른 ID를 생성할 수 있는 권한을 자동으로 부여하므로, 이를 위한 별도의 단계가 없습니다.

bash
$
# GitHub's /releases/latest/download/ redirect always resolves to the newest release,
$
# so there's no version to update here.
$
curl -sS -L \
>
"https://github.com/newrelic/newrelic-auth-rs/releases/latest/download/newrelic-auth-cli_amd64.tar.gz" \
>
-o /tmp/newrelic-auth-cli.tar.gz
$
tar -xzf /tmp/newrelic-auth-cli.tar.gz -C /tmp
$
/tmp/newrelic-auth-cli --version >&2
$
$
NR_AUTH_API_KEY="$NEW_RELIC_API_KEY" /tmp/newrelic-auth-cli create-bootstrap-identity key \
>
--name "terraform-parent" \
>
--organization-id "$NEW_RELIC_ORGANIZATION" \
>
--environment "$NEW_RELIC_REGION" \
>
--output-platform local-file \
>
--output-local-filepath /path/to/store/parent-private-key.pem

newrelic-auth-cli --api-key 플래그 대신 이 페이지의 다른 명령이 사용하는 것과 동일한 환경 변수 패턴인 여기의 NR_AUTH_API_KEY에서 API 키를 읽습니다. 명령줄에 직접 전달된 값은 프로세스가 실행되는 동안 ps 출력 및 셸 기록에 계속 표시되며 이 키는 만료되지 않으므로 특히 이 단계에서는 피하는 것이 좋습니다.

ID의 client_id을(를) 다시 출력합니다(프라이빗 키는 출력되지 않고 지정한 경로에 바로 기록됩니다). 해당 프라이빗 키 파일을 자동화를 제어하는 시크릿 저장소로 이동하고, 이를 생성한 머신에 복사본을 남겨두지 마십시오.

2단계: 각 설치에 대해 상위에서 수명이 짧은 토큰을 생성하십시오.

상위의 개인 키는 로컬에 유지됩니다. 타겟 호스트로 전달되는 것은 약 1시간 후에 만료되는 전달자 토큰입니다:

bash
$
TOKEN=$(/tmp/newrelic-auth-cli authenticate \
>
--client-id "$PARENT_CLIENT_ID" \
>
--environment "$NEW_RELIC_REGION" \
>
--private-key-path "$PARENT_PRIVATE_KEY_PATH" \
>
--output-token-format PLAIN)

NEW_RELIC_AUTH_TOKEN을(를) 설정하여 프라이빗 키가 아닌 해당 토큰을 설치 단계에 전달하십시오. 이 가이드 앞부분의 가끔 설치하기 위한 단기 자격 증명 생성 섹션에 있는 어떤 도구가 설치를 주도하든 관계없이 동일한 방식으로 작동하며, Ansible의 environment:, Chef의 env, Puppet의 environment_variables은 모두 클라이언트 시크릿을 전달하는 것과 정확히 동일하게 이를 전달합니다:

bash
$
sudo NEW_RELIC_CLI_SKIP_CORE=1 \
>
NEW_RELIC_REGION="${NEW_RELIC_REGION}" \
>
NEW_RELIC_ACCOUNT_ID="${NEW_RELIC_ACCOUNT_ID}" \
>
NEW_RELIC_ORGANIZATION="${NEW_RELIC_ORGANIZATION}" \
>
NEW_RELIC_AUTH_TOKEN="${TOKEN}" \
>
NR_CLI_FLEET_ID="${NR_CLI_FLEET_ID}" \
>
/usr/local/bin/newrelic install -y -n agent-control

Windows에서는 install.ps1이(가) -AuthParentToken와(과) 동일한 값을 가집니다. 설치 단계에서는 해당 토큰을 한 번 사용하여 타겟 호스트의 로컬에 자체 하위 ID를 생성하며, 이것이 실제로 에이전트 컨트롤이 실행되는 기반입니다. 상위 ID와 해당 개인 키는 해당 호스트에 절대 접근하지 않습니다.

각 호스트는 여전히 새로 생성된 자체 ID를 가져옵니다. 여기서 재사용할 수 있는 것은 이를 생성하도록 승인하는 상위 항목뿐입니다.

상위 ID 저장 및 교체

상위 프라이빗 키는 만료되지 않으므로 계정에 대한 액세스 권한을 부여하는 다른 수명이 긴 자격 증명과 동일하게 취급하십시오. 사람이나 크론(cron) 작업이 쉽게 읽을 수 있는 디스크 어딘가에 두지 말고, 시크릿 관리자(HashiCorp Vault, AWS Secrets Manager 또는 조직에서 이미 사용하는 모든 것)에 보관하십시오.

상위 ID에 대한 제자리 교체 명령은 없습니다. 이를 교체하려면 1단계를 반복하여 새 상위 항목을 생성하고, 자동화가 이를 가리키도록 한 다음, 이전 항목의 사용을 중지해야 합니다. 또한 아직 플랫폼에서 상위 ID를 비활성화하거나 삭제할 수 있는 방법이 없으므로, 이전 ID를 폐기한다는 것은 자동화가 해당 키의 제시를 중단한다는 의미이지 ID 자체가 사라진다는 의미는 아닙니다. 교체 주기를 원할 경우, 이와 같은 자격 증명에 대해서는 연간 교체가 합리적인 기본값입니다.

Copyright © 2026 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.