add some info about ansible-lint

[noc.git] / ansible / README.md

diff --git a/ansible/README.md b/ansible/README.md
index e29e7ca..967d1db 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'
 #   -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
 ```
 
 ### check if all server are reachable

@@ -33,40 +35,58 @@ ansible-playbook foo.yml
 ./apply-role.sh wuerfel base
 ```
 
 ./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
 ```
 
 ```
 ./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 are checked and every role must be manually added to the
+generic playbook [_lint_roles.yml](/ansible/_lint_roles.yml) in order to be checked.
+If an entire role should be skipped please add it to the playbook commented out
+and supply a reason why this roles 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.
 
 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
 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
 
 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
 `~/.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
 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
 -------
 
 
 
 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
 
 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:
 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 +101,9 @@ be two files:
 
 Of course the latter file needs to be created using `ansible-vault`.
 
 
 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.