Initial commit

.gitignore

@@ -0,0 +1 @@
+*.retry

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Achim Christ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,141 @@
+# Ansible-Boilerplate
+
+[Ansible](https://www.ansible.com/) is a configuration management tool, similar to [Chef](https://www.chef.io/) and [Puppet](https://puppet.com/). It allows for performing logical configuration of infrastructure components, such as servers and network switches. The configuration files in this repository can act as a template for your own Ansible projects, in order to get you started quickly. Once you've customized the configuration files then new servers can be configured quickly — excluding their network configuration. This means that adding new servers is as simple as:
+
+- Base OS installation of new server
+- Network configuration of new server (including bond, bridge, DNS and routing)
+- Configuration of password-less (public key) SSH authentication from the Ansible host (your laptop) to the new server
+
+The remaining configuration (installing packages, configuring services, etc.) can then be achieved using Ansible. In addition, Ansible ensures that configuration of all servers is and remains consistent.
+
+## Using this repository
+
+Simply download (clone) the repository and start modifying files according to your needs.
+
+```
+git clone https://github.com/acch/ansible-boilerplate.git myAnsibleProject/
+```
+
+Ideally, you'll want to use [Git](https://git-scm.com/) to manage your Ansible configuration files. For that purpose simply [fork](https://help.github.com/articles/fork-a-repo/) this repository into your own Git repository before cloning and customizing it. Git will allow you to version and roll-back changes with ease.
+
+Specifically, you'll want to customize the following files:
+- Add your own hosts and groups to file `hosts`. You'll want to replace `[anygroup]` with a more meaningful group name, and add your own groups as required.
+- Define roles by adding subdirectories underneath directory `roles/`. You'll want to rename `anyrole/` to a more meaningful role name, and add your own roles as required.
+- Associate your hosts (groups) with your roles by adding appropriate playbooks in the root directory. Rename `anygroup.yml` to a more meaningful playbook name.
+- Import all your playbooks in the main `site.yml` playbook.
+
+## Using Ansible
+
+Install `ansible` on your laptop and link the `hosts` file from `/etc/ansible/hosts` to the file in your repository. Now you're all set.
+
+To run a single (ad-hoc) task on multiple servers:
+
+```
+# Check connectivity
+ansible all -m ping -u root
+
+# Run single command on all servers
+ansible all -m command -a "cat /etc/hosts" -u root
+
+# Run single command only on servers in specific group
+ansible anygroup -m command -a "cat /etc/hosts" -u root
+
+# Run single command on individual server
+ansible server1 -m command -a "cat /etc/hosts" -u root
+```
+
+As the `command` module is the default, it can also be omitted:
+
+```
+ansible server1 -a "cat /etc/hosts" -u root
+```
+
+To use shell variables on the remote server, use the `shell` module instead of `command`, and use single quotes for the argument:
+
+```
+ansible server1 -m shell -a 'echo $HOSTNAME' -u root
+```
+
+The true power of ansible comes with so called *playbooks* — think of them as scripts, but they're declarative. Playbooks allow for running multiple tasks on any number of servers, as defined in the configuration files (`*.yml`):
+
+```
+# Run all tasks on all servers
+ansible-playbook site.yml -v
+
+# Run all tasks only on group of servers
+ansible-playbook anygroup.yml -v
+
+# Run all tasks only on individual server
+ansible-playbook site.yml -v -l server1
+```
+
+Note that `-v` produces verbose output. `-vv` and `-vvv` are also available for even more (debug) output.
+
+To verify what tasks would do without changing the actual configuration, use the `--list-hosts` and `--check` parameters:
+
+```
+# Show hosts that would be affected by playbook
+ansible-playbook site.yml --list-hosts
+
+# Perform dry-run to see what tasks would do
+ansible-playbook site.yml -v --check
+```
+
+Running all tasks in a playbook may take a long time. *Tags* are available to organize tasks so one can only run specific tasks to configure a certain component:
+
+```
+# Show list of available tags
+ansible-playbook site.yml --list-tags
+
+# Only run tasks required to configure DNS
+ansible-playbook site.yml -v -t dns
+```
+
+Note that the above command requires you to have tasks defined with the `tags: dns` attribute.
+
+## Configuration files
+
+The `hosts` file defines all hosts and groups which they belong to. Note that a single host can be member of multiple groups. Define groups for each rack, for each network, or for each environment (e.g. production vs. test).
+
+### Playbooks
+
+Playbooks associate hosts (groups) with roles. Define a separate playbook for each of your groups, and then import all playbooks in the main `site.yml` playbook.
+
+File | Description
+---- | -----------
+`site.yml` | Main playbook - runs all tasks on all servers
+`anygroup.yml` | Group playbook - runs all tasks on servers in group *anygroup*
+
+### Roles
+
+The group playbooks (e.g. `anygroup.yml`) simply associate hosts with roles. Actual tasks are defined in these roles:
+
+```
+roles/
+├── common/             Applied to all servers
+│   ├── handlers/
+│   ├── tasks/
+│   │   └ main.yml      Tasks for all servers
+│   └── templates/
+└── anyrole/            Applied to servers in specific group(s)
+    ├── handlers/
+    ├── tasks/
+    │   └ main.yml      Tasks for specific group(s)
+    └── templates/
+```
+
+Consider adding separate roles for different applications (e.g. webservers, dbservers, hypervisors, etc.), or for different responsibilities which servers fulfill (e.g. infra_server vs. infra_client).
+
+### Tags
+
+Use the following command to show a list of available tags:
+
+```
+ansible-playbook site.yml --list-tags
+```
+
+Consider adding tags for individual components (e.g. DNS, NTP, HTTP, etc.).
+
+Role | Tags
+--- | ---
+Common | all,check

anygroup.yml

@@ -0,0 +1,9 @@
+---
+- hosts: anygroup
+  roles:
+    - common
+    - anyrole
+
+# Associate further roles to servers in specific group in this file...
+
+...

group_vars/all.yml

@@ -0,0 +1,8 @@
+---
+# Default is to log in as root
+ansible_user: root
+remote_user: root
+
+# Add further variables which apply to all servers to this file...
+
+...

group_vars/anygroup.yml

@@ -0,0 +1,5 @@
+---
+
+# Add variables which apply to servers in a specific group to this file...
+
+...

hosts

@@ -0,0 +1,21 @@
+# This is the default ansible 'hosts' file.
+#
+# It should live in your Git repository, and there should be a link from /etc/ansible/hosts:
+#   /etc/ansible/hosts -> /path/to/myAnsibleProject/hosts
+#
+#   - Comments begin with the '#' character
+#   - Blank lines are ignored
+#   - Groups of hosts are delimited by [header] elements
+#   - You can enter hostnames or ip addresses
+#   - A hostname/ip can be a member of multiple groups
+
+[anygroup]
+server1     ansible_host=192.168.0.1
+server2     ansible_host=192.168.0.2
+server3     ansible_host=192.168.0.3
+server4     ansible_host=192.168.0.4
+
+# Add your own groups here. Hosts can be added to multiple groups like so:
+# [anothergroup]
+# server[1:3]
+# anotherserver     ansible_host=192.168.0.10

roles/anyrole/tasks/main.yml

@@ -0,0 +1,8 @@
+---
+#
+# Tasks to be applied to some servers
+#
+
+# Add tasks for a specific role to this playbook...
+
+...

roles/common/tasks/main.yml

@@ -0,0 +1,12 @@
+---
+#
+# Tasks to be applied to all servers
+#
+
+- name: Check connectivity
+  ping: data=alive
+  tags: check
+
+# Add further tasks for the common role (applied to all servers) to this playbook...
+
+...

site.yml

@@ -0,0 +1,6 @@
+---
+- import_playbook: anygroup.yml
+
+# Import all other group playbooks in this file...
+
+...