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 ansible-lint
  44 ------------
  45
  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:
  50
  51 ```
  52   tags:
  53   - skip_ansible_lint
  54 ```
  55
  56 For now only roles and no playbooks are checked. Every role must be manually added
  57 to the generic playbook [_lint_roles.yml](/ansible/_lint_roles.yml) in order to be
  58 included.
  59 If an entire role should be skipped please add it to the playbook commented out
  60 and supply a reason why this role must be skipped.
  61
  62
  63 Local ssh config
  64 ----------------
  65
  66 By default hosts in the inventory use the FQDNs as the name so most
  67 hosts should be reachable without any special configuration.
  68 In addition r3 NOC uses the `localconfig` playbook/role to generate a
  69 ssh config snippet to add nicer/shorter aliases for the hosts and also
  70 to automatically add jump hosts and some other special settings.
  71
  72 The way this works is that config snippets are generated inside
  73 `~/.ssh/config.d/` and (optionally) then compiled to a single file
  74 `~/.ssh/config`. If you want to use it as well you should move your
  75 current ssh config file to `~/.ssh/config.d/` and run the playbook
  76 `localconfig.yml`.
  77 In order to make the generated config snippet work for different
  78 people the role sources the file `~/.ssh/r3_localconfig.yml`.
  79 All variables inside that file will take precedence of files from
  80 `host_vars`, `group_vars`, gathered facts, etc.
  81
  82
  83 Secrets
  84 -------
  85
  86 See [README_vault.md](/ansible/README_vault.md) on how to create vaults.
  87
  88 In general vaults should live in `host_vars/<hostname>/vault.yml` or
  89 `group_vars/<groupname>/vault.yml`. The variables defined inside the
  90 vaults should be prefixed with `vault_` and be referenced by other
  91 variables and not used directly in plays and roles. For example if you
  92 want to set a secret variable `root_pasword` for host `foo` there should
  93 be two files:
  94   * `host_vars/foo/main.yml`:
  95     ```
  96     root_password: "{{ vault_root_password }}"
  97     ```
  98   * `host_vars/foo/vault.yml`:
  99     ```
 100     vault_root_password: "this-is-very-secret"
 101     ```
 102
 103 Of course the latter file needs to be created using `ansible-vault`.
 104
 105 If you want to store secrets that by default shouldn't be automatically
 106 exposed to hosts and groups as variables please put the vault files into
 107 `secrets` directory and name them <some-name>.vault.yml.
 108
 109 r3 NOC uses [ansible-vault-tools](https://github.com/building5/ansible-vault-tools)
 110 to manage/diff/merge changes in vaults.