Verified Commit 9eb3c347 authored by Giancarlo Razzolini's avatar Giancarlo Razzolini
Browse files Add notes about the maintenance mode, with some examples

docs/maintenance.txt: Add the documentation for the maintenance mode with example on how to plug it into another role.
parent 1f9f8fa7
......@@ -80,6 +80,27 @@ The opendkim DNS data has to be added to DNS manually. The roles verifies that t
The file that has to be added to the zone is `/etc/opendkim/private/$selector.txt`.
### Putting a service in maintenance mode
Most web services with a nginx configuration, can be put into a maintenance mode, by running the playbook with a maintenance variable:
ansible-playbook -e maintenance=true playbooks/<playbook.yml>
This also works with a tag:
ansible-playbook -t <tag> -e maintenance=true playbooks/<playbook.yml>
As long as you pass the maintenance variable to the playbook run, the web service will stay in maintenance mode. As soon as you stop
passing it on the command line and run the playbook again, the regular nginx configuration should resume and the service should accept
requests by the end of the run.
Passing maintenance=false, will also prevent the regular nginx configuration from resuming, but will not put the service into maintence
Keep in mind that passing the maintenance variable to the whole playbook, without any tag, will make all the web services that have the
maintenance mode in them, to be put in maintenance mode. Use tags to affect only the services you want.
Documentation on how to add the maintenance mode to a web service is inside docs/maintenance.txt
### Finding servers requiring security updates
# 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
name: maintenance
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
- 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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment