diff --git a/README.md b/README.md index e552ff567ddad8c7f25991c0880df8236531e197..51bf5840fd793213aed79f33bb699f36d2e37039 100644 --- a/README.md +++ b/README.md @@ -1,259 +1,7 @@ -# Ansible Repository by PARAGON +# Ansible Repository -This repository is a collection of playbooks, roles, plugins and inventories for -multiple clients that PARAGON supports. It is build such that multiple clients -could be installed on a single control host. However, by default the setup -script installs the framework for an individual custumer so that those can use -it for themselves too. +You find all the details in the [full documentation](https://devops-tools.docs.lakedrops.com/ansible/). -## Installation +## Quick Start -Before you can checkout the repositories from the server, you have to add your -public SSH key to your user profile on the GitLab server. To do so, please go -to https://gitlab.lakedrops.com/profile/keys and follow the instructions there. -Please also note the link to instructions on how to [generate it](https://gitlab.lakedrops.com/help/ssh/README) -which also describes on how to prepare your local host to securly access the -GitLab repositories. - -Once that's been completed, proceed with these steps: - -``` -# Install Ansible: http://docs.ansible.com/ansible/intro_installation.html -# There you can find the relevant instructions for your local environment. -# The following example is for Ubuntu (for others refer to the link above): -sudo apt-get install software-properties-common python2.7 git -sudo apt-add-repository ppa:ansible/ansible -sudo apt-get update -sudo apt-get install ansible - -# Patch Ansible, if required -# For this, see the next chapter with advise on which patch is required for which Ansible version. - -# Create your Ansible home directory (e.g. /opt/ansible) -mkdir /opt/ansible - -# Checkout the main repository -git clone git@gitlab.lakedrops.com:ansible-playbooks/general.git /opt/ansible --recurse-submodules -cd /opt/ansible - -# Optionally install other OS requirements, only if it fails in subsequent ansible-script.py setup-local task -# Then you should also use the parameter --skip-os-tasks in the next step -# How to find out the requirements: please look into the playbooks/setup/ directory and look -# into the right file for your OS to see which components need to be installed - -# Setup or update -./ansible-script.py setup-local COMPANY [--username=REMOTEUSERNAME] [--skip-os-tasks] -``` - -## Patching - -From time to time there might be problems with an Ansible core update and if there -is no other way, i.e. modifying our Ansible playbooks and roles, then we may have -to patch Ansible core and here is a list of availables patches and the information -which of them needs to be applied to which Ansible version: - -| Patch File | Ansible Versions | Comments | -| :------------------ | :--------------- | :---------------------------------------------------------- | -| none | | | - -You can find the patches in the `files/patches` sub-directory of this repository -and the Ansible core directory, that needs to be patched, depends on the operating -system and might be something like `/usr/share/pyshared/ansible/` - -So, you may have to execute these steps: - -``` -cd /usr/lib/python2.7/dist-packages/ansible -patch -p1 < /opt/ansible/files/patches/FILENAME.patch -``` - -Again, the directories depend on your local installation. - -## Configuration - -The above installation configures Ansible such that everything is good to go -and you can call the `ansible-script.py setup-local` script again at any time to grab updates -or restore settings if something got broken. - -When using `ansible-script.py setup-local` the first time there will be two new files being created -that you can use again in the future as shortcuts: - -- **/opt/ansible/update.sh** which will update your installation by pulling - all changed repositories and also running configuration of the current user -- **/opt/ansible/config.sh** which will just update the configuration for the - current user - -Important: if your remote username is different from your local username, you -should call those scripts (`ansible-script.py setup-local`, `update.sh`, `config.sh`) with an -additional parameter `--username=[REMOTE USER NAME]`. This will write that -username into the `~/.ansible.cfg` for future usage so as long as that name -remains the same, you no longer have to use that parameter again. - -Additional settings make the usage of Ansible more convenient and we're describing -them here with detailed descriptions. - -### Ansible configuration - -You'll find a file ```.ansible.cfg``` in your home directory after the setup from -above and there are certain additional settings that could be usefull: - -#### Working with a vault for automatic sudo password input - -When using Ansible with this repository you'll get asked for your remote sudo -password every single time. If you want to avoid that, you can store that password -in a vault so that Ansible grabs it from there automatically. - -**Warning:** Only use that if you have full control over the Ansible control host -because otherwise someone else could get access to your whole server farm. - -1. Create your vault password file - Create a file named ```~/.ansible/vault.pwd``` and edit that file so that it - contains your local password for your Ansible vault. -2. Configure your vault password file - To make sure Ansible is going to utilize your password file, insert the line - ```vault_password_file = ~/.ansible/vault.pwd``` into ```.ansible.cfg``` in - your home directory. -3. Create your vault - Use the command ```ansible-vault create ~/.ansible/secrets``` and include - one line ```ansible_sudo_pass: YOURSUDOPASS```. This is using your default - editor for the console but you can configure that like ```export $EDITOR=nano``` - to use the nano editor as an example. When saving the file, ansible-vault - will encrypt that file with your vault password contained in the vault.pwd file. -4. (Optional) Edit your vault file later on - If you later want to edit your secrets, use ```ansible-vault edit ~/.ansible/secrets``` - -### AWS EC2: Boto configuration - -If you want to use the dynamic AWS EC2 inventory, you should provide your access -keys in a file ```/etc/boto.cfg``` with the following content: - -``` -[Credentials] -aws_access_key_id = <access key> -aws_secret_access_key = <secret key> -``` - -Note: The access key and secret key should be provided without the < brackets >. - -In a multi-company environment the configuration file should provide different -sections for each company that has hosts in AWS EC2: - -``` -[profile COMPANY1] -aws_access_key_id = <access key> -aws_secret_access_key = <secret key> - -[profile COMPANY2] -aws_access_key_id = <access key> -aws_secret_access_key = <secret key> -``` - -Here you should replace `COMPANY#` with the lower case name of the relevant company. - -### JiffyBox configuration - -If you are using a JiffyBox inventory, you have to provide your API token in a -file ```/etc/jiffybox.cfg``` with the following content: - -``` -[Credentials] -api_token = <api token> -``` - -Note: The api token should be provided without the < brackets >. - -In a multi-company environment the configuration file should provide different -sections for each company that has hosts in JiffyBox: - -``` -[profile COMPANY1] -api_token = <api token> - -[profile COMPANY2] -api_token = <api token> -``` - -Here you should replace `COMPANY#` with the lower case name of the relevant company. - -### Linode configuration - -If you are using a Linode inventory, you have to provide your API key in a -file ```/etc/linode.cfg``` with the following content: - -``` -[Credentials] -api_key = <api key> -``` - -Note: The api key should be provided without the < brackets >. - -In a multi-company environment the configuration file should provide different -sections for each company that has hosts in Linode: - -``` -[profile COMPANY1] -api_key = <api key> - -[profile COMPANY2] -api_key = <api key> -``` - -Here you should replace `COMPANY#` with the lower case name of the relevant company. - -### Creating shortcuts for the scripts - -All the scripts in this repository are written in a way that they can be called -from everywhere, you don't have to chdir into the repository directory first. - -For better convenience, we recommend to create shortcuts in a directory which is -part of your PATH environment variable. Examples: - -``` -cd /usr/local/bin -sudo ln -s /opt/ansible/directory/ansible.py a -sudo ln -s /opt/ansible/directory/ansible-playbook.py apb -sudo ln -s /opt/ansible/directory/ansible-script.py ascr -``` - -Since version 1.2, the setup script is creating those links by default for you. - -### Preparing access to existing hosts - -Ansible knows the hosts by name and the company specific naming convention should -be reflected on each local host that wants to use Ansible to manage them. You'll -find the hostnames in the file called ```inventory``` (if you have a static -inventory) or for dynamic inventories this is an executibale file that you can -call and it will list the known hosts to your console. - -You should make sure that your local host knows all your remote hosts by name -and their IP address. For this, add a new line for each of those hosts into your -```/etc/hosts``` file starting with the IP address followed by a space and the -hostname from the inventory file. - -You can also run ```ansible-script.py hosts``` and Ansible will update your -local hosts file automatically. - -Next, and this is the final piece before you can start using Ansible to access -your hosts, make sure that you can access your hosts via SSH. This repository -is built with security at the forefront and therefore access is only available -through a PKI infrastructure. To configure your system for easy access, you -should have a file ```$HOME/.ssh/config``` with some content similar to the -following: - -``` -StrictHostKeyChecking yes -ForwardAgent no - -Host * - User [YOUR REMOTE USERNAME] - IdentityFile ~/.ssh/id_rsa -``` - -The above setting applies to all hosts and the definition of the remote user name -is only neccessary if that remote username is different from your local one. Please -note that you should define the same username also in ```$HOME/.ansible.cfg``` - -## Where to go next? - -The best place to continue reading is by heading over to the -[Wiki](https://gitlab.lakedrops.com/ansible-playbooks/general/wikis/home) +TBD