An Ansible role that can be used to install and/or configure the New Relic Infrastructure Agent and install New Relic Infrastructure OHIs.
To use the newrelic.newrelic-infra role directly in a playbook, simply
include the role in your playbook. For example,
# myplaybook.yml
---
- hosts: webservers
roles:
- role: newrelic.newrelic-infra
vars:
nrinfragent_config:
license_key: 12345To require newrelic.newrelic-infra as a role depencency your own role,
add a dependency in the meta/main.yml of your role. For example,
# roles/myapp/meta/main.yml
---
dependencies:
- role: newrelic.newrelic-infraThis role can be used for the following interactions with the New Relic Infrastructure Agent.
- Install the agent via OS package manager
- Install the agent via tarball (Linux only)
- Install integrations via OS package manager
- Configure the agent
- Setup the agent init service
By default, the role will install the agent via the OS package maanger, install any integrations via the OS package manager, configure the agent, and setup the agent init service. Additionally, the following tags are available to perform other interactions.
- nria_install
- nria_install_tarball
- nria_install_integrations
- nria_configure
- nria_setup_service
The following snippet will install the agent via the OS package manager, configure the agent with the specified configuration and setup the agent OS init service.
---
- hosts: ap_ne_1
roles:
- name: newrelic.newrelic-infra
vars:
log_file: /opt/logs/newrelic-infra.log
verbose: 0
nrinfragent_config:
license_key: 12345
custom_attributes:
environment: devTo install using the tarball installation method, you must set the nrinfragent_tarball_version variable to a valid
tarball version number.
Installation via the tarball installation method will also run the configuration
and agent OS init service tasks unless the nria_install_tarball tag is
specified.
- hosts: ap_ne_1
roles:
- name: newrelic.newrelic-infra
vars:
nrinfragent_tarball_version: 1.18.0
nrinfragent_tarball_download_dir: /opt/newrelic/
nrinfragent_config:
log_file: /opt/logs/newrelic-infra.log
verbose: 0
license_key: 12345
custom_attributes:
environment: devTo use a local tarball instead of downloading it from the web you need to set
nrinfragent_tarball_local_file_path variable to a local path of the tarball from
http://download.newrelic.com/infrastructure_agent/binaries/linux/{{ architecture }}/newrelic-infra_linux_{{ version }}_{{ architecture }}.tar.gz.
- hosts: ap_ne_1
roles:
- name: newrelic.newrelic-infra
vars:
nrinfragent_tarball_version: 1.18.0
nrinfragent_tarball_download_dir: /opt/newrelic/
nrinfragent_tarball_from_local: yes
nrinfragent_config:
log_file: /opt/logs/newrelic-infra.log
verbose: 0
license_key: 12345
custom_attributes:
environment: devThe following snippet will only configure the agent configuration of an existing
installation as long as the playbook is run with --tags nria_configure. Note
that the include_role must be used in this case.
- hosts: ap_ne_1
tasks:
- name: configure the New Relic Infrastructure Agent
include_role:
name: newrelic.newrelic-infra
vars:
nrinfragent_config:
license_key: 12345
log_file: /opt/logs/newrelic-infra.log
verbose: 0
custom_attributes:
environment: dev
tags:
- nria_configureThe role configuration variables are documented inline as well as below.
Install or uninstall packages (package manager installation). Package manager installations are performed using the Ansible package module.
'latest'- [default] install the latest version of the agent. Alsopresent.'absent'- Uninstall the agent.
Specifies the state of the newrelic-infra service after install. Defaults to
started, which ensures the service will be running. Change it to stopped to
install only, without starting it right away. See additional information about
valid values in the
Ansible service module documentation.
Specifies if the service will start during boot. Defauts to yes. change it to
no to prevent the service from starting automatically on boot. See additional information about
valid values in the
Ansible service module documentation.
Specifies a custom path on the to the New Relic Infrastructure Agent
configuration file on the target
hosts. Defaults to /etc/newrelic-infra.yml on Linux and
%ProgramFiles%\New Relic\newrelic-infra\newrelic-infra.yml on Windows. This
can be especially useful on Linux tarball installs
when installing to non-default locations.
Used to populate the agent configuration. At a minimum you must provide
license_key. For current configuration options, see the
New Relic documentation. For example:
custom_attributes:
business_unit: sales
team: newrelic
license_key: D000000000000000000000000000000000000000
log_file: /tmp/logs.log
verbose: 1Specifies the On-Host Integrations to be installed via the OS package manager. The list of available integrations can be found here.
Each package should provide its name and state. The integrations package
name is located in the Install and activate section of the
individual integrations docs. As
a convention, their name is the name of the service with the nri- prefix
(nri-apache, nri-redis, etc.).
By default the state it's absent, which doesn't install the package; you can
change it to latest or present. For example:
nrinfragent_integrations:
- name: nri-nginx
state: latest
- name: nri-mysql
state: absentThe source code for each integration is available on newrelic's GitHub organization.
You can specify the license key via the top level license_key for backward
compatibility. We recommend that you use license_key in nrinfragent_config
instead. If both are specified, the one in nrinfragent_config takes
precedence.
Specifies the New Relic Infrastructure agent tarball version to download. Linux only.
Specifies the directory on the target hosts in which to download and unzip tarball.
Specifies the agent home directory path on the target hosts. Same as the
NRIA_AGENT_DIR [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to /var/db/newrelic-infra/.
Specifies the agent binary directory path on the target hosts. Same as the
NRIA_BIN_DIR [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to /usr/local/bin/.
Specifies the agent log file path on the target hosts. Same as the
NRIA_LOG_FILE [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to /var/run/newrelic-infra/newrelic-infra.log.
Specifies the agent privilege level. Same as the
NRIA_MODE [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to ROOT.
Specifies the agent PID file path on the target hosts. Same as the
NRIA_PID_FILE [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to /var/run/newrelic-infra/newrelic-infra.pid.
Specifies the agent plugin directory path on the target hosts. Same as the
NRIA_PLUGIN_DIR [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to /etc/newrelic-infra/integrations.d/.
Specifies the user the agent binary will be run ason the target hosts. Same as
the NRIA_USER [parameter] (https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/linux-installation/tarball-assisted-install-infrastructure-agent-linux/#parameters).
Defaults to root.
Specifies the target OS that the infrastructure agent will be installed on.
Defaults to ansible_os_family. For a list of supported operating systems,
see the meta/main.yml file.
Specifies the OS version of the installer package needed for this machine.
Defaults to ansible_lsb.major_release. Mostly used for RedHat family OSs.
For a list of supported operating systems, see the
meta/main.yml file.
Specifies the OS codename of the installer package needed for this machine.
Defaults to ansible_lsb.codename. This is used on the Debian family OSs.
For a list of supported operating systems, see the
meta/main.yml file.
Specifies the version of the Chocolatey package to install newrelic-infra
on Windows. Can be used to pin the version or upgrade the agent.
Used to set lock_timeout value for ansible yum module. When it's not set this value defaults to 30. Works only for ansible version >= 2.8.0
Used to generate logging file. At a minimum you must provide
name, source_type, source_value. For current configuration options, see the
New Relic documentation. To create multiple log blocks enter additional - name lists. For example:
vars:
nrinfragent_logging:
- name: Name of the logs that you want to forward to newrelic one [required]
source_type: type of the logs you want to forward - file/systemd/syslog/tcp/winlog [required]
source_value: ONLY FILE/SYSTEMD - value of the source type https://docs.newrelic.com/docs/logs/enable-log-management-new-relic/enable-log-monitoring-new-relic/forward-your-logs-using-infrastructure-agent/#log-source-required
syslog: [required if source_type is syslog]
uri: Syslog socket. Format varies depending on the protocol
TCP/UDP network sockets - [tcp/udp]://LISTEN_ADDRESS:PORT
Unix domain sockets unix_[tcp/udp]:// + /socket/path
parser: Syslog parser. Default is rfc3164. Use rfc5424 if your messages include fractional seconds. Note - rfc3164 currently does not work on SuSE.
permissions: default is 0644 for domain sockets; this limits entries to processes running as root. You can use 0666 to listen for non-root processes, at your own risk.
tcp: [required if source_type is tcp]
uri: TCP/IP socket to listen for incoming data. The URI format is tcp://LISTEN_ADDRESS:PORT
format: format of the data. It can be json or none.
separator: If format - none is used, you can define a separator string for splitting records (default - \n).
winlog: [required if source_type is winlog]
channel: name of the channel logs will be collected from.
collect_eventids: a list of Windows Event IDs to be collected and forwarded to New Relic. Event ID ranges are supported.
exclude_eventids: a list of Windows Event IDs to be excluded from collection. Event ID ranges are supported.
pattern: Regular expression for filtering records. Only supported for the tail, systemd, syslog, and tcp (only with format none) sources.
max_line_kb: Maximum size of log entries/lines in KB. If log entries exceed the limit, they are skipped. Default is 128.
fluentbit: External Fluent Bit configuration and parser files.
config_file: path to an existing Fluent Bit configuration file. Note that any overlapping source results in duplicate messages in New Relic Logs.
parser_file: path to an existing Fluent Bit parsers file. The following parser names are reserved: rfc3164, rfc3164-local and rfc5424.
custom_attributes: List of custom attributes as key-value pairs that can be used to send additional data with the logs which you can then query. Add attributes to any log source. Expects data in the following format -
"
custom_attributes: [
{ 'key': 'value'},
{ 'key2': 'value2'},
...
]
"
- name: Name of the logs that you want to forward to newrelic one [required]
source_type: type of the logs you want to forward - file/systemd/syslog/tcp/winlog [required]
source_value: ONLY FILE/SYSTEMD - value of the source type https://docs.newrelic.com/docs/logs/enable-log-management-new-relic/enable-log-monitoring-new-relic/forward-your-logs-using-infrastructure-agent/#log-source-requiredThis only applies if you have the
newrelic-infra-integrationspackage installed
If you want to remove the newrelic-infra-integrations package or any of the
bundled integrations (nri-redis, nri-cassandra, nri-apache, nri-nginx,
nri-mysql), add newrelic-infra-integrations as the first item of
nrinfragent_integrations with the state absent.
nrinfragent_integrations:
- name: newrelic-infra-integrations
state: "absent"The infrastructure-agent-ansible role uses molecule
for testing. Three scenarios are provided.
- The default scenario tests installation and configuration of the agent and setup of OS init services all via the OS package manager.
- The configure scenario tests running configuration
of the agent only using the
nria_coniguretag. Note that in order to run this test, thedefaultscenario'screateandconvergemethod should be run first so theconfigurescenario has an installed agent to test with. - The targz scenario tests installation and configuration of the agent and setup of OS init services using the tarball installation method.
The default and targz scenarios can be run in full using molecule test.
Note that the test command will destroy the containers after testing and
verifying the scenario. Therefore, the best way to run the configure scenario
is to use molecule converge && molecule test -s configure && molecule destroy.
To release a new version to Ansible Galaxy follow this steps:
- Update the CHANGELOG.md
- Create a new GitHub release.
- Watch the build with the version number in Github Actions: https://github.com/newrelic/infrastructure-agent-ansible/actions
- Make sure the version is imported into Ansible Galaxy, if there is any issue, ask one of the project owners.
- RHEL/CentOS
- RHEL/CentOS 8
- RHEL/CentOS 7
- RHEL/CentOS 6
- RHEL/CentOS 5
- Ubuntu
- 18 Bionic
- 16 Xenial
- 14 Trusty
- 12 Precise
- Debian
- 10 Buster
- 9 Stretch
- 8 Jessie
- 7 Wheezy
- SUSE Linux Enterprise
- 12
- Windows
- All
- Disclaimer: Windows support depends on the third-party newrelic-infra Chocolatey package which is maintained by @ripclawffb and @xandrellas. It is distributed without any guarantee or support from New Relic.
New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads here:
- New Relic Documentation: Comprehensive guidance for using our platform
- New Relic Community: The best place to engage in troubleshooting questions
- New Relic Developer: Resources for building a custom observability applications
- New Relic University: A range of online training for New Relic users of every level
- New Relic Technical Support 24/7/365 ticketed support. Read more about our Technical Support Offerings.
We encourage your contributions to improve [project name]! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.
If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com.
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
If you would like to contribute to this project, review these guidelines.
To all contributors, we thank you! Without your contribution, this project would not be what it is today.
infrastructure-agent-ansible is licensed under the Apache 2.0 License.