Skip to content
Snippets Groups Projects
Commit 2241e6b8 authored by Engin Yoeyen's avatar Engin Yoeyen
Browse files

Update README.md

Restructure text and add new section
- Encrypting Passwords and Certificates
- Running the Code
parent 9d7f8f29
No related branches found
No related tags found
No related merge requests found
##Ansible Best Practises
Problem that is being addressed is to complexity of the ansible projects, soon as the project starts grow. Organization of the code in this repository shows how it is possible solve following issues:
* How to manage external roles
* Usage of variables
* Naming
* Staging
* Complexity of plays
#Ansible Best Practises
If infrastructures are to be treated as a code than projects that manage them must be treated as software projects. As your infrastructure code gets bigger and bigger you have more problems to deal with it. Code layout, variable precedence, small hacks here and there. Therefore, organization of your code is very important, and in this repository you can find some of the best practices(in our opinion) to manage yours infrastructure code. Problems that are address are:
* Overall organization
* How to manage external roles
* Usage of variables
* Naming
* Staging
* Complexity of plays
* Encryption of data(e.g. passwords, certificates)
##TL;DR
* Do not keep external roles in your repository, use ansible-galaxy
* Do not use pre_task, task or post_tasks in your play, use roles to reuse the code
* Keep all your variables in one place, if possible
* Do not use variables in your play
* Use variables in the roles instead of hard-coding
* Keep the names consistent between groups, plays, variables, and roles
* Different environments(development,test,production) must be close as possible, if not equal
* Do not put your password or certificates as plain text in your git repo, use ansible-vault for encrypting
* Use tags in your play
##1. Directory Layout
This is the directory layout of this repository with explanation.
##Directory Layout
production.ini # inventory file for production stage
development.ini # inventory file for development stage
test.ini # inventory file for test stage
vpass # ansible-vault password file
# This file shoul not be commited into the repository
# therefore file is in ignored by git
group_vars/
all # variables under this directory belongs all the groups
apt.yml # ansible-apt role variable file for all groups
......@@ -23,6 +39,7 @@ Problem that is being addressed is to complexity of the ansible projects, soon a
nginx.yml # ""
postgresql # here we assign variables to postgresql groups
postgresql.yml # Each file will correspond to a role i.e. postgresql
postgresql-password.yml #Encrypted password file
plays
ansible.cfg # Ansible.cfg file that holds all ansible config
webservers.yml # playbook for webserver tier
......@@ -32,24 +49,12 @@ Problem that is being addressed is to complexity of the ansible projects, soon a
requirements.yml # All the infromation about the roles
external # All the roles that are in git or ansible galaxy
# This directory is in ignored by git and all the roles in the
# requirements.yml will be downloaded into this directory
# requirements.yml file will be downloaded into this directory
internal # All the roles that are not public
##TL;DR
* Do not keep external roles in your repository, use ansible-galaxy
* Do not use pre_task, task or post_tasks in your play, use roles to reuse the code
* Keep all your variables in one place, if possible
* Do not use variables in your play
* Use variables in the roles instead of hardcoding
* Keep the names consistent between groups, plays, variables, and roles
* Different environments(development,test,production) must be close as possible, if not equal
* Use tags in your play
##1. How to Manage Roles
##2. How to Manage Roles
It is a bad habit to keep the copy of roles, that are developed by other developers, in your git repository. Therefore, you can use ansible-galaxy for installing the roles you need, at the location you need, by simply defining them in the requirements.yml:
```
......@@ -66,7 +71,7 @@ ansible-galaxy install -r requirements.yml
```
##2. Keep your plays simple
##3. Keep your plays simple
If you want to take the advantage of the roles, you have to keep your plays simple.
Therefore do not add any tasks in your main play. Your play should only consist of the list of roles that it depends on. Here is an example:
......@@ -85,22 +90,38 @@ Therefore do not add any tasks in your main play. Your play should only consist
As you can see there are also no variables in this play, you can use variables in many different ways in ansible, and to keep it simple and easier to maintain do not use variables in plays. Furthermore, use tags, they give wonderful control over role execution.
##3. Stages
##4. Stages
Most likely you will need different stages(e.g. test, development, production) for the product you are either developing or helping to develop. A good way to manage different stages is to have multiple inventory files. As you can see in this repository, there are three inventory files. Each stage you have must be identical as possible, that also means, you should try to use few as possible host variables. It is best to not use at all.
##4. Variables
##5. Variables
Variables are wonderful, that allows you to use all this existing code by just setting some values. Ansible offers many different ways to use variables. However, soon as your project starts to get bigger, and more you spread variables here and there, more problems you will encounter. Therefore it is good practice to keep all your variables in one place, and this place happen to be group_vars. They are not host dependent, so it will help you to have a better staging environment as well. Furthermore, if you have internal roles that you have developed, keep the variables out of them as well, so you can reuse them easily.
##5. Name consistency
If you want to maintain your code, keep the name consistency between, play and inventories, roles and group variables. Use the name of the roles to separate different variables in each group. If you have a role called nginx keep the variables under your group_vars/webservers/nginx.yml group_vars support directory and every file inside the group will be loaded
##6. Name consistency
If you want to maintain your code, keep the name consistency between your plays, inventories, roles and group variables. Use the name of the roles to separate different variables in each group. For instance, if you are using the role nginx under webservers play, variables that belong to nginx should be located under *group_vars/webservers/nginx.yml*. What his effectively means is that group_vars supports directory and every file inside the group will be loaded. You can, of course, put all of them in a single file as well, but this is messy, therefore don't do it.
##7. Encrypting Passwords and Certificates
It is most likely that you will have a password or certificates in your repository. It is not a good practise to put them in a repository as plain text. You can use [ansible-vault](http://docs.ansible.com/playbooks_vault.html) to encrypt sensitive data. You can refer to [postgresql-password.yml](https://github.com/enginyoyen/ansible-best-practises/blob/master/group_vars/postgresql/postgresql-password.yml) in group variables to see the encrypted file and [postgresql-password-plain.yml](https://github.com/enginyoyen/ansible-best-practises/blob/master/group_vars/postgresql/postgresql-password-plain.yml) to see the plain text file, commented out.
To decrypt the file, you need the vault password, which you can place in your root directory but it MUST NOT be committed to your git repository. You should share the password with you coworkers with some other method than committing to git a repo.
#Running the Code
Code in this repo is functional and test it. To run it:
* Create a vpass text file in the root directory and add the secret code (123456)
* Go to roles directory and execute to download roles
```
ansible-galaxy install -r requirements.yml --force
```
* Go to plays directory and the execute and do not forget to change the host address in the development.ini
```
ansible-playbook -i ../development.ini webservers.yml
```
#TODO
* ansible-vault example
#License
MIT License.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment