commit 657dd98c821411f3cf08396534b0c86ac20eea37 Author: Achim Christ Date: Wed Nov 29 16:25:46 2017 +0100 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a8b42eb --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.retry diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9891267 --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..289cb63 --- /dev/null +++ b/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 diff --git a/anygroup.yml b/anygroup.yml new file mode 100644 index 0000000..50bc577 --- /dev/null +++ b/anygroup.yml @@ -0,0 +1,9 @@ +--- +- hosts: anygroup + roles: + - common + - anyrole + +# Associate further roles to servers in specific group in this file... + +... diff --git a/group_vars/all.yml b/group_vars/all.yml new file mode 100644 index 0000000..3c26339 --- /dev/null +++ b/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... + +... diff --git a/group_vars/anygroup.yml b/group_vars/anygroup.yml new file mode 100644 index 0000000..b7fc7d4 --- /dev/null +++ b/group_vars/anygroup.yml @@ -0,0 +1,5 @@ +--- + +# Add variables which apply to servers in a specific group to this file... + +... diff --git a/hosts b/hosts new file mode 100644 index 0000000..45fb033 --- /dev/null +++ b/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 diff --git a/roles/anyrole/handlers/.gitkeep b/roles/anyrole/handlers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/roles/anyrole/tasks/main.yml b/roles/anyrole/tasks/main.yml new file mode 100644 index 0000000..8153fcb --- /dev/null +++ b/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... + +... diff --git a/roles/anyrole/templates/.gitkeep b/roles/anyrole/templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/roles/common/handlers/.gitkeep b/roles/common/handlers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/roles/common/tasks/main.yml b/roles/common/tasks/main.yml new file mode 100644 index 0000000..1ae6e84 --- /dev/null +++ b/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... + +... diff --git a/roles/common/templates/.gitkeep b/roles/common/templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..6f9c89b --- /dev/null +++ b/site.yml @@ -0,0 +1,6 @@ +--- +- import_playbook: anygroup.yml + +# Import all other group playbooks in this file... + +...