--- title: Configure the infrastructure agent using Ansible source: https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/config-management-tools/configure-ansible --- You can use New Relic's Ansible role to help you scale your New Relic Observability efforts using the [New Relic CLI](https://github.com/newrelic/newrelic-cli) and [New Relic Open Installation repository](https://github.com/newrelic/open-install-library). For instructions on how to use Ansible, see the [Ansible documentation](https://docs.ansible.com/). This is a [community-supported](https://github.com/newrelic/ansible-install) effort. Want to configure the infrastructure agent using Ansible? [Create a New Relic account](https://newrelic.com/signup) for free! No credit card required. > #### ⚠️ IMPORTANT > > This role will always install the latest released version of the New Relic agent and doesn't support installing older versions. ## Sample code [#role-description] New Relic provides configuration management sample code to help you install our infrastructure agent using workflows and tools that are common with many Ops teams. This is a basic Ansible role and is intended to be used as a starting place for creating your own customized workflow. Configuration depends on your specific setup and standards. To view an Ansible sample role and more integration information, see the [Ansible Galaxy documentation](https://galaxy.ansible.com/newrelic/newrelic_install). ## Compatibility and requirements [#role-compatibility] The Ansible role with New Relic's infrastructure agent requires a [supported operating system](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/getting-started/compatibility-requirements-new-relic-infrastructure#operating-systems). If you need help with Ansible for Windows OS, take a look at [Setting up a Windows Host](https://docs.ansible.com/ansible/latest/os_guide/windows_setup.html), from the [Ansible Documentation](https://docs.ansible.com/ansible/latest/) site. This role is tested with the Ansible Core 2.13 and 2.14 and Python 3.10. Ansible Core versions before 2.10 are not supported. ## Set up New Relic with Ansible [#role-setup] ### Installation #### Ansible Galaxy [Link to Galaxy](https://galaxy.ansible.com/newrelic/newrelic_install) ```shell ansible-galaxy install newrelic.newrelic_install ``` Make sure you have `ansible.windows` and `ansible.utils` if they are not already installed: ```shell ansible-galaxy collection install ansible.windows ansible.utils ``` #### Manual If you want to use a local copy of the role, clone the repo and run `make` in the project root to copy this repo to `~/.ansible/roles/newrelic.newrelic_install`, enabling the role to behave as though it were installed from Galaxy. ### Getting started To get started using the role `newrelic.newrelic_install`: 1. Include the role in your playbook. 2. Customize the required variables. After installing, include the `newrelic.newrelic_install` role in a new or existing playbook. Here is an example of configuring your role to install the infrastructure agent: ```yml --- - name: Install New Relic hosts: all roles: - role: newrelic.newrelic_install vars: targets: - infrastructure - logs tags: foo: bar environment: NEW_RELIC_API_KEY: NEW_RELIC_ACCOUNT_ID: NEW_RELIC_REGION: ``` ## Role configuration variables [#role-config] Here are available variables for configuring the `newrelic.newrelic_install` role: | Variable | IsRequired | Description | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `targets` | Required | List of targeted installs to run on hosts. Available options are: - `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) | | `tags` | Optional | Key-value pairs of tags passed to the installation. | | `install_timeout_seconds` | Optional | Sets timeout for installation task. Overrides the default timeout of 600s. | | `verbosity` | Optional | Verbosity options for the installation (`debug` or `trace`) writes verbose output to a log file on the host. | ### Defaults Set in [defaults/main.yml](https://github.com/newrelic/ansible-install/blob/main/defaults/main.yml): - `cli_install_url` - `cli_install_download_location` - `target_name_map` - `verbosity_on_log_file_path_linux` - `verbosity_on_log_file_path_windows` - `default_install_timeout_seconds` ### Environment variables Values are set under the [`environment`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) keyword in your playbook: - `NEW_RELIC_API_KEY` (required) - `NEW_RELIC_ACCOUNT_ID` (required) - `NEW_RELIC_REGION` (optional: 'US', 'EU', or 'JP', default 'US') Additionally, you can set an optional `HTTPS_PROXY` variable to enable a proxy for your installation. **apm-php** - `NEW_RELIC_APPLICATION_NAME` (optional) The name of the PHP application to instrument. This name will be listed under New Relic's `APM & Services`. If omitted, it defaults to `PHP Application`. **apache** - `NEW_RELIC_APACHE_STATUS_URL` (optional) The URL to check the Apache web server status. This is used to ensure that an Apache web server is running on the host and is in a healthy state before attempting the installation of the Apache On-Host Integration. Defaults to: `http://127.0.0.1/server-status?auto` **mssql** - `NEW_RELIC_MSSQL_DB_HOSTNAME` (optional) Hostname or IP where MS SQL server is running. Defaults to discovered hostname if unspecified. - `NEW_RELIC_MSSQL_DB_PORT` (optional) Port on which MS SQL server is listening. Defaults to `1433` - `NEW_RELIC_MSSQL_DB_USERNAME` (optional) Username for accessing the MS SQL server. Defaults to `newrelic`. If using a domain user, use the syntax `domain\user` - `NEW_RELIC_MSSQL_DB_PASSWORD` (optional) Password for the given SQL or Domain user. If no password is provided, a random password will be generated. - `NEW_RELIC_MSSQL_SQL_USERNAME` (optional) Optional credential override passed to `sqlcmd` when creating the SQL user specified by `NEW_RELIC_MSSQL_DB_USERNAME`. If omitted, the default login username will be used. - `NEW_RELIC_MSSQL_SQL_PASSWORD` (optional) Optional credential override passed to `sqlcmd` when creating the SQL user specified by `NEW_RELIC_MSSQL_DB_USERNAME`. If omitted, the default login password will be used. - `NEW_RELIC_MSSQL_ENABLE_BUFFER_METRICS` (optional) Enable collection of buffer pool metrics. Defaults to true - `NEW_RELIC_MSSQL_ENABLE_RESERVE_METRICS` (optional) Enable collection of database partition reserve space. Defaults to true **mysql** - `NEW_RELIC_MYSQL_PORT` (optional) Defaults to `3306` if unspecified. - `NEW_RELIC_MYSQL_USERNAME` (optional) Defaults to `newrelic` if no other is specified. This is the username that the `mysql` integration will setup and will also set in the integration's configuration file (e.g.: `mysql-config.yml`) for data reporting purposes. See more in [MySQL integration](/install/mysql/). - `NEW_RELIC_MYSQL_PASSWORD` (optional) The password for the user specified in `NEW_RELIC_MYSQL_USERNAME`. See more in [MySQL integration](/install/mysql/). - `NEW_RELIC_MYSQL_ROOT_PASSWORD` (required) The `mysql` integration needs to connect to `mysql` to create the appropriate credentials. See [ansible's remote environment](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_environment.html) for more info. > #### ⚠️ IMPORTANT NOTE > > - The `logs` target requires `infrastructure`, and an error will be thrown if `logs` is specified without `infrastructure`. > - The `apm-nodejs` agent installation is supported only for apps managed by [PM2](https://pm2.keymetrics.io/). To install the agent using a package manager such as `npm` or `yarn` or via other installation paths, please reference our [docs](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/install-nodejs-agent/). > - The `apm-dotnet` agent installation for Windows is supported only for apps hosted by [IIS](https://www.iis.net/). Linux installations are only supported for .NET applications which run as a `systemd` service. > - The `apm-java` agent installation supports Java running in Tomcat, Wildfly/Jboss, and Jetty (standalone). > - The following integrations require the infrastructure agent to be installed: > - apm-java > - apache > - mssql > - mysql > - nginx ## Additional Example Playbook [#examples] ```yml - 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: NEW_RELIC_ACCOUNT_ID: NEW_RELIC_REGION: NEW_RELIC_APPLICATION_NAME: "My Application" HTTPS_PROXY: "http://my.proxy:8888" ```