├── notes └── .keep ├── roles └── .keep ├── tmp └── .keep ├── galaxy_roles └── .keep ├── playbooks └── .keep ├── log ├── inventories ├── group_vars │ └── .keep └── host_vars │ └── .keep ├── requirements.yml ├── Pipfile ├── .gitignore ├── LICENSE ├── ansible.cfg └── README.md /notes/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /roles/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /tmp/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /galaxy_roles/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /playbooks/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /log: -------------------------------------------------------------------------------- 1 | /tmp/ansible.log -------------------------------------------------------------------------------- /inventories/group_vars/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /inventories/host_vars/.keep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /requirements.yml: -------------------------------------------------------------------------------- 1 | --- 2 | # EXAMPLE 3 | # - src: github.repo 4 | # path: galaxy_roles 5 | # name: role.name 6 | -------------------------------------------------------------------------------- /Pipfile: -------------------------------------------------------------------------------- 1 | [[source]] 2 | url = 'https://pypi.python.org/simple' 3 | verify_ssl = true 4 | name = 'pypi' 5 | 6 | [requires] 7 | python_version = '3.6.6' 8 | 9 | [packages] 10 | ansible = "*" 11 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .ruby-version 2 | .ruby-gemset 3 | .vagrant/* 4 | galaxy_roles/* 5 | !galaxy_roles/.keep 6 | *.swp 7 | tmp/* 8 | !tmp/.keep 9 | *.pyc 10 | *.retry 11 | inventories/group_vars/*/secret/* 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Mike Chau 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /ansible.cfg: -------------------------------------------------------------------------------- 1 | [defaults] 2 | 3 | ############################################################################### 4 | # LOG_PATH 5 | ############################################################################### 6 | # 7 | # If present and configured in ansible.cfg, Ansible will log information about 8 | # executions at the designated location. Be sure the user running Ansible has 9 | # permissions on the logfile. 10 | # 11 | # This behavior is not on by default. Note that ansible will, without this 12 | # setting, record module arguments called to the syslog of managed machines. 13 | # Password arguments are excluded. 14 | # 15 | # http://docs.ansible.com/ansible/intro_configuration.html#log-path 16 | # 17 | log_path = /tmp/ansible.log 18 | 19 | ############################################################################### 20 | # RETRY_FILES_ENABLED 21 | ############################################################################### 22 | # This controls whether a failed Ansible playbook should create a .retry file. 23 | # 24 | # The default setting is True. 25 | # 26 | retry_files_enabled = True 27 | 28 | ############################################################################### 29 | # RETRY_FILES_SAVE_PATH 30 | ############################################################################### 31 | # 32 | # The retry files save path is where Ansible will save .retry files when a 33 | # playbook fails and retry_files_enabled is True (the default). The default 34 | # location is adjacent to the play (~/ in versions older than 2.0) and can be 35 | # changed to any writeable path. 36 | # 37 | # http://docs.ansible.com/ansible/intro_configuration.html#retry-files-save-path 38 | # 39 | retry_files_save_path = tmp 40 | 41 | ############################################################################### 42 | # ROLES_PATH 43 | ############################################################################### 44 | # 45 | # The roles path indicate additional directories beyond the ‘roles/’ 46 | # subdirectory of a playbook project to search to find Ansible roles. 47 | # 48 | # http://docs.ansible.com/ansible/intro_configuration.html#roles-path 49 | # 50 | roles_path = galaxy_roles:roles 51 | 52 | ############################################################################### 53 | # CALLBACK_WHITELIST 54 | ############################################################################### 55 | # 56 | # Now ansible ships with all included callback plugins ready to use but they 57 | # are disabled by default. This setting lets you enable a list of additional 58 | # callbacks. 59 | # 60 | # http://docs.ansible.com/ansible/intro_configuration.html#callback-whitelist 61 | # 62 | callback_whitelist = timer, profile_tasks 63 | 64 | ############################################################################### 65 | # STDOUT_CALLBACK 66 | ############################################################################### 67 | # 68 | # This setting allows you to override the default stdout callback for 69 | # ansible-playbook. 70 | # 71 | # http://docs.ansible.com/ansible/intro_configuration.html#stdout-callback 72 | # 73 | stdout_callback = skippy 74 | 75 | ############################################################################### 76 | # GATHERING 77 | ############################################################################### 78 | # 79 | # The ‘gathering’ setting controls the default policy of facts gathering (variables discovered about remote systems). 80 | # 81 | # The value ‘implicit’ is the default, which means that the fact cache will be 82 | # ignored and facts will be gathered per play unless ‘gather_facts: False’ is 83 | # set. 84 | # 85 | # The value ‘explicit’ is the inverse, facts will not be gathered unless 86 | # directly requested in the play. 87 | # 88 | # The value ‘smart’ means each new host that has no facts discovered will be 89 | # scanned, but if the same host is addressed in multiple plays it will not be 90 | # contacted again in the playbook run. This option can be useful for those 91 | # wishing to save fact gathering time. 92 | # 93 | # Both ‘smart’ and ‘explicit’ will use the fact cache. 94 | # 95 | # http://docs.ansible.com/ansible/intro_configuration.html#gathering 96 | # 97 | gathering = smart 98 | 99 | [ssh_connection] 100 | ############################################################################### 101 | # SSH_ARGS 102 | ############################################################################### 103 | # 104 | # If set, this will pass a specific set of options to Ansible rather than 105 | # Ansible’s usual defaults (-o ControlMaster=auto -o ControlPersist=60s). 106 | # 107 | # http://docs.ansible.com/ansible/intro_configuration.html#ssh-args 108 | # 109 | # Configured to use ssh forwarding, control persistence set to 30 minutes (this 110 | # allows for faster reconnection) and does not save the remote host to known 111 | # hosts. 112 | # 113 | ssh_args = -o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=30m -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 114 | 115 | ############################################################################### 116 | # PIPELINING 117 | ############################################################################### 118 | # 119 | # Enabling pipelining reduces the number of SSH operations required to execute 120 | # a module on the remote server, by executing many ansible modules without 121 | # actual file transfer. This can result in a very significant performance 122 | # improvement when enabled, however when using “sudo:” operations you must 123 | # first disable ‘requiretty’ in /etc/sudoers on all managed hosts. 124 | # 125 | # By default, this option is disabled to preserve compatibility with sudoers 126 | # configurations that have requiretty (the default on many distros), but is 127 | # highly recommended if you can enable it. 128 | # 129 | # http://docs.ansible.com/ansible/intro_configuration.html#pipelining 130 | # 131 | pipelining = True 132 | 133 | ############################################################################### 134 | # CONTROL_PATH 135 | ############################################################################### 136 | # 137 | # This is the location to save ControlPath sockets. 138 | # 139 | # This defaults to %(directory)s/ansible-ssh-%%h-%%p-%%r. 140 | # 141 | # http://docs.ansible.com/ansible/intro_configuration.html#control-path 142 | # 143 | control_path = /tmp/ansible-ssh-%%h-%%p-%%r 144 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ansible-boilerplate 2 | 3 | This repo is a boilerplate for getting started for repos containing Ansible 4 | playbooks. `git clone` this project and be on your merry way. 5 | 6 | ## Prerequisites 7 | 8 | ### Use pyenv and pipenv (recommended) 9 | 10 | You may want to use [pyenv](https://github.com/pyenv/pyenv) and [pipenv](https://github.com/pypa/pipenv) to manage your Python interpreter version and your virtualenv. 11 | 12 | ### Install Ansible (traditional method) 13 | 14 | If you want to use pipenv, you can skip this step 15 | 16 | #### pip 17 | 18 | - `pip install ansible` (may need to run this as `sudo`) 19 | 20 | ## Getting started 21 | 22 | ### Git clone 23 | 24 | - `git clone --depth=1 --branch=master https://github.com/mikechau/ansible-boilerplate.git` - clone the latest copy of the repo 25 | - `cd ansible-boilerplate && git remote rm origin` - remove the origin 26 | 27 | #### Initialize the project (if you use pipenv) 28 | 29 | - `pipenv install` - create a project, initialize the virtualenv, and install dependencies 30 | - `pipenv install --dev molecule docker` - add development dependencies to the project (optionnal) 31 | 32 | --- 33 | 34 | ### Directory structure 35 | 36 | ``` 37 | . 38 | ├── ansible.cfg 39 | ├── galaxy_roles 40 | ├── inventories 41 | │   ├── group_vars 42 | │   └── host_vars 43 | ├── LICENSE 44 | ├── log -> /tmp/ansible.log 45 | ├── notes 46 | ├── playbooks 47 | ├── README.md 48 | ├── requirements.yml 49 | ├── roles 50 | └── tmp 51 | ``` 52 | 53 | #### ansible.cfg 54 | 55 | This is a project specific configuration file to configure Ansible. [View](ansible.cfg) 56 | to see a more detailed explanation of the default settings provided by this 57 | project. 58 | 59 | ##### Read more 60 | 61 | - [Ansible.cfg - http://docs.ansible.com/ansible/intro_configuration.html](http://docs.ansible.com/ansible/intro_configuration.html) 62 | 63 | #### galaxy_roles 64 | 65 | This is where you should install your third-party roles from [Ansible Galaxy](https://galaxy.ansible.com/). 66 | 67 | Recommended to configure [requirements.yml](requirements.yml) with the third party roles you are 68 | using. 69 | 70 | ##### Read more 71 | 72 | - [Ansible Galaxy - http://docs.ansible.com/ansible/galaxy.html](http://docs.ansible.com/ansible/galaxy.html) 73 | 74 | #### inventories 75 | 76 | This is where you should put the list of hosts for Ansible to connect to. It 77 | also contains directories for [group_vars](http://docs.ansible.com/ansible/intro_inventory.html#group-variables) and [host_vars](http://docs.ansible.com/ansible/intro_inventory.html#host-variables). 78 | 79 | Example: 80 | 81 | ``` 82 | . 83 | ├── group_vars 84 | ├── host_vars 85 | └── production 86 | ``` 87 | 88 | We have a file called `production`, but if you have a lot of environments, 89 | instead of `production`, you might call it `production_app_name` or 90 | `app_name_production`, etc. 91 | 92 | In it you might define it like so: 93 | 94 | ```yml 95 | # inventories/production 96 | [application] 97 | app01.server.com 98 | app02.server.com 99 | app03.server.com 100 | 101 | [database] 102 | db01.server.com 103 | 104 | [production:children] 105 | application 106 | database 107 | ``` 108 | 109 | `production:children`, indicates to Ansible this is a group of made of all the 110 | things in the groups listed below. 111 | 112 | So its equivalent to manually writing: 113 | 114 | ``` 115 | # inventories/production 116 | [production] 117 | app01.server.com 118 | app02.server.com 119 | app03.server.com 120 | db01.server.com 121 | ``` 122 | 123 | ##### group_vars 124 | 125 | This directory contains yaml files which correspond to a group name, and tells 126 | Ansible to load the variables for the hosts in that group. 127 | 128 | Example structure: 129 | 130 | ``` 131 | . 132 | └── group_vars 133 | ├── all 134 | │   └── ubuntu.yml 135 | ├── application 136 | │   ├── rails.yml 137 | │   └── secret 138 | │   └── rails.yml 139 | └── database 140 | ├── mysql.yml 141 | ├── postgresql.yml 142 | └── secret 143 | ├── mysql.yml 144 | └── postgresql.yml 145 | ``` 146 | 147 | - `all` - is a Ansible group, where it will be loaded for all hosts. 148 | - `application`- is a user defined group of hosts, we defined this in our `production` hosts file in the previous example. 149 | - `database` - is a user defined group of hosts, we defined this in our `production` hosts file in the previous example. 150 | 151 | A group variable file looks like this: 152 | 153 | ```yml 154 | # inventories/group_vars/application/rails.yml 155 | --- 156 | rails_version: 5.0.0 157 | ``` 158 | 159 | So the `rails_version` variable will be available for all hosts listed under `application` (app[0-3].server.com). 160 | 161 | **NOTE:** You might have noticed the `secret` directory, this is where you can 162 | take advantage of [ansible-vault](http://docs.ansible.com/ansible/playbooks_vault.html). For secret specific variables such as api keys and etc, 163 | I like to put them inside a `secret` folder, and encrypt the folder with `ansible-vault`. 164 | 165 | Secrets are prefixed with the key `secret_`. 166 | 167 | Example: 168 | 169 | ```yml 170 | # Encrypted secrets for rails 171 | # inventories/group_vars/application/secret/rails.yml 172 | --- 173 | secret_rails_secret_token: 1db372dbc0a8200da1d7f9c51384fe0094c940628c497e7e519eb4977aba244cdad0ab9c4965383d2dc9244296ea6b889fe711d40dc590a4455d17e1a012db58 174 | ``` 175 | 176 | ```yml 177 | # Unencrypted secrets for rails 178 | # inventories/group_vars/application/rails.yml 179 | --- 180 | rails_version: 5.0.0 181 | rails_secret_token: "{{ secret_rails_secret_token }}" 182 | ``` 183 | 184 | You can see our unencrypted variable file reference the encrypted variable file's variable in `secret`. 185 | 186 | ##### host_vars 187 | 188 | `host_vars` work just like `group_vars`, but instead of naming it after a 189 | group name, you use the `hostname`. The variables only be loaded for that specific host. 190 | 191 | Example: 192 | 193 | ``` 194 | . 195 | └── host_vars 196 | └── app01.server.com 197 | └── rails.yml 198 | ``` 199 | 200 | ##### Read More 201 | 202 | - [Inventory - http://docs.ansible.com/ansible/intro_inventory.html](http://docs.ansible.com/ansible/intro_inventory.html) 203 | - [Variables - http://docs.ansible.com/ansible/playbooks_variables.html](http://docs.ansible.com/ansible/playbooks_variables.html) 204 | 205 | --- 206 | 207 | #### log 208 | 209 | By default this is just a symlink to `tmp/ansible.log`. 210 | 211 | --- 212 | 213 | #### notes 214 | 215 | This is where you can add your notes for things like manual configuration. 216 | 217 | --- 218 | 219 | #### playbooks 220 | 221 | This is where [playbooks](http://docs.ansible.com/ansible/playbooks.html) 222 | should be placed. 223 | 224 | ##### Read More 225 | 226 | - [Playbooks - http://docs.ansible.com/ansible/playbooks.html](http://docs.ansible.com/ansible/playbooks.html) 227 | 228 | --- 229 | 230 | #### requirements.yml 231 | 232 | Edit this yml file to add your third-party roles from Github or Ansible Galaxy. 233 | 234 | Then install your roles with this command: 235 | 236 | ```bash 237 | ansible-galaxy install -r requirements.yml 238 | ``` 239 | 240 | [Ansible Galaxy - requirements - http://docs.ansible.com/ansible/galaxy.html#advanced-control-over-role-requirements-files](http://docs.ansible.com/ansible/galaxy.html#advanced-control-over-role-requirements-files) 241 | 242 | --- 243 | 244 | #### roles 245 | 246 | This is where you can add your custom Ansible [roles](http://docs.ansible.com/ansible/playbooks_roles.html#roles) for usage by your playbooks. 247 | 248 | ##### Read more 249 | 250 | [Roles - http://docs.ansible.com/ansible/playbooks_roles.html#roles](http://docs.ansible.com/ansible/playbooks_roles.html#roles) 251 | 252 | --- 253 | 254 | #### tmp 255 | 256 | A tmp directory for convenience. For example, you may prefer to write logs 257 | here. 258 | 259 | --- 260 | 261 | ### LICENSE 262 | 263 | MIT 264 | --------------------------------------------------------------------------------