diff --git a/README.md b/README.md index 9fcf1d10a81511d65944b418d6ec42cfac651e57..9dcc2ba4a9ce868de358dafcfca892f5f66d0571 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ Base Linux ========== -This role does bootstrapping and common configuration for a base Linux server. +The primary purpose of this role is bootstrapping a host to allow Ansible tasks to be run against it. It does this by checking if Python is executable on the target host, providing remediation assistance if it isn't, and installing additional requirements to run Ansible tasks against the target host. + +The secondary purpose of this role is to install common utilities that most people would want on all servers. Requirements ------------ @@ -15,12 +17,9 @@ Role Variables |----------|---------|---------| | hostname | | The hostname to set on the server. If blank or undefined, the hostname will not be changed. | | required_utils | `[]` | Additional prerequisites required for Ansible, modules, etc. | -| common_utils | `[curl, git, gzip, htop, screen, unzip, vim]` | Common packages and utilities to install. | +| common_utils | `[curl, git, gzip, htop, screen, tree, unzip, vim]` | Common packages and utilities to install. | -OS specific variable overrides will be read from the `vars/` directory. The -first OS specific var file found will be loaded, and they are queried in -descending order by specificity. For example, Ubuntu would check files in this -order: +OS specific variable overrides will be read from the `vars/` directory. The first OS specific var file found will be loaded, and they are queried in order of descending specificity. For example, Ubuntu 18.04 would check the files in this order: 1. ubuntu-18.04.yml # Distribution name + full version number 1. ubuntu-bionic.yml # Distribution name + release name @@ -28,3 +27,36 @@ order: 1. ubuntu.yml # Distribution name 1. debian.yml # OS family name +Example Playbooks +----------------- + +The bootstrapping tasks included in this role typically only need to run once, so they are only ran if you specifically include the bootstrap task list. It's also recommended to tag them with the `never` tag and an additional tag so that they only run when that additional tag is used. + +```yaml +# Make sure all the hosts are bootstrapped. Only runs if the 'bootstrap' tag is used +- hosts: all + gather_facts: false + tags: ['never', 'bootstrap'] + tasks: + - include_role: + name: base-linux + tasks_from: bootstrap + +# The rest of your playbook +- hosts: all + tasks: + - include_role: + name: base-linux +``` + +The example above will run the main task list for every play, but the bootstrap task list will only run if the `bootstrap` tag is used. For example: + +```sh +ansible-playbook playbook.yml --tags=bootstrap +``` + + + + + +[_modeline]: # ( vi: set ts=4 sw=4 et wrap ft=markdown: )