Browse Source

Initial commit

master
Achim Christ 7 years ago
commit
657dd98c82
  1. 1
      .gitignore
  2. 21
      LICENSE
  3. 141
      README.md
  4. 9
      anygroup.yml
  5. 8
      group_vars/all.yml
  6. 5
      group_vars/anygroup.yml
  7. 21
      hosts
  8. 0
      roles/anyrole/handlers/.gitkeep
  9. 8
      roles/anyrole/tasks/main.yml
  10. 0
      roles/anyrole/templates/.gitkeep
  11. 0
      roles/common/handlers/.gitkeep
  12. 12
      roles/common/tasks/main.yml
  13. 0
      roles/common/templates/.gitkeep
  14. 6
      site.yml

1
.gitignore

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

21
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.

141
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

9
anygroup.yml

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

8
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...
...

5
group_vars/anygroup.yml

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

21
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

0
roles/anyrole/handlers/.gitkeep

8
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...
...

0
roles/anyrole/templates/.gitkeep

0
roles/common/handlers/.gitkeep

12
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...
...

0
roles/common/templates/.gitkeep

6
site.yml

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