Skip to content
Snippets Groups Projects
Commit bf23639b authored by jurgenhaas's avatar jurgenhaas
Browse files

docker/l3d#74 Move all documentation to devops-tools doc

parent 6e6cb1a6
Branches
No related tags found
No related merge requests found
Pipeline #33418 passed
Stage: build
Hide whitespace changes
Inline Side-by-side
Showing
with 4 additions and 256 deletions
README.md
+ 4
− 256
View file @ bf23639b
# Ansible Repository by PARAGON # Ansible Repository
This repository is a collection of playbooks, roles, plugins and inventories for You find all the details in the [full documentation](https://devops-tools.docs.lakedrops.com/ansible/).
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.
## Installation ## Quick Start
Before you can checkout the repositories from the server, you have to add your TBD
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)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment