4 This should provide a short overview on how to use ansible
6 ### basic ansible playbook call
10 # -D ... show diff of changes
11 ansible-playbook foo.yml -D -C
14 ### basic ansible call
16 # -m ... load module shell
17 # -a ... arguments to module call
18 ansible vex -m shell -a 'uname -a'
19 ansible servers -m apt -a 'name=foo state=present'
20 ansible desktops -m file -a 'name=/make/sure/this/file/is/gone state=absent'
23 ### check if all server are reachable
25 ansible servers -m ping
30 ansible-playbook foo.yml
33 ### deploy a single role to a single host
35 ./apply-role.sh wuerfel base
38 ### deploy a single role to a group of hosts with check-mode to see what would be done
40 ./apply-role.sh servers base -C -D
46 We use ansible-lint to check all roles when changes are pushed to Github.
47 Some rules have been globally disabled. See [.ansible-lint](/ansible/.ansible-lint)
48 for a list of all disabled rules. If ansible-lint produces a false positive for
49 a specific task you can disable it by adding the following to the task:
56 For now only roles are checked and every role must be manually added to the
57 generic playbook [_lint_roles.yml](/ansible/_lint_roles.yml) in order to be checked.
58 If an entire role should be skipped please add it to the playbook commented out
59 and supply a reason why this roles must be skipped.
65 By default hosts in the inventory use the FQDNs as the name so most
66 hosts should be reachable without any special configuration.
67 In addition r3 NOC uses the `localconfig` playbook/role to generate a
68 ssh config snippet to add nicer/shorter aliases for the hosts and also
69 to automatically add jump hosts and some other special settings.
71 The way this works is that config snippets are generated inside
72 `~/.ssh/config.d/` and (optionally) then compiled to a single file
73 `~/.ssh/config`. If you want to use it as well you should move your
74 current ssh config file to `~/.ssh/config.d/` and run the playbook
76 In order to make the generated config snippet work for different
77 people the role sources the file `~/.ssh/r3_localconfig.yml`.
78 All variables inside that file will take precedence of files from
79 `host_vars`, `group_vars`, gathered facts, etc.
85 See [README_vault.md](/ansible/README_vault.md) on how to create vaults.
87 In general vaults should live in `host_vars/<hostname>/vault.yml` or
88 `group_vars/<groupname>/vault.yml`. The variables defined inside the
89 vaults should be prefixed with `vault_` and be referenced by other
90 variables and not used directly in plays and roles. For example if you
91 want to set a secret variable `root_pasword` for host `foo` there should
93 * `host_vars/foo/main.yml`:
95 root_password: "{{ vault_root_password }}"
97 * `host_vars/foo/vault.yml`:
99 vault_root_password: "this-is-very-secret"
102 Of course the latter file needs to be created using `ansible-vault`.
104 If you want to store secrets that by default shouldn't be automatically
105 exposed to hosts and groups as variables please put the vault files into
106 `secrets` directory and name them <some-name>.vault.yml.
108 r3 NOC uses [ansible-vault-tools](https://github.com/building5/ansible-vault-tools)
109 to manage/diff/merge changes in vaults.