Tuer firmware (WIP)
[noc.git] / ansible / README.md
1 Overview
2 ========
3
4 This should provide a short overview on how to use ansible
5
6 ### basic ansible playbook call
7
8 ```
9 #   -C ... check
10 #   -D ... show diff of changes
11 ansible-playbook foo.yml -D -C
12 ```
13
14 ### basic ansible call
15 ```
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'
21 ```
22
23 ### check if all server are reachable
24 ```
25 ansible servers -m ping
26 ```
27
28 ### deploy playbook
29 ```
30 ansible-playbook foo.yml
31 ```
32
33 ### deploy a single role to a single host
34 ```
35 ./apply-role.sh wuerfel base
36 ```
37
38 ### deploy a single role to a group of hosts with check-mode to see what would be done
39 ```
40 ./apply-role.sh servers base -C -D
41 ```
42
43
44 Local ssh config
45 ----------------
46
47 By default hosts in the inventory use the FQDNs as the name so most
48 hosts should be reachable without any special configuration.
49 In addition r3 NOC uses the `localconfig` playbook/role to generate a
50 ssh config snippet to add nicer/shorter aliases for the hosts and also
51 to automatically add jump hosts and some other special settings.
52
53 The way this works is that config snippets are generated inside
54 `~/.ssh/config.d/` and (optionally) then compiled to a single file
55 `~/.ssh/config`. If you want to use it as well you should move your
56 current ssh config file to `~/.ssh/config.d/` and run the playbook
57 `localconfig.yml`.
58 In order to make the generated config snippet work for different
59 people the role sources the file `~/.ssh/r3_localconfig.yml`.
60 All variables inside that file will take precedence of files from
61 `host_vars`, `group_vars`, gathered facts, etc.
62
63
64 Secrets
65 -------
66
67 See [README_vault.md](/ansible/README_vault.md) on how to create vaults.
68
69 In general vaults should live in `host_vars/<hostname>/vault.yml` or
70 `group_vars/<groupname>/vault.yml`. The variables defined inside the
71 vaults should be prefixed with `vault_` and be referenced by other
72 variables and not used directly in plays and roles. For example if you
73 want to set a secret variable `root_pasword` for host `foo` there should
74 be two files:
75   * `host_vars/foo/main.yml`:
76     ```
77     root_password: "{{ vault_root_password }}"
78     ```
79   * `host_vars/foo/vault.yml`:
80     ```
81     vault_root_password: "this-is-very-secret"
82     ```
83
84 Of course the latter file needs to be created using `ansible-vault`.
85
86 If you want to store secrets that by default shouldn't be automatically
87 exposed to hosts and groups as variables please put the vault files into
88 `secrets` directory and name them <some-name>.vault.yml.
89
90 r3 NOC uses [ansible-vault-tools](https://github.com/building5/ansible-vault-tools)
91 to manage/diff/merge changes in vaults.