Here are instructions of installing the Ansible lab, see below for the different systems you provision for the lab.
For the lab to work, you need to provision 1 Ansible Tower server and 3 Managed systems per student in the lab. All users share the same GitLab server. The current GitLab server should scale to up to atleast 400 concurrent students.
These instructions guide you how to let Ansible provision the environment to Amazon AWS. All installation material is in content/ -directory, instructions assume you are working in that directory. Start with cloning this repository, moving into working directory, and adding your ssh key to ssh-agent for Ansible to use it:
git clone https://github.com/mglantz/ansible-roadshow.git
cd content
ssh-add /path/to/your/amazon-ssh-key-file.pem
Export the AWS credentials (without this, the ec2.py inventory will bail out).
export AWS_ACCESS_KEY_ID=asdfasdfasdfasdfasdf
export AWS_SECRET_ACCESS_KEY='the-keyasdfasdfasdfasdf'
To enable the Ansible Tower instances, you need to fetch a subscription from https://www.ansible.com/workshop-license. If you want you can do this in advance for the students, or just have them follow the instructions which are a part of the lab, which has them fetch a subscription (it get's e-mailed automatically within a minute or two from registering).
This setup was tested at the time of writing this README with Ansible version 2.6. To install Ansible follow Ansible install guidance for your favourite OS, Linux :) .
Before running the installer, you need to install boto Python modules on your Ansible machine using the Ansible AWS documentation.
Install the boto library using python pip, as follows:
sudo pip install boto
sudo pip install boto3
Before running the installer, you need to install boto Python modules on your Ansible machine using the Ansible AWS documentation. Before running the installer, you need to install boto Python modules on your Ansible machine using the Ansible AWS documentation.
- When running the installer, a task regarding the GitLab server may fail as shown below, just wait a minute and then re-run the playbook if that is the case.
PLAY [setup stuff in Gitlab VMs] ***************************************************************************************
TASK [Gathering Facts] *************************************************************************************************
The authenticity of host '18.184.66.48 (18.184.66.48)' can't be established.
ECDSA key fingerprint is SHA256:xdDsD7vJe9GFVbxhXe7/xgwpkyQecmL1NJ0F7bR8Zmo.
Are you sure you want to continue connecting (yes/no)? yes
fatal: [18.184.66.48]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh: Warning: Permanently added '18.184.66.48' (ECDSA) to the list of known hosts.\r\nConnection reset by 18.184.66.48 port 22\r\n", "unreachable": true}
to retry, use: --limit @/path/to/ansible-roadshow/content/provision-all.retry
- When doing repeated setups of brand new environments, gitlab server install fails due to gitlab_server.out contains old values. Solve problem by removing old entries.
Playbook fails as such:
TASK [Create project] **************************************************************************************************
fatal: [localhost]: FAILED! => {"changed": false, "msg": "Invalid header value 'ec2-52-57-173-62.eu-central-1.compute.amazonaws.com\\nhttps:'"}
to retry, use: --limit @/path/to/ansible-roadshow/content/gitlab-setup.retry
PLAY RECAP *************************************************************************************************************
localhost : ok=2 changed=0 unreachable=0 failed=1
Playbooks expect file content/vars/vars.yml to contain settings your personal AWS credentials, machine AMI image and some other parameters. Copy content/vars/vars-example.yml and fill it with your settings. It is recommended to use Ansible Vault to encrypt your credentials.
Put password of your choice into a text file. In this example content/vault-password.txt. Then you can use command ansible-vault --vault-password-file content/vault-password.txt encrypt_string to encrypt your credentials. The output can be used in the content/vars/vars.yml file, see example in ```content/vars/vars-example.yml -file.
You can also put the credentials in plain text, but you should make sure that you don't commit them into any git repository! Files content/vars/vars.yml and content/vault-password.txt are ignored by git in this repository for your safety.
There are some dependencies for external roles in this setup. You can use Ansible Galaxy to install them:
ansible-galaxy install -p roles -r roles/requirements.yml
As of now, 2002-08-24, the gitlab role is a bit broken, fix it by changing the file roles/gitlab/tasks/main.yml as follows.
- Below the
Install GitLab repository.task, add the following two tasks:
- name: Fix repo_gpgcheck in repository file
lineinfile:
path: /etc/yum.repos.d/gitlab_gitlab-ce.repo
regexp: '^repo_gpgcheck='
line: repo_gpgcheck=0
- name: Fix gpgcheck in repository file
lineinfile:
path: /etc/yum.repos.d/gitlab_gitlab-ce.repo
regexp: '^gpgcheck='
line: gpgcheck=0
- In the
Install GitLabtask, changeasync: 300``` toasync: 900, so the task reads as follows.
- name: Install GitLab
package:
name: "{{ gitlab_package_name | default(gitlab_edition) }}"
state: present
async: 900
poll: 5
when: not gitlab_file.stat.exists
Playbook provision-all.yml includes other playbooks to create all necessary resources into AWS, and configure each of them. It will use dynamic inventory provided by content/inventory/ec2.py. That's why you need boto Python modules installed in addition to AWS credentials in content/vars/vars.yml.
ansible-playbook --vault-password-file vault-password.txt -i inventory/ec2.py provision-all.yml
💥 If you don't use Ansible Vault, ignore vault-password-file parameter
Once the environment has been provisioned and if you don't feel like using GitHub, you can use Gitlab that was installed with the lab environment. Due to limitations in the Gitlab API, you have to create access key for the root user, that was created during the installation by hand. This has to be done in order to get the ansible-roadshow -project and student users set up to Gitlab.
Gitlab's default administrator account details are below; be sure to login immediately after installation and change these credentials!
root
5iveL!fe
Gitlab will automatically prompt you to change the password.
Password should be set to redhat123, or if you end up choosing something different you will have to modify gitlab-setup.yml to comply with your password.
Once you are logged in, it's time to create the access token for the Administrator user(root).
From the top-right corner click on the avatar and choose settings:
At the settings -page go to menu called "Access Tokens" that is at the left side of the screen:
From that menu you can create Access Token(s) to access the API. You can name the Access Token how ever you like, but make sure to tick all the boxes under the Scope -section:
Once you click on the "Create personal access token" -button, Access Token will be generated for you, be sure to copy it to your clipboard:
Next, we're going to turn off the automatic pipeline feature in GitLab, as it makes a bit of a mess for students. Click on the "admin area tool wrench", select "Settings" and then "CI/CD". When you are there, de-select "Default to Auto DevOps pipeline for all projects" and "Enable shared runner for new projects" as shown below and click the "Save settings" button at the bottom.
Once you have the access token on your clipboard, copy it to gitlab_token -variable in vars.yml -file and run the gitlab-setup.yml -playbook:
ansible-playbook gitlab-setup.yml
This will copy the content of the workshop from GitHub to your Gitlab server and create as many user accounts as you have Ansible tower systems.
Users will be named student1 to studentX and password for the student accounts will be redhat123.
The installation of Ansible Tower is completely automatic. If you need to know how the automatic installation happens, read up on: https://github.com/mglantz/ansible-roadshow/blob/master/content/scripts/tower-prep.sh
The tower-prep.sh script dumps an inventory (tower-inventory) and a playbook (tower-install.yml) /root. The tower-install.yml playbook is what installs Tower.
The reason for this is because fetching the script from GitHub is unreliable when doing large lab environments. Also, it hard codes against this repository, which makes testing branches a nightmare.
After tower-prep.sh has dropped the playbook and the inventory, the installation is then run at the end of tower-prep.sh like so:
ansible-playbook -i /root/tower-inventory /root/tower-install.yml
Because of security reasons when provisoning the environment in advance, or to ensure that all students starts the labs at the same time, you may want to turn off all access to the environment after having provisioned it. Deny all incoming traffic to the environment by running below playbook:
ansible-playbook -i inventory/ec2.py turn_off_access.yml
If you have turned off all access to the environment by running the turn_off_access.yml playbook, turn access back to normal by running:
ansible-playbook -i inventory/ec2.py turn_on_access.yml
Beware this might leave something out, do check yourself from your AWS account
There is a helper playbook, which deletes all resources created for this lab from AWS. But you never know if someone adds something to labs, and forgets to also add it into delete_instances.yml playbook. If you develop this further, do always remember to include your added resources into delete_instances.yml.
After labs are done, stop billing by running:
ansible-playbook --vault-password-file vault-password.txt -i inventory/ec2.py delete_instances.yml
if you don't use vault, ignore vault-password-file parameter
Ansible Tower server and managed systems should be up in 10 minutes. Ansible Tower itself will be up in aproximately 30 minutes and the GitLab server will be available in about 15 minutes. Happy learning!
At the time of writing, not all playbooks are included in do_all.yml. Remove this line once the issue is taken care of.