New Relic Ansible Role

newrelic.newrelic_install is an Ansible Role designed to help you enhance your New Relic Observability capabilities. It utilizes the New Relic CLI and New Relic Open Installation repository to do this.

Important: You cannot install specific versions of an agent using this role; it will always install the latest version of a New Relic agent.

Please review the sections below for detailed information on installation, getting started, the role's variables, dependencies, and an example Ansible playbook showcasing how to use this role.

If you require assistance with Ansible on Windows OS, check out the guide on Setting up a Windows Host from the Ansible Documentation site.

Installation

Ansible Galaxy

To install the role, run the following command:

ansible-galaxy install newrelic.newrelic_install

Link to Galaxy

Make sure that you also have the ansible.windows and ansible.utils collections installed:

ansible-galaxy collection install ansible.windows ansible.utils

Manual

If you prefer to use a local copy of the role, clone the repository and run make in the project root. This action will copy the repository into ~/.ansible/roles/newrelic.newrelic_install, allowing it to act as if it was installed from Galaxy.

Getting Started

Once installed, include the newrelic.newrelic_install role in your playbook. Here’s an example:

- name: Install New Relic
  hosts: all
  roles:
    - role: newrelic.newrelic_install
      vars:
        targets:
          - infrastructure
          - logs
          - apm-php
        tags:
          foo: bar
  environment:
    NEW_RELIC_API_KEY: <API key>
    NEW_RELIC_ACCOUNT_ID: <Account ID>
    NEW_RELIC_REGION: <Region>

Variables

Role Variables

targets (Required)

This variable lists what you want to install on the hosts. Choices include:

• infrastructure (Linux & Windows)
• logs (Linux & Windows)
• apm-php (Linux)
• apm-nodejs (Linux)
• apm-dotnet (Linux & Windows)
• apm-java (Linux)
• apache (Linux)
• mssql (Windows)
• mysql (Linux)
• nginx (Linux)

Important Notes:

• The logs target requires the infrastructure target as well.
• The apm-nodejs agent installation is only supported for applications managed by PM2.
• The apm-dotnet agent installation for Windows is supported only for IIS-hosted apps. On Linux, it supports .NET applications running as a systemd service.
• The apm-java agent installation supports Java applications running in multiple environments like Tomcat and Jetty.
• The following integrations need the infrastructure agent to be installed:
  • apm-java
  • apache
  • mssql
  • mysql
  • nginx

tags (Optional)

This variable allows you to add key-value pairs as tags for the installation.

install_timeout_seconds (Optional)

This sets a timeout for installation tasks, overriding the default of 600 seconds.

verbosity (Optional)

This allows you to set the level of detail in logs (debug or trace).

Defaults

The default values are specified in defaults/main.yml.

Environment Variables

Set these in your playbook under the environment keyword:

• NEW_RELIC_API_KEY (required)
• NEW_RELIC_ACCOUNT_ID (required)
• NEW_RELIC_REGION (optional: 'US' or 'EU', defaults to 'US')

You can also set an optional HTTPS_PROXY variable to enable a proxy for your installation.

Additional variables for specific targets are also available; please refer to the documentation for details.

Versions Compatibility

• Ansible: Works with Ansible Core versions 2.13 and 2.14. Versions before 2.10 are not supported.
• Python: Works with Python version 3.10.

Dependencies

See the Python requirements in requirements.txt and Ansible requirements in requirements.yml.

Example Playbook

- name: Install New Relic
  hosts: all
  roles:
    - role: newrelic.newrelic_install
      vars:
        targets:
          - infrastructure
          - logs
          - apm-php
        tags:
          foo: bar
        install_timeout_seconds: 1000
        verbosity: debug
  environment:
    NEW_RELIC_API_KEY: <API key>
    NEW_RELIC_ACCOUNT_ID: <Account ID>
    NEW_RELIC_REGION: <Region>
    NEW_RELIC_APPLICATION_NAME: "My Application"
    HTTPS_PROXY: "http://my.proxy:8888"

Support

New Relic provides an online forum for users to interact with employees and each other for support and sharing best practices. You can explore the following resources:

• New Relic Documentation
• New Relic Community
• New Relic Developer
• New Relic University
• New Relic Technical Support

Contribute

We welcome your contributions to enhance the newrelic.newrelic_install Ansible role! When submitting your pull request, you will need to sign the Contributor License Agreement (CLA) using CLA-Assistant.

If you have questions or need to execute our corporate CLA, please email opensource@newrelic.com.

Note About Vulnerabilities

New Relic values customer privacy and security. If you suspect you have found a security vulnerability, please report it via HackerOne.

License

This project has an Apache 2.0 License.