Skip to content

Latest commit

 

History

History
58 lines (45 loc) · 2.38 KB

maintenance.md

File metadata and controls

58 lines (45 loc) · 2.38 KB
Raw

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_legacy_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.