Code development platform for open source projects from the European Union institutions :large_blue_circle: EU Login authentication by SMS has been phased out. To see alternatives please check here

Skip to content
Snippets Groups Projects
Commit fed39c04 authored by David Delassus's avatar David Delassus
Browse files

:bookmark: v0.5.0

parent b83ac1ce
No related branches found
No related tags found
No related merge requests found
Pipeline #154768 passed
Showing
with 651 additions and 0 deletions
profile: null
use_default_rules: true
enable_list:
- command-instead-of-module
- command-instead-of-shell
- deprecated-bare-vars
- deprecated-local-action
- deprecated-module
- empty-string-compare
- ignore-errors
- inline-env-var
- internal-error
- jinja[spacing]
- jinja[invalid]
- key-order
- latest[git]
- literal-compare
- package-latest
- partial-become
- no-changed-when
- no-free-form
- no-handler
- no-jinja-when
- no-log-password
- no-relative-path
- no-same-owner
- playbook-extension
- risky-file-permissions
- risky-octal
- risky-shell-pipe
- role-name
- syntax-check
skip_list:
- latest[git]
- var-naming[no-role-prefix]
docs/build/
lint:
script:
- ansible-lint -c ./.ansible-lint.yml ./roles/
tags:
- lab
- shell
pages:
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- pip install sphinx
- (cd docs && sphinx-build -M html source build)
- mv docs/build/html public
artifacts:
paths:
- public
tags:
- lab
- shell
# Git workflow
Commit messages **MUST** follow the [Gitmoji](https://gitmoji.dev) convention.
New changes **MUST** be done in a separated branch with a dedicated Merge Request.
# Merge Requests
Merge Requests **MUST** be reviewed before being merged.
Merge requests **SHOULD** rebase their branch on `devel` before merging to avoid merge conflicts.
# Versionning
New versions **MUST** be created via a git tag of the following format: `v$MAJOR.$MINOR.$PATCH`.
Version numbers **MUST** follow Semantic Versionning.
# Architecture Decision Records
Merge Requests act as ADR.
An ADR is a record of "why" things are done in a certain way. This is important
for onboarding new people on the project as they can just go through the
history of ADR to understand the project.
# Ansible Collection - ec.rps_nginx
## Installation
Add to your `requirements.yml`:
```yaml
collections:
- name: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection.git
type: git
version: v0.5.0
```
## Documentation
For more information:
- the [CONTRIBUTING](./CONTRIBUTING.md) document describes how to contribute to the repository
- consult the [documentation](https://digit-c4.pages.code.europa.eu/rps/nginx-ansible-collection)
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'Ansible Collection - ec.rps_nginx'
copyright = '2024, DIGIT NMS RPS'
author = 'DIGIT NMS RPS'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = []
templates_path = ['_templates']
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'nature'
html_theme_options = {
'body_min_width': 'calc(100% - 230px)',
}
html_static_path = ['_static']
Ansible Collection ec.rps_nginx
===============================
.. image:: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection/badges/main/pipeline.svg?style=flat-square
:target: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection/-/commits/main
:alt: Pipeline Status
.. image:: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection/-/badges/release.svg?style=flat-square
:target: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection/-/releases
:alt: Latest Release
Installation
------------
Add to your ``requirements.yml``:
.. code-block:: yaml
collections:
- name: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection.git
type: git
version: v0.5.0
Content
-------
Included Roles
~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
roles/check_service_catalog
roles/provision_netbox_docker
roles/provision_netbox_mappings
roles/probe_healthchecks
roles/probe_testurls
Legacy Roles
~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
legacy/compliance
legacy/deploy_nginx_plus
legacy/deploy_nginx_waf_modsec
legacy/apply_policies
legacy/sid2netbox_migration
See also
--------
* `Docker image for RPS <https://digit-c4.pages.code.europa.eu/sec/rps-nginx-instance/>`_
* `Ansible playbooks for RPS <https://digit-c4.pages.code.europa.eu/rps/nginx-ansible-playbooks>`_
* `AWX job provisionning <https://digit-c4.pages.code.europa.eu/awx-data/>`_
Apply Policies
==============
This role configures the NGINX+ RPS on a Debian 11 virtual machine, to serve
mappings configured in the CMDB.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: all:!localhost
gather_facts: true
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
roles:
- ec.rps_nginx.legacy_apply_policies
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
workspace_name, "Name of the workspace (on the runner)", "``default``"
gixy_bin, "Absolute path to the ``gixy`` binary", "``/usr/bin/gixy``"
sid_enabled, "If ``true``, mappings are fetched from SID", "``false``"
sid_env, "Name of the Intragate environment (leave empty for production)", "N/A"
sid_uid, "Unique identifier of the environment in SID to fetch mappings from", "N/A"
sid_custom_nginx_config, "If enabled, add support of custom NGINX+ configuration in SID", "``true``"
acme_enabled, "If ``true``, will enable the ACME certificate generation", "``false``"
cert_name, "Name of the wildcard certificate to use when ACME is disabled", "``star-tech``"
saml_enabled, "If ``true``, will enable the SAML authentication", "``false``"
modsec_enabled, "If ``true``, will enable the ModSecurity WAF", "``true``"
rps_mappings, "If SID is disabled, mappings (as fetched from Netbox) to apply", "``[]``"
Virtual machine compliance
==========================
This role ensures that the virtual machine does not have conflicting package or
configuration set up.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: all:!localhost
gather_facts: true
roles:
- ec.rps_nginx.legacy_compliance
Inventory
---------
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
modsec_enabled, "Disable suppression of the ModSecurity WAF if enabled", "``true``"
appprotect_enabled, "Disable suppression of the AppProtect WAF if enabled", "``false``"
Deploy NGINX+
=============
This role installs the NGINX+ service on a Debian 11 virtual machine.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: all:!localhost
gather_facts: true
roles:
- ec.rps_nginx.legacy_deploy_nginx_plus
**NB:** This role requires an Ansible Vault key.
Inventory
---------
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
workspace_name, "Name of the workspace (on the runner)", "``default``"
proxy_enabled, "If ``true``, will set the HTTP(S) proxy to the value of the runner's environment variable ``PROXY_EC_URL``", "``true``"
acme_enabled, "If ``true``, will enable the ACME certificate generation", "``false``"
cert_name, "Name of the wildcard certificate to use when ACME is disabled", "``star-tech``"
dns_resolvers, "List of DNS resolvers to use in NGINX+ configuration", "``[]``"
syslog_tag, "Prefix for NGINX+ logs when redirected to Syslog", "``nginxrps``"
Deploy NGINX+ WAF ModSecurity
=============================
This role installs the Web Application Firewall ModSecurity on a Debian 11
virtual machines.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: all:!localhost
gather_facts: true
roles:
- ec.rps_nginx.legacy_deploy_nginx_waf_modsec
Inventory
---------
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 80, 20
workspace_name, "Name of the workspace (on the runner)", "``default``"
proxy_enabled, "If ``true``, will set the HTTP(S) proxy to the value of the runner's environment variable ``PROXY_EC_URL``", "``true``"
modsec_rules_input_filename, "Name of the file listing the ModSecurity rules to install from the `C4 repository <https://code.europa.eu/digit-c4/modsec-rules.git>`_", "``2.yml``"
SID to Netbox Migration
=======================
This role fetches mappings from SID and synchronize them in Netbox.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
gather_facts: false
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
env_name: 'my-env-name'
sid_uid: '12345678'
roles:
- ec.rps_nginx.legacy_sid2netbox_migration
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
workspace_name, "Name of the workspace (on the runner)", "``default``"
sid_env, "Name of the Intragate environment (leave empty for production)", "N/A"
sid_uid, "Unique identifier of the environment in SID to fetch mappings from", "N/A"
env_name, "Name of the environment in Netbox to synchronize (the slug of the tag on the mappings and virtual machines)", "N/A"
Check Service Catalog
=====================
This role verifies that the required services are present in the Netbox.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
netbox_dns_service_name: bind
netbox_syslog_service_name: syslog
roles:
- ec.rps_nginx.check_service_catalog
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
"netbox_dns_service_name", "Name of the DNS service in Netbox", "``bind``"
"netbox_syslog_service_name", "Name of the Syslog service in Netbox", "``syslog``"
Probe healthchecks
==================
This role is used to probe the healthchecks of every virtual host present in the
RPS (2 mappings can be served by the same virtual host). 2 checks are performed:
* A backend test: the test is performed on each instance of the RPS, using the ``Host`` header for routing
* An End-To-End test: the test is performed using the source domain of the mapping (possibly going through a load balancer or a VIP)
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
env_name: 'my-env-name'
roles:
- ec.rps_nginx.probe_healthchecks
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
"env_name", "Name of the environment to check (the slug of the tag on the mappings and virtual machines)", "N/A"
"rps_service_name", "Name of service in Netbox associated to the virtual machines", "``nginx``"
Probe Testing URLs
==================
This role will check the testing URLs of each mapping.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
env_name: 'my-env-name'
roles:
- ec.rps_nginx.probe_testurls
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
"env_name", "Name of the environment to check (the slug of the tag on the mappings and virtual machines)", "N/A"
Provision Netbox Docker
=======================
This role will setup the RPS docker image in Netbox.
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
roles:
- ec.rps_nginx.provision_netbox_docker
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
"rps_service_name", "Name of service in Netbox associated to the virtual machines", "``nginx``"
"rps_docker_registry", "Name of the Docker registry in Netbox", "``code.europa.eu``"
"rps_docker_image_name", "Name of the Docker image to pull", "``code.europa.eu:5679/digit-c4/sec/rps-nginx-instance``"
"rps_version", "Version of the Docker image to pull", "``v0.30.0``"
"rps_agent_allowed_origins", "IP ranges allowed to access the RPS agent API", "``[*]``"
Provision Netbox Mappings
=========================
This role creates DNS records, mappings and certificates in Netbox in bulk from
a template.
The template is a **Config Template** in Netbox with the following name:
* ``{{ env_name }}/mappings``
Usage
-----
.. code-block:: yaml
---
- name: My Playbook
hosts: localhost
connection: local
vars:
netbox_api: "{{ lookup('env', 'NETBOX_API') }}"
netbox_token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
env_name: lab
roles:
- ec.rps_nginx.provision_netbox_mappings
Inventory
---------
Netbox-related Inventory
~~~~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 70, 10
"netbox_api", "URL to Netbox", "N/A"
"netbox_token", "Authentication token to Netbox API", "N/A"
RPS-related Inventory
~~~~~~~~~~~~~~~~~~~~~
.. csv-table::
:header: "Key", "Description", "Default Value"
:widths: 20, 60, 40
"env_name", "Name of the environment to create the mappings in (the slug of the tag on the mappings and virtual machines)", "N/A"
"certificate_authority", "Certificate Authority to use for certificates", "``letsencrypt``"
namespace: ec
name: rps_nginx
version: "0.5.0"
readme: README.md
authors:
- DIGIT NMS RPS
description: RPS related roles and plugins
license:
- GPL-2.0-or-later
license_file: ''
tags: []
# Collections that this collection requires to be installed for it to be usable. The key of the dict is the
# collection label 'namespace.name'. The value is a version range
# L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version
# range specifiers can be set and are separated by ','
dependencies:
community.general: ">=7.4.0"
community.crypto: ">=2.10.0"
netbox.netbox: ">=3.13.0"
repository: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection
documentation: https://digit-c4.pages.code.europa.eu/rps/nginx-ansible-collection/
homepage: https://digit-c4.pages.code.europa.eu/rps/nginx-ansible-collection/
issues: https://code.europa.eu/digit-c4/rps/nginx-ansible-collection/-/issues
build_ignore: []
---
requires_ansible: '>=2.9.10'
---
netbox_api: ""
netbox_token: ""
netbox_dns_service_name: bind
netbox_syslog_service_name: syslog
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment