ansible: add some docs on how to use this
[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 ```
20
21 ### check if all server are reachable
22 ```
23 ansible servers -m ping
24 ```
25
26 ### deploy playbook
27 ```
28 ansible-playbook foo.yml
29 ```
30
31 ### deploy a single role to a single host
32 ```
33 ./apply-role.sh wuerfel base
34 ```
35
36 ### deploy a single role to a group of hosts using additional options
37 ```
38 ./apply-role.sh servers base -C -D
39 ```
40
41
42 Local ssh config
43 ----------------
44
45 By default hosts in the inventory use the FQDNs as the name so most
46 hosts should be reachable without any special configuration.
47 In addition r3 NOC uses the localconfig playbook/role to generate a
48 ssh config snippet to add nicer/shorter aliases for the hosts and also
49 to automatically add jump hosts and some other special settins.
50
51 The way this works is that config snippets are generated inside
52 `~/.ssh/config.d/` and (optionally) then compiled to a single file in
53 `~/.ssh/config`. If you want to use it as well you should move your
54 current ssh config file to `~/.ssh/confi.d/` and run the playbook
55 localconfig.yml.
56 In order to make the generated config snippet work for different
57 people the role sources the file `~/.ssh/r3_localconfig.yml`.
58 All variables inside that file will take precedence of files from
59 host_vars, group_varis, facts, etc.
60
61
62 Secrets
63 -------
64
65 See [README_vault.md](/README_vault.md) on how to create vaults.
66
67 In general vaults should live in `host_vars/<hostname>/vault.yml` or
68 `group_vars/<groupname>/vault.yml`. The variables defined inside the
69 vaults should be prefix with `vault_` and be referenced by other
70 variables and not used directly in plays and roles. For example if you
71 want to set a secret variable `root_pasword` for host `foo` there should
72 be two files:
73   * `host_vars/foo/main.yml`:
74     ```
75     root_password: "{{ vault_root_password }}"
76     ```
77   * `host_vars/foo/vault.yml`:
78     ```
79     vault_root_password: "this-is-very-secret"
80     ```
81
82 Of course the latter file needs to be created using `ansible-vault`.
83
84 If you wan't to store secrets that by default shouldn't be exposed to
85 hosts and groups as variables please put the vault files into `secrets`.