Merge pull request #59 from adfinis/ansible-guide-ng

Ansible Guide 2.0

Makefile

@@ -1,43 +1,24 @@
 .DEFAULT_GOAL := help
 
-ROLES		:= $(wildcard adfinis-roles/*)
-ROLES_DOC	:= $(patsubst adfinis-roles/%, doc/%.rst, $(ROLES))
-ROLES_FILES	:= $(patsubst doc/%, %, $(ROLES_DOC))
+ROLES_DOC	:= $(doc/%.rst)
 
-all:
+all: doc
 
 help:  ## display this help
 	@cat $(MAKEFILE_LIST) | grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' | \
 		sort -k1,1 | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
 clean:  ## cleanup
-	rm -f requirements.yml
-	rm -f doc/adfinis-sygroup.*.rst
 	$(shell \
 		cd doc; \
 		make clean; \
 		cd ..; \
 	)
 
-requirements: ## create requirements.yml
-	echo "---" > requirements.yml
-	for role in $$(ansible-galaxy search --author adfinis-sygroup | awk '/adfinis/ {print $$1}'); do \
-	    printf "\n- src: %s\n  version: master" "$$role" >> requirements.yml; \
-	done
-
-install: ## install all ansible roles
-	ansible-galaxy install -r requirements.yml
-
 doc: $(ROLES_DOC)  ## create html documentation
-	cp mk/role_overview.rst doc/role_overview.rst
-	echo " $(ROLES_FILES)" | \
-		sed "s/.rst/.rst\n/g" | \
-		sort -u | \
-		grep -v '_template.rst' \
-		>> doc/role_overview.rst
 	cd doc && make html
 
-doc/%.rst: adfinis-roles/% doc/sphinx-template
+doc/%.rst: doc/sphinx-template
 	mk/yml2rst $* $< $@
 
 doc/sphinx-template:

README.md

@@ -9,7 +9,7 @@ available in the Adfinis Galaxy namespace.
 
 The rendered documentation is available here:
 
-* https://docs.adfinis.com/ansible-guide
+* https://adfinis.github.io/ansible-guide
 
 ## Dependencies
 

doc/conf.py

@@ -32,8 +32,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autosectionlabel'
 ]
 
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -60,16 +63,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '2.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+release = '2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/getting_started.rst

@@ -6,37 +6,37 @@ Getting Started
 Project Repository
 ==================
 
-.. warning::
-    This section is vastly outdated and will be rewritten in the near future.
-    Rather than adding a submodule, you should install roles and collections via `Ansible Galaxy <https://docs.ansible.com/ansible/latest/galaxy/user_guide.html>`_.
-
-First of all, you need a project repository. For that, you can just clone
-this repository or start a new one. As a Git Submodule you should add the
-`ansible-roles`_ as ``roles/``:
-
-::
-
-  git init
-  git commit -m 'Intial commit.' --allow-empty
-  git submodule add https://github.com/adfinis/ansible-roles adfinis-roles
-
-Create the main playbook ``site.yml`` with content along the following
-example. Add your roles as needed:
-
-::
-
-  ---
-
-  - hosts: all
-    roles:
-      - ansible
-      - console
-      - ssh
-
-Create an inventory file ``hosts``, create as many hostgroups as you need. A
-host can be in multiple hostgroups. Each host is in the hostgroup ``all``.
-
-::
+First of all, you need a project repository.  For this, simply create
+a directory and run ``git init``, or create a new project on the git
+forge of your choice and clone the repository.
+
+Now, let's configure Ansible.  For this, create a file named
+``ansible.cfg`` in your project's root directory:
+
+.. code-block:: ini
+
+   [defaults]
+   # Path to the default inventory file
+   inventory=inventory
+   # By default, roles and collections from Ansible Galaxy are installed to ~/.ansible.  To prevent conflicts
+   # between different versions, it can be useful to change this to another path.  Also add to gitignore!
+   collections_path=./galaxy
+   roles_path=./galaxy/ansible_roles
+ 
+   # The ansible_managed header used in templates can be multi-line; following lines need to be indented.
+   # Use multi-line headers with caution when using roles where you don't know how ansible_managed
+   # is used in templates.
+   ansible_managed = This file is managed by Ansible.  Manual changes will be overwritten.
+    Ansible repository: https://git.example.org/example/project
+
+
+The next step is to create an inventory file, ``inventory``,
+containing the hosts and groups of your infrastructure.  Create as
+many host groups as you need.  A host can be in multiple groups,
+and groups can contain other groups. Each host is automatically added
+to the the group ``all``.
+
+.. code-block:: ini
 
   www1.example.com
   www2.example.com
@@ -54,68 +54,105 @@ host can be in multiple hostgroups. Each host is in the hostgroup ``all``.
   www2.example.com
   db1.example.com
 
-You can now start Ansible, and Ansible will connect to each host with ssh.
-If you can't login with public keys, you can use ssh controlmaster with
-sockets, for that, create a file called ``ansible.cfg`` in the root of your
-project directory.
+
+Next, you declare which roles and collections you need to use.  Roles
+and collections installed from `Ansible Galaxy <https://galaxy.ansible.com>`_
+must be listed in the ``requirements.yml`` file:
+
+.. code-block:: yaml
+
+  ---
+
+  collections:
+
+    # A collection installed from Ansible Galaxy
+    - name: community.general
+      version: "7.3.0"
+
+    # A collection installed directly from a git repository
+    - name: https://git.example.org/example/ansible-collection-foo
+      type: git
+      version: "main"  # Name of the branch or tag
+
+  roles:
+
+    # A single role installed from Ansible Galaxy
+    - name: adfinis.users
+      version: "0.3.0"
+
+
+These dependencies can be installed using the ``ansible-galaxy`` command:
 
 ::
 
-  [defaults]
-  ansible_managed     = Warning: File is managed by Ansible [https://github.com/adfinis/ansible-roles]
-  retry_files_enabled = False
-  hostfile            = ./hosts
-  roles_path          = ./adfinis-roles
+   ansible-galaxy install -r requirements.yml
+
+
+To assign these roles to hosts, create a playbook; let's name it ``playbook.yml``:
+
+.. code-block:: yaml
+
+  ---
+
+  - hosts: all
+    roles:
+      - adfinis.users
+
+  - hosts: webservers
+      - community.general.redis
+      - example.foo.bar
 
-  [ssh_connection]
-  ssh_args            = -o ControlMaster=auto -o ControlPersist=30s
-  #control_path       = ~/.ssh/sockets/%C
 
-You need to create the directory ``~/.ssh/sockets`` and you should
-manually establish a connection to each host (with a command like ``ssh -o
-ControlMaster=auto -o ControlPath='~/.ssh/sockets/%C' -o ControlPersist=30s
--l root $FQDN``). While the connection is established (and 30 seconds
-after that) a socket file in ``~/.ssh/sockets/`` is generated. Ansible will use this
-socket file to connect to the hosts, and doesn't' need to reauthenticate.
-This speeds up Ansible operations considerably especially with many hosts.
+Most roles require additional configuration.  This can be provided
+both on a per-host and per-group basis.  While the exact filename does
+not matter, we recommend putting the host vars of a role into
+``host_vars/<hostname>/<rolename>.yml`` and group vars into
+``group_vars/<groupname>/<rolename>.yml``.
+
+For example, let's create ``group_vars/all/users.yml``:
+
+.. code-block:: yaml
+   
+   ---
+   
+   users_default_user: adfinis
+   
+   users_adfinis:
+     - username: adfinis
+     - username: customer
 
 
 Run Ansible
 ===========
 
 To run Ansible with your playbook and your hosts, just start
-``ansible-playbook -i hosts site.yml``. If you want to know what has
-changed, you can add the option ``--diff`` and if you want to know that
-before you change anything, you can add ``--check``. With the checkmode
-enabled, nothing gets changed on any of the systems!
+``ansible-playbook playbook.yml``. If you want to know what has
+changed, you can add the option ``--diff`` and if you want to know
+that before you change anything, you can add ``--check``. With check
+mode enabled, nothing gets changed, but the diff of what WOULD be
+changed is printed.
 
 As a possible way to go, start Ansible with diff and checkmode:
 
 ::
 
-  ansible-playbook -i hosts --diff --check site.yml
+  ansible-playbook playbook.yml --diff --check
 
-If you think the changes do what you intend to do, you can start Ansible without the checkmode:
+If you think the changes do what you intend to do, you can start
+Ansible without check mode:
 
 ::
 
-  ansible-playbook -i hosts --diff site.yml
-
-
-Special Roles
-=============
-
-If you need new roles, which aren't created yet, create them and make a
-pull-requests to the `ansible-roles`_ repository. Only generic roles will
-be accepted. Follow the guidelines for new roles.
+  ansible-playbook playbook.yml --diff
 
-To create special roles for one project (e.g. not possible as a generic
-role or never needed in another project) put them inside the directory
-``roles/``. Each role in this directory will override roles in the directory
-``adfinis-roles/``.
 
+Write Roles & Collections
+=========================
 
-.. _ansible-roles: https://github.com/adfinis/ansible-roles
+You will most likely run into a situation where existing roles and
+collections don't match your needs rather quickly.
 
+Under :ref:`roles_collections:Roles & Collections` we provide a
+guide and best practices for writing new roles and collections.
 
 .. vim: set spell spelllang=en foldmethod=marker sw=2 ts=2 et wrap tw=76 :

doc/index.rst

@@ -9,7 +9,5 @@ Ansible Guide
 
    overview.rst
    getting_started.rst
+   roles_collections.rst
    styling_guide.rst
-   roles.rst
-   test_infrastructure.rst
-   role_overview.rst