⚠️	New Relic offers a new Ansible solution that simplifies scaling your New Relic Observability efforts. Please consider using this solution going forward.

Ansible role for the New Relic infrastructure agent

An Ansible role that can be used to install and/or configure the New Relic Infrastructure Agent and install New Relic Infrastructure OHIs.

Installation

Use the following command to download the latest version of the New Relic role:

ansible-galaxy install newrelic.newrelic-infra

Getting Started

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: 12345

To 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-infra

Usage

This 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

Basic Usage

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: dev

Tarball Installation (Linux Only)

To 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: dev

Tarball installation "offline"

To 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: dev

Configure Only

The 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_configure

Reference

Role configuration

Variables

The role configuration variables are documented inline as well as below.

nrinfragent_state (Optional)

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. Also present.
• 'absent' - Uninstall the agent.

nrinfragent_service_state (Optional)

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.

nrinfragent_service_enabled (Optional)

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.

nrinfragent_config_file (Optional)

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.

nrinfragent_config (Required)

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: 1

nrinfragent_integrations (Optional)

Specifies 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: absent

The source code for each integration is available on newrelic's GitHub organization.

license_key (DEPRECATED)

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.

nrinfragent_tarball_version (Required for Tarball Installation Only)

Specifies the New Relic Infrastructure agent tarball version to download. Linux only.

nrinfragent_tarball_download_dir (Required for Tarball Installation Only)

Specifies the directory on the target hosts in which to download and unzip tarball.

nrinfragent_tarball_agent_dir (Optional, Tarball Installation Only)

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/.

nrinfragent_tarball_bin_dir (Optional, Tarball Installation Only)

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/.

nrinfragent_tarball_log_file (Optional, Tarball Installation Only)

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.

nrinfragent_tarball_mode (Optional, Tarball Installation Only)

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.

nrinfragent_tarball_pid_file (Optional, Tarball Installation Only)

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.

nrinfragent_tarball_plugin_dir (Optional, Tarball Installation Only)

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/.

nrinfragent_tarball_user (Optional, Tarball Installation Only)

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.

nrinfragent_os_name (Optional)

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.

nrinfragent_os_version (Optional)

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.

nrinfragent_os_codename (Optional)

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.

---

nrinfragent_choco_version (Optional, Windows only)

Specifies the version of the Chocolatey package to install newrelic-infra on Windows. Can be used to pin the version or upgrade the agent.

nrinfragent_yum_lock_timeout (Optional)

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

nrinfragent_logging (optional)

Used to generate logging file. For current configuration options, see the New Relic documentation. To create multiple log blocks enter additional - name lists. For example:

vars:
  nrinfragent_logging:
    - name: example-log
      file: /var/log/example.log # Path to a single log file

    - name: docker-logs
      file: /var/lib/docker/containers/*/*.log # Path to multiple folders and files

    - name: systemd-example
      systemd: cupsd

    # TCP network socket
    - name: syslog-tcp-test
      syslog:
        uri: tcp://0.0.0.0:5140 # Use the tcp://LISTEN_ADDRESS:PORT format
        parser: rfc5424 # Default syslog parser is rfc3164

    # Unix TCP domain socket
    - name: syslog-unix-tcp-test
      syslog:
        uri: unix_tcp:///var/unix-tcp-socket-test
        unix_permissions: 0666 # Default is 0644. Change at your own risk

    # Unix UDP domain socket
    - name: syslog-unix-udp-test
      syslog:
        uri: unix_udp:///var/unix-udp-socket-test
        parser: rfc5424

    - name: tcp-simple-test
      tcp:
        uri: tcp://0.0.0.0:1234 # Use the tcp://LISTEN_ADDRESS:PORT format
        format: none # Raw text - this is default for 'tcp'
        separator: \t # String for separating raw text entries
      max_line_kb: 32

    - name: tcp-json-test
      tcp:
        uri: tcp://0.0.0.0:2345 # Use the tcp://LISTEN_ADDRESS:PORT format
        format: json

Removing the newrelic-infra-integrations package and its bundled integrations

This only applies if you have the newrelic-infra-integrations package 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"

Testing

The infrastructure-agent-ansible role uses molecule for testing. Three scenarios are provided.

1. The default scenario tests installation and configuration of the agent and setup of OS init services all via the OS package manager.
2. The configure scenario tests running configuration of the agent only using the nria_conigure tag. Note that in order to run this test, the default scenario's create and converge method should be run first so the configure scenario has an installed agent to test with.
3. 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.

Release to Ansible Galaxy

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.

Compatibility

Platforms

• 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.

Support

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.

Contribute

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.

License

infrastructure-agent-ansible is licensed under the Apache 2.0 License.