From 5135c0cc0a47265761e38d713aac06d50af4cddb Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Thu, 3 Jan 2019 16:15:47 +0200 Subject: [PATCH] Add Ansible guide and Ansible version checks After having multiple people report issues with retrieving SSL certificates, we've finally discovered the culprit to be Ansible 2.5.1 (default and latest version on Ubuntu 18.04 LTS). As silly as it is, certain distributions ("LTS" even) are 13 bugfix versions of Ansible behind. From now on, we try to auto-detect buggy Ansible versions and tell the user. We also provide some tips for how to upgrade Ansible or run it from inside a Docker container. My testing shows that Ansible 2.4.0 and 2.4.6 are OK. All other intermediate 2.4.x versions haven't been tested, but we trust they're OK too. From the 2.5.x releases, only 2.5.0 and 2.5.1 seem to be affected. Ansible 2.5.2 corrects the problem with `include_tasks` + `with_items`. --- docs/ansible.md | 60 +++++++++++++++++++ docs/prerequisites.md | 2 +- .../tasks/setup/setup_sanity_check.yml | 17 +++++- 3 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/ansible.md diff --git a/docs/ansible.md b/docs/ansible.md new file mode 100644 index 00000000..60480a60 --- /dev/null +++ b/docs/ansible.md @@ -0,0 +1,60 @@ +# Running this playbook + +This playbook is meant to be run using [Ansible](https://www.ansible.com/). + + +## Supported Ansible versions + +Generally, Ansible 2.4 or later is required. + +If you're on Ansible 2.5.x, then at least Ansible 2.5.2 is required. + + +## Checking your Ansible version + +In most cases, you won't need to worry about the Ansible version. +The playbook will try to detect it and tell you if you're on an unsupported version. + +To manually check which verison of Ansible you're on, run: `ansible --version`. + +If you're on an old version of Ansible, you should upgrade to a newer version. + + +## Upgrading Ansible + +Depending on your distribution, you may be able to upgrade Ansible in a few different ways: + +- by using an additional repository (PPA, etc.), which provides newer Ansible versions + +- by removing the Ansible package (`yum remove ansible` or `apt-get remove ansible`) and installing via [pip](https://pip.pypa.io/en/stable/installing/) (`pip install ansible`). + +If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path. + + +**Note**: Both of the above methods are a bad way to run system software such as Ansible. +If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software. + + +## Using Ansible via Docker + +Alternatively, you can run Ansible itself from a Docker container on your computer. + +Here's a sample command to get you started (run this from the playbook's directory): + +```bash +docker run -it --rm \ +-w /work \ +-v `pwd`:/work \ +-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \ +--entrypoint=/bin/sh \ +qmxme/ansible +``` + +The above command tries to mount an SSH key (`$HOME/.ssh/id_rsa`) into the container (at `/root/.ssh/id_rsa`). +If your SSH key is at a different path (not in `$HOME/.ssh/id_rsa`), adjust that part. +If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`). + +Once you execute the above command, you'll be dropped into a `/work` directory inside a Docker container. +The `/work` directory contains the playbook's code. + +You can execute `ansible-playbook` commands as per normal now. \ No newline at end of file diff --git a/docs/prerequisites.md b/docs/prerequisites.md index 8895db06..13cf89a5 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -4,7 +4,7 @@ - [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`). -- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Version 2.4 or later is required (see `ansible --version`). +- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for version requirements or alternative ways to run Ansible. - properly configured DNS SRV record for `` (details in [Configuring DNS](configuring-dns.md#configuring-dns) below) diff --git a/roles/matrix-server/tasks/setup/setup_sanity_check.yml b/roles/matrix-server/tasks/setup/setup_sanity_check.yml index bb048a20..4d967912 100644 --- a/roles/matrix-server/tasks/setup/setup_sanity_check.yml +++ b/roles/matrix-server/tasks/setup/setup_sanity_check.yml @@ -1,5 +1,20 @@ --- +- set_fact: + matrix_ansible_outdated_fail_msg: "You are running on Ansible {{ ansible_version.string }}, which is not supported. See our guide about Ansible: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/ansible.md" + +- name: Fail if running on Ansible < 2.4 + fail: + msg: "{{ matrix_ansible_outdated_fail_msg }}" + when: "ansible_version.major <= 2 and ansible_version.minor < 4" + +# Ansible 2.5.0 and 2.5.1 are known to have a bug with `include_tasks` + `with_items`. +# The bug has been fixed in Ansible 2.5.2. +- name: Fail if running on Ansible 2.5.x (lower than 2.5.2) + fail: + msg: "{{ matrix_ansible_outdated_fail_msg }}" + when: "ansible_version.major == 2 and ansible_version.minor == 5 and ansible_version.revision < 2" + - name: Fail if Macaroon key is missing fail: msg: "You need to set a secret in the matrix_synapse_macaroon_secret_key variable" @@ -21,4 +36,4 @@ with_items: - "{{ hostname_identity }}" - "{{ hostname_matrix }}" - - "{{ hostname_riot }}" \ No newline at end of file + - "{{ hostname_riot }}"