From: Christian Pointner Date: Sat, 21 Apr 2018 19:06:59 +0000 (+0200) Subject: ansible: add some docs on how to use this X-Git-Url: https://git.realraum.at/?a=commitdiff_plain;h=f21af8f13cce3fcb4ed000a2c6b19062c5ede845;p=noc.git ansible: add some docs on how to use this --- diff --git a/ansible/README.md b/ansible/README.md new file mode 100644 index 0000000..e29e7ca --- /dev/null +++ b/ansible/README.md @@ -0,0 +1,85 @@ +Overview +======== + +This should provide a short overview on how to use ansible + +### basic ansible playbook call + +``` +# -C ... check +# -D ... show diff of changes +ansible-playbook foo.yml -D -C +``` + +### basic ansible call +``` +# -m ... load module shell +# -a ... arguments to module call +ansible vex -m shell -a 'uname -a' +``` + +### check if all server are reachable +``` +ansible servers -m ping +``` + +### deploy playbook +``` +ansible-playbook foo.yml +``` + +### deploy a single role to a single host +``` +./apply-role.sh wuerfel base +``` + +### deploy a single role to a group of hosts using additional options +``` +./apply-role.sh servers base -C -D +``` + + +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 +ssh config snippet to add nicer/shorter aliases for the hosts and also +to automatically add jump hosts and some other special settins. + +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`. 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. +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. + + +Secrets +------- + +See [README_vault.md](/README_vault.md) on how to create vaults. + +In general vaults should live in `host_vars//vault.yml` or +`group_vars//vault.yml`. The variables defined inside the +vaults should be prefix 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: + * `host_vars/foo/main.yml`: + ``` + root_password: "{{ vault_root_password }}" + ``` + * `host_vars/foo/vault.yml`: + ``` + vault_root_password: "this-is-very-secret" + ``` + +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`.