mirror of
https://gitlab.archlinux.org/archlinux/infrastructure.git
synced 2024-05-05 21:06:02 +02:00
58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# About the maintenance role
|
|
|
|
The maintenance role is a generic role that contains a maintenance nginx configuration
|
|
and a html file that is used for the 503 return.
|
|
|
|
It can be plugged into any role that has a web service that uses nginx. Also, if the role
|
|
has any alternate domains, they can also be passed to the maintenance mode and all of them
|
|
will be redirecting to the main domain in maintenance mode.
|
|
|
|
This mode works only while there is a `maintenance` variable defined. To prevent accidents,
|
|
the variable must be explicitly defined on the command line when running a playbook with the
|
|
-e command flag.
|
|
|
|
# Adding the maintenance role to another role
|
|
|
|
This role plugs into another role in two points. The first being the actual role configuration
|
|
using ansible's include_role module. The second point is where the role receiving the maintenance
|
|
mode configures nginx. There are a few examples of roles that can be used, like archweb and archwiki.
|
|
|
|
The basic configuration looks like this:
|
|
|
|
```
|
|
- name: run maintenance mode
|
|
include_role:
|
|
name: maintenance
|
|
vars:
|
|
service_name: "<service name>"
|
|
service_domain: "{{ service_domain }}"
|
|
service_alternate_domains: []
|
|
service_nginx_conf: "{{ service_nginx_conf }}"
|
|
when: maintenance is defined
|
|
```
|
|
|
|
This is best placed at the top of the tasks main file for the role, to make sure it is ran first.
|
|
Replace <service_name> with the name of the web service. The nginx configuration is best to be set
|
|
as a variable, to make sure the right file is used.
|
|
|
|
```
|
|
- name: set up nginx
|
|
template: src=nginx.d.conf.j2 dest="{{ service_nginx_conf }}" owner=root group=root mode=644
|
|
notify:
|
|
- Reload nginx
|
|
when: maintenance is not defined
|
|
tags: ['nginx']
|
|
```
|
|
|
|
This causes the regular nginx configuration to only be applied when there is no maintenance variable
|
|
on the command line.
|
|
|
|
# Adding a custom maintenance mode nginx template
|
|
|
|
The maintenance role can also use a custom nginx template, if the service_nginx_template variable is
|
|
set alongside the other vars when including the maintenance role, it will look up first on the maintenance
|
|
role template directory and then on the calling role template directory for the specified template.
|
|
|
|
Since this is a completely custom file, it is the job of this file of putting the service into maintenance
|
|
mode. The maintenance role will provide the 503 file and create the directories.
|