From 0aff90546ac4205be97f01d6da821206f19dfa4e 2014-11-09 00:49:15
From: Branko Majic <branko@majic.rs>
Date: 2014-11-09 00:49:15
Subject: [PATCH] MAR-2: Updated docs formatting a bit. Added documentation for the bootstrap role. Updated bootstrap role a bit to have better authorized key referencing.

---

diff --git a/docs/rolereference.rst b/docs/rolereference.rst
index c39387179e3ff88f2b49ba0a06faaa69c4ee6475..acf80e381267f6ab8adf950c00deca3578eb7b03 100644
--- a/docs/rolereference.rst
+++ b/docs/rolereference.rst
@@ -47,22 +47,22 @@ Parameters
     DHCP) or manual. If manual configuration is selected a number of
     additional options needs to be specified.
 
-  **network_ip** (string, mandatory if **network_auto** if *False*)
+  **network_ip** (string, mandatory if **network_auto** is set to ``no``)
     IP address for the server network interface.
 
-  **network_netmask** (string, mandatory if **network_auto** if *False*)
+  **network_netmask** (string, mandatory if **network_auto** is set to ``no``)
     Netmask for the server network interface.
 
-  **network_gateway** (string, mandatory if **network_auto** if *False*)
+  **network_gateway** (string, mandatory if **network_auto** is set to ``no``)
     Default gateway for the server.
 
-  **network_dns** (string, mandatory if **network_auto** if *False*)
+  **network_dns** (string, mandatory if **network_auto** is set to ``no``)
     Comma-separated list of DNS servers.
 
-  **network_hostname** (string, mandatory if **network_auto** if *False*)
+  **network_hostname** (string, mandatory if **network_auto** is set to ``no``)
     Server hostname.
 
-  **network_domain** (string, mandatory if **network_auto** if *False*)
+  **network_domain** (string, mandatory if **network_auto** is set to ``no``)
     Server domain.
 
   **mirror_hostname** (string, mandatory)
@@ -131,6 +131,56 @@ automatic and one with manual network configuration:
       timezone: Europe/Stockholm
 
 
+Bootstrap
+---------
+
+The ``bootstrap`` role can be used for bootstraping a new server with
+Ansible. In order to apply this role to a server, all that is necessary is root
+access to the server (either via SSH or locally).
+
+The role implements the following:
+
+* Installs sudo package.
+* Creates operating system user and group for Ansible (``ansible``).
+* Sets-up an authorized_key for operating system user ``ansible`` (for remote
+  SSH access).
+* Configures sudo to allow operating system user ``ansible`` to run sudo
+  commands without password authentication.
+
+
+Parameters
+~~~~~~~~~~
+
+**ansible_key** (string, mandatory)
+  SSH public key that should be deployed to authorized_keys truststore for
+  operating system user ``ansible``.
+
+
+Examples
+~~~~~~~~
+
+Since the role is meant to be used just after the server has been installed, and
+using the ``root`` account, it is probably going to be invoked from a separate
+playbook.
+
+For example, a playbook (``bootstrap.yml``) could look something similar to:
+
+.. code-block:: yaml
+
+  ---
+
+  - hosts: "{{ server }}"
+    remote_user: root
+    roles:
+      - bootstrap
+    vars:
+      ansible_key: "{{ lookup('file', 'authorized_keys/ansible.pub') }}"
+
+With such a playbook in place, it would be invoked with:
+
+  ansible-playbook --ask-pass -e server=test1.example.com bootstrap.yml
+
+
 Common
 ------
 
@@ -166,7 +216,7 @@ Parameters
   **additional_groups** (string, mandatory)
     Comma-separated list of additional groups that a user should belong to. If
     no additional groups should be appended to user's list of groups, set it to
-    empty string.
+    empty string (``""``).
 
   **authorized_keys** (list, mandatory)
     List of SSH public keys that should be deployed to user's authorized_keys
diff --git a/roles/bootstrap/tasks/main.yml b/roles/bootstrap/tasks/main.yml
index 6e32bbd6d0016ec5ec80fe20ea0c00b910f16799..d225e9f7ccd3772d16e1e59367478b1067b8d958 100644
--- a/roles/bootstrap/tasks/main.yml
+++ b/roles/bootstrap/tasks/main.yml
@@ -10,7 +10,7 @@
   user: name=ansible system=yes group=ansible shell=/bin/bash
 
 - name: Set-up authorized key for the Ansible user
-  authorized_key: user=ansible key="{{ lookup('file', ansible_key) }}"
+  authorized_key: user=ansible key="{{ ansible_key }}"
 
 - name: Set-up password-less sudo for the ansible user
   copy: src=ansible_sudo dest=/etc/sudoers.d/ansible mode=640 owner=root group=root
\ No newline at end of file