torwachter: rm d3 key as he does no longer want access as told by ruru. Also better...

[noc.git] / ansible / README.md

diff --git a/ansible/README.md b/ansible/README.md
index e29e7ca..a8b88a4 100644 (file)
--- a/ansible/README.md
+++ b/ansible/README.md
@@ -16,6 +16,8 @@ ansible-playbook foo.yml -D -C
 #   -m ... load module shell
 #   -a ... arguments to module call
 ansible vex -m shell -a 'uname -a'
+ansible servers -m apt -a 'name=foo state=present'
+ansible desktops -m file -a 'name=/make/sure/this/file/is/gone state=absent'
 ```
 
 ### check if all server are reachable
@@ -33,40 +35,59 @@ ansible-playbook foo.yml
 ./apply-role.sh wuerfel base
 ```
 
-### deploy a single role to a group of hosts using additional options
+### deploy a single role to a group of hosts with check-mode to see what would be done
 ```
 ./apply-role.sh servers base -C -D
 ```
 
+ansible-lint
+------------
+
+We use ansible-lint to check all roles when changes are pushed to Github.
+Some rules have been globally disabled. See [.ansible-lint](/ansible/.ansible-lint)
+for a list of all disabled rules. If ansible-lint produces a false positive for
+a specific task you can disable it by adding the following to the task:
+
+```
+  tags:
+  - skip_ansible_lint
+```
+
+For now only roles and no playbooks are checked. Every role must be manually added
+to the generic playbook [_lint_roles.yml](/ansible/_lint_roles.yml) in order to be
+included.
+If an entire role should be skipped please add it to the playbook commented out
+and supply a reason why this role must be skipped.
+
 
 Local ssh config
 ----------------
 
 By default hosts in the inventory use the FQDNs as the name so most
 hosts should be reachable without any special configuration.
-In addition r3 NOC uses the localconfig playbook/role to generate a
+In addition r3 NOC uses the `localconfig` playbook/role to generate a
 ssh config snippet to add nicer/shorter aliases for the hosts and also
-to automatically add jump hosts and some other special settins.
+to automatically add jump hosts and some other special settings.
 
 The way this works is that config snippets are generated inside
-`~/.ssh/config.d/` and (optionally) then compiled to a single file in
+`~/.ssh/config.d/` and (optionally) then compiled to a single file
 `~/.ssh/config`. If you want to use it as well you should move your
-current ssh config file to `~/.ssh/confi.d/` and run the playbook
-localconfig.yml.
+current ssh config file to `~/.ssh/config.d/` and run the playbook
+`localconfig.yml`.
 In order to make the generated config snippet work for different
 people the role sources the file `~/.ssh/r3_localconfig.yml`.
 All variables inside that file will take precedence of files from
-host_vars, group_varis, facts, etc.
+`host_vars`, `group_vars`, gathered facts, etc.
 
 
 Secrets
 -------
 
-See [README_vault.md](/README_vault.md) on how to create vaults.
+See [README_vault.md](/ansible/README_vault.md) on how to create vaults.
 
 In general vaults should live in `host_vars/<hostname>/vault.yml` or
 `group_vars/<groupname>/vault.yml`. The variables defined inside the
-vaults should be prefix with `vault_` and be referenced by other
+vaults should be prefixed with `vault_` and be referenced by other
 variables and not used directly in plays and roles. For example if you
 want to set a secret variable `root_pasword` for host `foo` there should
 be two files:
@@ -81,5 +102,9 @@ be two files:
 
 Of course the latter file needs to be created using `ansible-vault`.
 
-If you wan't to store secrets that by default shouldn't be exposed to
-hosts and groups as variables please put the vault files into `secrets`.
+If you want to store secrets that by default shouldn't be automatically
+exposed to hosts and groups as variables please put the vault files into
+`secrets` directory and name them <some-name>.vault.yml.
+
+r3 NOC uses [ansible-vault-tools](https://github.com/building5/ansible-vault-tools)
+to manage/diff/merge changes in vaults.