nginxinc.nginx_management_suite

<!-- [![Ansible Galaxy](https://img.shields.io/badge/galaxy-nginxinc.nginx-5bbdbf.svg)](https://galaxy.ansible.com/nginxinc/nginx_management_suite) -->
[![Molecule CI/CD](https://github.com/nginxinc/ansible-role-nginx-management-suite/workflows/Molecule%20CI/CD/badge.svg)](https://github.com/nginxinc/ansible-role-nginx-management-suite/actions/workflows/molecule.yml/badge.svg)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# Ansible NGINX Management Suite Role

This role installs the NGINX Management Suite (NMS).

**Note:** The role is still being developed. There may be some issues, and variables may change.

## Requirements

1. NGINX Management Suite License Files
2. [NGINX Ansible Role (**nginxinc.nginx**)](https://github.com/nginxinc/ansible-role-nginx)

### NGINX Management Suite Certificate Files

To install NMS, you need the NMS certificate files. Access them by logging into [MyF5](https://account.f5.com/myf5) or using a link from the trial activation email to get the NMS **.crt** and **.key** files:

* nginx-mgmt-suite-trial.key
* nginx-mgmt-suite-trial.crt

**NOTE:** Rename these files to `nginx-repo.key` and `nginx-repo.crt`.

### NGINX Instance

NMS needs an NGINX instance—either NGINX OSS or NGINX Plus. This role connects to the [NGINX Ansible Role](https://github.com/nginxinc/ansible-role-nginx) named **nginxinc.nginx**. You can set related variables when using this role; for example, `nginx_type` is a variable you can define in your playbook. If you set `nginx_type: plus`, this NMS role will use the **nginxinc.nginx** role to install NGINX Plus. Check the [Ansible Role NGINX](https://github.com/nginxinc/ansible-role-nginx) for more information.

The difference in using NGINX OSS or NGINX Plus is based on the [Authentication Option](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/configure-authentication/#auth-options) you want.

### Ansible

* This role works with maintained versions of Ansible core (above `2.12`).
* It was developed and tested with **nginxinc.nginx** version **0.24.0**.
   * UPDATE 6/24/24: Use the edge *nginxinc.nginx* version. See `requirements.yml` [here](https://github.com/nginxinc/ansible-role-nginx-management-suite/blob/8feff2413ca3b5281a4002dcd6518e38effcf7e4/.github/workflows/requirements/requirements_ansible.yml#L3-L6).
* You need to install the following collections:
   * ansible.posix
   * community.general
   * community.crypto
   * community.docker (only if using Molecule)

* Run this role as a root user, ensuring you have the right permissions set on your target hosts.
* For instructions on how to install Ansible, visit the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#upgrading-ansible-from-version-2-9-and-older-to-version-2-10-or-later).

### Jinja2

* This role uses Jinja2 templates. Ansible includes Jinja2 by default, but ensure you have version `3.1` or higher.
* Instructions for installing Jinja2 can be found on the [Jinja2 website](https://jinja.palletsprojects.com/en/2.11.x/intro/#installation).

### Molecule (Optional)

Use Molecule if you are contributing to this role.

* Molecule tests the role functions. The recommended version for this role is `4.0.1`.
* Instructions for installation can be found on the [Molecule website](https://molecule.readthedocs.io/en/latest/installation.html). *You also need to install the Molecule Docker driver.*
* To run tests, copy your NMS license to the role's [`files/license`](https://github.com/nginxinc/ansible-role-nginx-management-suite/blob/main/files/license/) folder.

Alternatively, add your NGINX Management Suite repository certificate and key to the local environment. Use these commands:

```bash
export NGINX_CRT=$( cat <path to your certificate file> | base64 )
export NGINX_KEY=$( cat <path to your key file> | base64 )
molecule test -s plus

Usage

Follow these steps to install the NGINX Management Suite (NMS) using this Ansible role.

Create Inventory File

Create an inventory file named inventory with the following content:

[nms]
<hostname> ansible_user=<adminUserName> ansible_become=yes

Install Required Roles and Collections

Create a requirements.yml file with the following content:

---
roles:
  - name: nginxinc.nginx_management_suite
    version: 0.3.0
collections:
  - name: ansible.posix
    version: 1.5.1
  - name: community.general
    version: 6.4.0
  - name: community.crypto
    version: 2.11.0
  - name: community.docker # Only required if using Molecule
    version: 3.4.2

Run the command to install the roles and collections:

ansible-galaxy install -r requirements.yml

To update existing installations, use:

ansible-galaxy install -fr requirements.yml

Move NGINX Certificates

Move the NGINX certificates to the directory where you'll create the NMS install playbook.

Create Playbook

Create a playbook file named nms-install.yml with the following example for installing NMS with NGINX Plus. Adjust the paths to your NGINX certificates accordingly.

- name: Install NGINX Management Suite
  hosts: nms

  tasks:
    - name: Install NMS
      ansible.builtin.include_role:
        name: nginxinc.nginx_management_suite
      vars:
        nms_setup: install
        nms_user_name: admin
        nms_user_passwd: default
        nginx_type: plus
        nginx_selinux: true
        nginx_selinux_enforcing: false
        nginx_license:
          certificate: nginx-repo.crt
          key: nginx-repo.key

Install NMS

Run this command to execute the playbook and install NMS:

ansible-playbook -i inventory nms-install.yml

Using the Latest Edge of NMS Ansible Role (the main Branch)

You have two options to use the latest version from this role:

1. Add the following to your requirement.yml:

   roles:
     - src: https://github.com/nginxinc/ansible-role-nginx-management-suite.git
       version: main
   

2. Clone the role repository using git clone https://github.com/nginxinc/ansible-role-nginx-management-suite.git to get the latest version.

Platforms

This Ansible role works on platforms supported by NGINX Management Suite:

Supported Platforms

Amazon Linux 2:
  - any
CentOS:
  - 7.4+
Debian:
  - buster (10)
  - bullseye (11)
Oracle Linux:
  - 7.4+
  - 8
Red Hat:
  - 7.4+
  - 8
  - 9
Ubuntu:
  - bionic (18.04)
  - focal (20.04)
  - jammy (22.04)

Note: You may use this role on unsupported platforms at your own risk.

Role Variables

This role has multiple variables. Find descriptions and defaults in the defaults/main/ folder:

Also, find preset variable descriptions in the vars/ folder:

Example Playbooks

You can find functional examples in the molecule/ folder:

If you install via Ansible Galaxy, remember to replace the role variable in the sample playbooks from ansible-role-nginx-management-suite to nginxinc.nginx_management_suite.

Other NGINX Ansible Collections and Roles

You can find other NGINX Ansible collections for installing and configuring NGINX Open Source, NGINX Plus, and NGINX App Protect here.

The role for configuring NGINX can be found here.

To install NGINX Unit, visit here.

License

Apache License, Version 2.0

Author Information

John Wong

Alessandro Fael Garcia

© F5, Inc. 2023 ```