docs: add automated doc generation

document argument_specs

.ansible-lint

@@ -0,0 +1,27 @@
+# .ansible-lint
+exclude_paths:
+  - .cache/
+  - .github/
+  - molecule/
+  - .ansible-lint
+  - .yamllint
+
+rulesdir:
+   - ../../ansible-lint-custom-rules/rules/
+
+enable_list:
+  - fqcn-builtins  # opt-in
+  - no-log-password  # opt-in
+
+warn_list:
+  - role_vars_start_with_role_name
+  - vars_in_vars_files_have_valid_names
+  - vars_should_not_be_used
+  - experimental
+  - ignore-errors
+  - no-handler
+  - fqcn-builtins
+  - no-log-password
+
+use_default_rules: true
+parseable: true

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,48 @@
+---
+name: 🐛 Bug report
+about: Create a report to help us improve
+
+---
+
+##### SUMMARY
+<!-- Explain the problem briefly -->
+
+
+##### ISSUE TYPE
+ - Bug Report
+
+
+##### ANSIBLE VERSION
+<!-- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version"-->
+```
+
+```
+
+##### COLLECTION VERSION
+<!-- Paste, BELOW THIS COMMENT, verbatim output from "ansible-galaxy collection list"-->
+<!-- If using virtual environments or execution environments, remember to activate them-->
+```
+
+```
+
+##### STEPS TO REPRODUCE
+<!-- List the steps to reproduce the problem, using a minimal test-case. -->
+
+<!-- Paste example playbook below -->
+```yaml
+
+```
+
+##### EXPECTED RESULTS
+<!-- What did you expect to happen when running the steps above? -->
+
+
+##### ACTUAL RESULTS
+<!-- What actually happened? If possible run with extra verbosity (-vvvv) and diff (--diff) -->
+<!-- Please also include check mode (--check --diff) output if the API returns an error -->
+<!-- Be sure to mask any sensitive information -->
+
+<!--- Paste verbatim command output between quotes below -->
+```
+
+```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,12 @@
+---
+name: ✨ Feature request
+about: Suggest an idea for this project
+
+---
+
+##### SUMMARY
+<!--- Explain the problem briefly -->
+
+
+##### ISSUE TYPE
+ - Feature Idea

.github/workflows/ci.yml

@@ -29,6 +29,12 @@ jobs:
           pip install yamllint 'molecule[docker]~=3.5.2' ansible-core flake8 ansible-lint voluptuous
           pip install -r ansible_collections/middleware_automation/keycloak/requirements.txt
 
+      - name: Install ansible-lint custom rules
+        uses: actions/checkout@v2
+        with:
+          repository: ansible-middleware/ansible-lint-custom-rules
+          path: ansible_collections/ansible-lint-custom-rules/
+
       - name: Create default collection path
         run: |
           mkdir -p /home/runner/.ansible/collections/ansible_collections

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+---
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "*.*.*"
+
+env:
+  COLORTERM: 'yes'
+  TERM: 'xterm-256color'
+  PYTEST_ADDOPTS: '--color=yes'
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    if: github.repository == 'ansible-middleware/keycloak'
+    permissions:
+      actions: write
+      checks: write
+      contents: write
+      deployments: write
+      packages: write
+      pages: write
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v2
+        with:
+          path: ansible_collections/middleware_automation/keycloak
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Install doc dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r ansible_collections/middleware_automation/keycloak/docs/requirements.txt
+          pip install -r ansible_collections/middleware_automation/keycloak/requirements.txt
+
+      - name: Create default collection path
+        run: |
+          mkdir -p /home/runner/.ansible/collections/ansible_collections
+
+      - name: Create doc directories and resources
+        run: |
+          mkdir -p ./docs/plugins ./docs/roles
+          cat ./docs/roles.rst.template > ./docs/roles/index.rst
+          antsibull-docs collection --use-current --squash-hierarchy --dest-dir docs/plugins  middleware_automation.keycloak
+          for role_readme in roles/*/README.md; do ln -f -s ../../$role_readme ./docs/roles/$(basename $(dirname $role_readme)).md; echo " * :doc:\`$(basename $(dirname $role_readme))\`" >> ./docs/roles/index.rst; done
+        working-directory: ansible_collections/middleware_automation/keycloak
+
+      - name: Run sphinx
+        run: |
+          sphinx-build -M html . _build -v
+        working-directory: ansible_collections/middleware_automation/keycloak/docs/
+
+      - name: Commit docs
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          git checkout gh-pages
+          rm -rf $(basename ${GITHUB_REF})
+          mv docs/_build/html $(basename ${GITHUB_REF})
+          ln --force --no-dereference --symbolic   main latest
+          git show origin/main:docs/_gh_include/header.inc > index.html
+          (echo main; echo latest; dirname *.*.*/index.html | sort --version-sort --reverse) | xargs -I@@ -n1 echo '<li class="toctree-l1"><a class="reference internal" href="@@/">@@</a></li>' >> index.html
+          git show origin/main:docs/_gh_include/footer.inc >> index.html
+          git add $(basename ${GITHUB_REF}) latest index.html
+          git commit -m "Update docs for $(basename ${GITHUB_REF})" || true
+          git push origin gh-pages
+        working-directory: ansible_collections/middleware_automation/keycloak/

.gitignore

@@ -1,2 +1,10 @@
 *.tar.gz
 *.zip
+.tmp
+.cache
+docs/plugins/
+docs/roles/
+docs/_build/
+.pytest_cache/
+.mypy_cache/
+*.retry

CONTRIBUTING.md

@@ -5,10 +5,10 @@
 - Use spaces around jinja variables. `{{ var }}` over `{{var}}`
 - Variables that are internal to the role should be lowercase and start with the role name
 - Keep roles self contained - Roles should avoid including tasks from other roles when possible
-- Plays should do nothing more than include a list of roles except where `pre_tasks` and `post_tasks` are required when possible
-- Separators - Use valid name, ie. underscores (e.g. `my_role` `my_playbook`) not dashes (`my-role`)
-- Paths - When defining paths, do not include trailing slashes (e.g. `my_path: /foo` not `my_path: /foo/`). When concatenating paths, follow the same convention (e.g. `{{ my_path }}/bar` not `{{ my_path }}bar`)
+- Plays should do nothing more than include a list of roles, except where `pre_tasks` and `post_tasks` are required, when possible
+- Separators - Use valid names, ie. underscores (e.g. `my_role` `my_playbook`) not dashes (`my-role`)
+- Paths - When defining paths, do not include trailing slashes (e.g. `my_path: /foo` not `my_path: /foo/`); when concatenating paths, follow the same convention (e.g. `{{ my_path }}/bar` not `{{ my_path }}bar`)
 - Indentation - Use 2 spaces for each indent
 - `vars/` vs `defaults/` - internal or interpolated variables that don't need to change or be overridden by user go in `vars/`, those that a user would likely override, go under `defaults/` directory
-- All arguments have a specification in `meta/argument_specs.yml`
+- All role arguments have a specification in `meta/argument_specs.yml`
 - All playbooks/roles should be focused on compatibility with Ansible Tower

README.md

@@ -1,4 +1,4 @@
-# Ansible Collection - keycloak
+# Ansible Collection - middleware_automation.keycloak
 
 [![Build Status](https://github.com/ansible-middleware/keycloak/workflows/CI/badge.svg?branch=main)](https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml)
 
@@ -13,6 +13,7 @@ This collection has been tested against following Ansible versions: **>=2.9.10**
 Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions.
 <!--end requires_ansible-->
 
+
 ## Installation
 
 ### Installing the Collection from Ansible Galaxy
@@ -54,12 +55,12 @@ A requirement file is provided to install:
 
 Both playbooks include the `keycloak` role, with different settings, as described in the following sections.
 
-For service configuration details, refer to the [keycloak role README](roles/keycloak/README.md).
+For full service configuration details, refer to the [keycloak role README](roles/keycloak/README.md).
 
 
 ### Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO)
 
-The general flag `keycloak_rhsso_enable` controls what to install between upstream(Keycloak, when `False`) or Red Hat Single Sign-On (when `True`).
+The general flag `keycloak_rhsso_enable` controls what to install between upstream (Keycloak, when `False`) or Red Hat Single Sign-On (when `True`).
 The default value for the flag if `True` when Red Hat Network credentials are defined, `False` otherwise.
 
 
@@ -133,15 +134,15 @@ ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e
 
 ### Config Playbook
 
-[`playbooks/keycloak-realm.yml`](playbooks/keycloak-realm.yml) creates provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist.
+[`playbooks/keycloak_realm.yml`](playbooks/keycloak_realm.yml) creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s).
 
 
 ### Example configuration command
 
-Execute the following command from the source root directory
+Execute the following command from the source root directory:
 
 ```bash
-ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test
+ansible-playbook -i <ansible_hosts> playbooks/keycloak_realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test
 ```
 
 - `keycloak_admin_password` password for the administration console user account.
@@ -153,7 +154,7 @@ ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_adm
   localhost ansible_connection=local
   ```
 
-For configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md).
+For full configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md).
 
 
 ## License

docs/README.md

@@ -0,0 +1 @@
+../README.md

docs/_gh_include/footer.inc

@@ -0,0 +1,21 @@
+              </ul>
+            </div>
+          </section>
+        </div>
+      </div>
+      <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
+      </div>
+      <hr/>
+      <div role="contentinfo">
+        <p>&#169; Copyright 2022, Red Hat, Inc..</p>
+      </div>
+      Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+        <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+        provided by <a href="https://readthedocs.org">Read the Docs</a>.
+      </footer>
+    </div>
+  </div>
+</section>
+</div>
+</body>
+</html>

docs/_gh_include/header.inc

@@ -0,0 +1,43 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Keycloak Ansible Collection documentation index</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="https://ansible-middleware.github.io/keycloak/main/_static/pygments.css" type="text/css" />
+    <link rel="stylesheet" href="https://ansible-middleware.github.io/keycloak/main/_static/css/theme.css" type="text/css" />
+    <link rel="stylesheet" href="https://ansible-middleware.github.io/keycloak/main/_static/ansible-basic-sphinx-ext.css" type="text/css" />
+    <script data-url_root="./" id="documentation_options" src="https://ansible-middleware.github.io/keycloak/main/_static/documentation_options.js"></script>
+    <script src="https://ansible-middleware.github.io/keycloak/main/_static/jquery.js"></script>
+    <script src="https://ansible-middleware.github.io/keycloak/main/_static/underscore.js"></script>
+    <script src="https://ansible-middleware.github.io/keycloak/main/_static/doctools.js"></script>
+    <script src="https://ansible-middleware.github.io/keycloak/main/_static/js/theme.js"></script>
+  </head>
+
+<body class="wy-body-for-nav">
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search" >
+            <a href="#" class="icon icon-home"> Keycloak Ansible Collection</a>
+        </div>
+      </div>
+    </nav>
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+      <div class="wy-nav-content">
+          <div class="rst-content">
+            <div role="navigation" aria-label="Page navigation">
+              <ul class="wy-breadcrumbs">
+                  <li><a href="#" class="icon icon-home"></a> &raquo;</li>
+                  <li>Welcome to Keycloak Collection documentation</li>
+                  <li class="wy-breadcrumbs-aside"></li>
+              </ul>
+              <hr/>
+            </div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+             <div itemprop="articleBody">
+                <section id="welcome-to-keycloak-collection-documentation">
+                  <h1>Welcome to Keycloak Collection documentation<a class="headerlink" href="#welcome-to-keycloak-collection-documentation" title="Permalink to this headline"></a></h1>
+                    <div class="toctree-wrapper compound">
+                      <p class="caption" role="heading"><span class="caption-text">Pick collection version:</span></p>
+                        <ul>

docs/conf.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import datetime
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../plugins/module_utils/'))
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'Keycloak Ansible Collection'
+copyright = '{y}, Red Hat, Inc.'.format(y=datetime.date.today().year)
+author = 'Red Hat, Inc.'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'ansible_basic_sphinx_ext',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# 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
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.tmp']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+highlight_language = 'YAML+Jinja'
+
+# -- Options for HTML output -------------------------------------------------
+html_theme_path = ['_themes']
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'KeycloakCollectionDoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'KeycloakCollection.tex', 'Red Hat Single Sign-On Ansible Collection Documentation',
+     'Red Hat, Inc.', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'keycloakcollection', 'Red Hat Single Sign-On Ansible Collection Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'KeycloakCollection', 'Red Hat Single Sign-On Ansible Collection Documentation',
+     author, 'KeycloakCollection', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'python': ('https://docs.python.org/2', None), 'ansible': ('https://docs.ansible.com/ansible/latest/', None)}

docs/developing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/index.rst

@@ -0,0 +1,32 @@
+.. Red Hat middleware_automation Keycloak Ansible Collection documentation main file
+
+Welcome to Keycloak Collection documentation
+============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User documentation
+
+   README
+   plugins/index
+   roles/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer documentation
+
+   developing
+   testing
+   releasing
+
+.. toctree::
+   :maxdepth: 2
+   :caption: General
+
+   Changelog <CHANGELOG>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,5 @@
+antsibull>=0.17.0
+ansible-base>=2.10.12
+sphinx-rtd-theme
+git+https://github.com/felixfontein/ansible-basic-sphinx-ext
+myst-parser

docs/roles.rst.template

@@ -0,0 +1,3 @@
+Role Index
+==========
+

galaxy.yml

@@ -1,6 +1,6 @@
 namespace: middleware_automation
 name: keycloak
-version: "0.2.3"
+version: "0.2.5"
 readme: README.md
 authors:
   - Romain Pelisse <rpelisse@redhat.com>
@@ -14,10 +14,14 @@ tags:
   - rhel
   - rhn
   - sso
+  - single sign-on
+  - security
+  - infrastructure
+  - authentication
 dependencies:
   "middleware_automation.redhat_csp_download": ">=1.2.1"
-  "middleware_automation.wildfly": ">=0.0.4"
+  "middleware_automation.wildfly": ">=0.0.6"
 repository: https://github.com/ansible-middleware/keycloak
-documentation: https://github.com/ansible-middleware/keycloak
+documentation: https://ansible-middleware.github.io/keycloak
 homepage: https://github.com/ansible-middleware/keycloak
 issues: https://github.com/ansible-middleware/keycloak/issues

molecule/default/molecule.yml

@@ -4,6 +4,9 @@ dependency:
   command: ansible-galaxy collection install -r molecule/default/requirements.yml -p $HOME/.ansible/collections --force-with-deps
 driver:
   name: docker
+lint: |
+  ansible-lint --version
+  ansible-lint -v
 platforms:
   - name: instance
     image: registry.access.redhat.com/ubi8/ubi-init:latest

roles/keycloak/README.md

@@ -69,6 +69,29 @@ Role Defaults
 |`keycloak_version`| keycloak.org package version | `15.0.2` |
 |`keycloak_rhsso_version`| RHSSO version | `7.5.0` |
 |`keycloak_dest`| Installation root path | `/opt/keycloak` |
+|`keycloak_download_url` | Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/{{ keycloak_version }}/{{ keycloak_archive }}` |
+|`keycloak_rhn_url` | Base download URI for customer portal | `https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId=` |
+
+
+* Miscellaneous configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_archive` | keycloak install archive filename | `keycloak-{{ keycloak_version }}.zip` |
+|`keycloak_download_url_9x` | Download URL for keycloak (deprecated) | `https://downloads.jboss.org/keycloak/{{ keycloak_version }}/{{ keycloak_archive }}` |
+|`keycloak_installdir` | Installation path | `{{ keycloak_dest }}/keycloak-{{ keycloak_version }}` |
+|`keycloak_rhsso_archive` | Red Hat SSO install archive filename | `rh-sso-{{ keycloak_rhsso_version }}-server-dist.zip` |
+|`keycloak_rhsso_installdir`| Installation path for Red Hat SSO | `{{ keycloak_dest }}/rh-sso-{{ keycloak_rhsso_version | regex_replace('^([0-9])\.([0-9]*).*', '\1.\2') }}` |
+|`keycloak_rhsso_download_url`| Full download URI for Red Hat SSO | `{{ keycloak_rhn_url }}{{ rhsso_rhn_id }}` |
+|`keycloak_jboss_home` | Installation work directory | `{{ keycloak_rhsso_installdir if keycloak_rhsso_enable else keycloak_installdir }}` |
+|`keycloak_config_dir` | Path for configuration | `{{ keycloak_jboss_home }}/standalone/configuration` |
+|`keycloak_config_path_to_standalone_xml` | Custom path for configuration | `{{ keycloak_jboss_home }}/standalone/configuration/{{ keycloak_config_standalone_xml }}` |
+|`keycloak_auth_realm` | Name for rest authentication realm | `master` |
+|`keycloak_auth_client` | Authentication client for configuration REST calls | `admin-cli` |
+|`keycloak_force_install` | Remove pre-existing versions of service | `False` |
+|`keycloak_url` | URL for configuration rest calls | `http://{{ keycloak_host }}:{{ keycloak_http_port }}` |
+|`keycloak_management_url` | URL for management console rest calls | `http://{{ keycloak_host }}:{{ keycloak_management_http_port }}` |
+|`rhsso_rhn_id` | Customer Portal product ID for Red Hat SSO | `{{ rhsso_rhn_ids[keycloak_rhsso_version] }}` |
 
 
 Role Variables

roles/keycloak/meta/argument_specs.yml

@@ -4,162 +4,162 @@ argument_specs:
             keycloak_version:
                 # line 3 of keycloak/defaults/main.yml
                 default: "15.0.2"
-                description: "TODO document argument"
+                description: "keycloak.org package version"
                 type: "str"
             keycloak_archive:
                 # line 4 of keycloak/defaults/main.yml
                 default: "keycloak-{{ keycloak_version }}.zip"
-                description: "TODO document argument"
+                description: "keycloak install archive filename"
                 type: "str"
             keycloak_download_url:
                 # line 5 of keycloak/defaults/main.yml
                 default: "https://github.com/keycloak/keycloak/releases/download/{{ keycloak_version }}/{{ keycloak_archive }}"
-                description: "TODO document argument"
+                description: "Download URL for keycloak"
                 type: "str"
             keycloak_download_url_9x:
                 # line 6 of keycloak/defaults/main.yml
                 default: "https://downloads.jboss.org/keycloak/{{ keycloak_version }}/{{ keycloak_archive }}"
-                description: "TODO document argument"
+                description: "Download URL for keycloak (deprecated)"
                 type: "str"
             keycloak_installdir:
                 # line 7 of keycloak/defaults/main.yml
                 default: "{{ keycloak_dest }}/keycloak-{{ keycloak_version }}"
-                description: "TODO document argument"
+                description: "Installation path"
                 type: "str"
             keycloak_rhsso_version:
                 # line 10 of keycloak/defaults/main.yml
                 default: "7.5.0"
-                description: "TODO document argument"
+                description: "Red Hat Single Sign-On version"
                 type: "str"
             rhsso_rhn_id:
                 # line 11 of keycloak/defaults/main.yml
                 default: "{{ rhsso_rhn_ids[keycloak_rhsso_version] }}"
-                description: "TODO document argument"
+                description: "Customer Portal product ID for Red Hat SSO"
                 type: "str"
             keycloak_rhsso_archive:
                 # line 12 of keycloak/defaults/main.yml
                 default: "rh-sso-{{ keycloak_rhsso_version }}-server-dist.zip"
-                description: "TODO document argument"
+                description: "ed Hat SSO install archive filename"
                 type: "str"
             keycloak_rhsso_installdir:
                 # line 13 of keycloak/defaults/main.yml
                 default: "{{ keycloak_dest }}/rh-sso-{{ keycloak_rhsso_version | regex_replace('^([0-9])\\.([0-9]*).*', '\\1.\\2') }}"
-                description: "TODO document argument"
+                description: "Installation path for Red Hat SSO"
                 type: "str"
             keycloak_rhn_url:
                 # line 14 of keycloak/defaults/main.yml
                 default: "https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId="
-                description: "TODO document argument"
+                description: "Base download URI for customer portal"
                 type: "str"
             keycloak_rhsso_download_url:
                 # line 15 of keycloak/defaults/main.yml
                 default: "{{ keycloak_rhn_url }}{{ rhsso_rhn_id }}"
-                description: "TODO document argument"
+                description: "Full download URI for Red Hat SSO"
                 type: "str"
             keycloak_rhsso_enable:
                 # line 18 of keycloak/defaults/main.yml
                 default: "{{ True if rhsso_rhn_id is defined and rhn_username is defined and rhn_password is defined else False }}"
-                description: "TODO document argument"
+                description: "Enable Red Hat Single Sign-on installation"
                 type: "str"
             keycloak_offline_install:
                 # line 20 of keycloak/defaults/main.yml
                 default: false
-                description: "TODO document argument"
+                description: "Perform an offline install"
                 type: "bool"
             jvm_package:
                 # line 23 of keycloak/defaults/main.yml
                 default: "java-1.8.0-openjdk-devel"
-                description: "TODO document argument"
+                description: "RHEL java package runtime rpm"
                 type: "str"
             keycloak_dest:
                 # line 24 of keycloak/defaults/main.yml
                 default: "/opt/keycloak"
-                description: "TODO document argument"
+                description: "Root installation directory"
                 type: "str"
             keycloak_jboss_home:
                 # line 25 of keycloak/defaults/main.yml
                 default: "{{ keycloak_rhsso_installdir if keycloak_rhsso_enable else keycloak_installdir }}"
-                description: "TODO document argument"
+                description: "Installation work directory"
                 type: "str"
             keycloak_config_dir:
                 # line 26 of keycloak/defaults/main.yml
                 default: "{{ keycloak_jboss_home }}/standalone/configuration"
-                description: "TODO document argument"
+                description: "Path for configuration"
                 type: "str"
             keycloak_config_standalone_xml:
                 # line 27 of keycloak/defaults/main.yml
                 default: "keycloak.xml"
-                description: "TODO document argument"
+                description: "Service configuration filename"
                 type: "str"
             keycloak_config_path_to_standalone_xml:
                 # line 28 of keycloak/defaults/main.yml
                 default: "{{ keycloak_jboss_home }}/standalone/configuration/{{ keycloak_config_standalone_xml }}"
-                description: "TODO document argument"
+                description: "Custom path for configuration"
                 type: "str"
             keycloak_service_user:
                 # line 29 of keycloak/defaults/main.yml
                 default: "keycloak"
-                description: "TODO document argument"
+                description: "posix account username"
                 type: "str"
             keycloak_service_group:
                 # line 30 of keycloak/defaults/main.yml
                 default: "keycloak"
-                description: "TODO document argument"
+                description: "posix account group"
                 type: "str"
             keycloak_service_pidfile:
                 # line 31 of keycloak/defaults/main.yml
                 default: "/run/keycloak.pid"
-                description: "TODO document argument"
+                description: "PID file path for service"
                 type: "str"
             keycloak_bind_address:
                 # line 34 of keycloak/defaults/main.yml
                 default: "0.0.0.0"
-                description: "TODO document argument"
+                description: "Address for binding service ports"
                 type: "str"
             keycloak_host:
                 # line 35 of keycloak/defaults/main.yml
                 default: "localhost"
-                description: "TODO document argument"
+                description: "Hostname for service"
                 type: "str"
             keycloak_http_port:
                 # line 36 of keycloak/defaults/main.yml
                 default: 8080
-                description: "TODO document argument"
+                description: "Listening HTTP port"
                 type: "int"
             keycloak_https_port:
                 # line 37 of keycloak/defaults/main.yml
                 default: 8443
-                description: "TODO document argument"
+                description: "Listening HTTPS port"
                 type: "int"
             keycloak_ajp_port:
                 # line 38 of keycloak/defaults/main.yml
                 default: 8009
-                description: "TODO document argument"
+                description: "Listening AJP port"
                 type: "int"
             keycloak_jgroups_port:
                 # line 39 of keycloak/defaults/main.yml
                 default: 7600
-                description: "TODO document argument"
+                description: "jgroups cluster tcp port"
                 type: "int"
             keycloak_management_http_port:
                 # line 40 of keycloak/defaults/main.yml
                 default: 9990
-                description: "TODO document argument"
+                description: "Management port (http)"
                 type: "int"
             keycloak_management_https_port:
                 # line 41 of keycloak/defaults/main.yml
                 default: 9993
-                description: "TODO document argument"
+                description: "Management port (https)"
                 type: "int"
             keycloak_java_opts:
                 # line 42 of keycloak/defaults/main.yml
                 default: "-Xms1024m -Xmx2048m"
-                description: "TODO document argument"
+                description: "Additional JVM options"
                 type: "str"
             keycloak_prefer_ipv4:
                 # line 43 of keycloak/defaults/main.yml
                 default: true
-                description: "TODO document argument"
+                description: "Prefer IPv4 stack and addresses for port binding"
                 type: "bool"
             keycloak_ha_enabled:
                 # line 46 of keycloak/defaults/main.yml
@@ -179,52 +179,52 @@ argument_specs:
             keycloak_auth_realm:
                 # line 52 of keycloak/defaults/main.yml
                 default: "master"
-                description: "TODO document argument"
+                description: "Name for rest authentication realm"
                 type: "str"
             keycloak_auth_client:
                 # line 53 of keycloak/defaults/main.yml
                 default: "admin-cli"
-                description: "TODO document argument"
+                description: "Authentication client for configuration REST calls"
                 type: "str"
             keycloak_force_install:
                 # line 55 of keycloak/defaults/main.yml
                 default: false
-                description: "TODO document argument"
+                description: "Remove pre-existing versions of service"
                 type: "bool"
             keycloak_modcluster_url:
                 # line 58 of keycloak/defaults/main.yml
                 default: "localhost"
-                description: "TODO document argument"
+                description: "URL for the modcluster reverse proxy"
                 type: "str"
             keycloak_frontend_url:
                 # line 59 of keycloak/defaults/main.yml
                 default: "http://localhost"
-                description: "TODO document argument"
+                description: "Frontend URL for keycloak endpoints when a reverse proxy is used"
                 type: "str"
             infinispan_user:
                 # line 62 of keycloak/defaults/main.yml
                 default: "supervisor"
-                description: "TODO document argument"
+                description: "Username for connecting to infinispan"
                 type: "str"
             infinispan_pass:
                 # line 63 of keycloak/defaults/main.yml
                 default: "supervisor"
-                description: "TODO document argument"
+                description: "Password for connecting to infinispan"
                 type: "str"
             infinispan_url:
                 # line 64 of keycloak/defaults/main.yml
                 default: "localhost"
-                description: "TODO document argument"
+                description: "URL for the infinispan remote-cache server"
                 type: "str"
             infinispan_sasl_mechanism:
                 # line 65 of keycloak/defaults/main.yml
                 default: "SCRAM-SHA-512"
-                description: "TODO document argument"
+                description: "Authentication type to infinispan server"
                 type: "str"
             infinispan_use_ssl:
                 # line 66 of keycloak/defaults/main.yml
                 default: false
-                description: "TODO document argument"
+                description: "Enable hotrod client TLS communication"
                 type: "bool"
             infinispan_trust_store_path:
                 # line 68 of keycloak/defaults/main.yml
@@ -234,45 +234,45 @@ argument_specs:
             infinispan_trust_store_password:
                 # line 69 of keycloak/defaults/main.yml
                 default: "changeit"
-                description: "TODO document argument"
+                description: "Path to truststore containing infinispan server certificate"
                 type: "str"
             keycloak_jdbc_engine:
                 # line 72 of keycloak/defaults/main.yml
                 default: "postgres"
-                description: "TODO document argument"
+                description: "Backend database flavour when db is enabled: [ postgres, mariadb ]"
                 type: "str"
             keycloak_db_user:
                 # line 74 of keycloak/defaults/main.yml
                 default: "keycloak-user"
-                description: "TODO document argument"
+                description: "Username for connecting to database"
                 type: "str"
             keycloak_db_pass:
                 # line 75 of keycloak/defaults/main.yml
                 default: "keycloak-pass"
-                description: "TODO document argument"
+                description: "Password for connecting to database"
                 type: "str"
             keycloak_jdbc_url:
                 # line 76 of keycloak/defaults/main.yml
                 default: "{{ keycloak_default_jdbc[keycloak_jdbc_engine].url }}"
-                description: "TODO document argument"
+                description: "URL for connecting to backend database"
                 type: "str"
             keycloak_jdbc_driver_version:
                 # line 77 of keycloak/defaults/main.yml
                 default: "{{ keycloak_default_jdbc[keycloak_jdbc_engine].version }}"
-                description: "TODO document argument"
+                description: "Version for the JDBC driver to download"
                 type: "str"
             keycloak_admin_password:
                 # line 4 of keycloak/vars/main.yml
                 required: true
-                description: "TODO document argument"
+                description: "Password for the administration console user account"
                 type: "str"
             keycloak_url:
                 # line 12 of keycloak/vars/main.yml
                 default: "http://{{ keycloak_host }}:{{ keycloak_http_port }}"
-                description: "TODO document argument"
+                description: "URL for configuration rest calls"
                 type: "str"
             keycloak_management_url:
                 # line 13 of keycloak/vars/main.yml
                 default: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}"
-                description: "TODO document argument"
+                description: "URL for management console rest calls"
                 type: "str"

roles/keycloak/meta/main.yml

@@ -6,7 +6,7 @@ collections:
 galaxy_info:
   role_name: keycloak
   namespace: middleware_automation
-  author: Romain Pelisse, Guido Grazioli
+  author: Romain Pelisse, Guido Grazioli, Pavan Kumar Motaparthi
   description: Install keycloak or Red Hat Single Sing-On server configurations
   company: Red Hat, Inc.
 
@@ -17,7 +17,6 @@ galaxy_info:
   platforms:
    - name: EL
      versions:
-     - 7
      - 8
 
   galaxy_tags:

roles/keycloak/tasks/fastpackages/check.yml

@@ -8,7 +8,7 @@
     changed_when: rpm_info.failed
 
   rescue:
-    - name: "If package {{ package_name }} is missing, add it to the yum install list."
+    - name: "Add {{ package_name }} to the yum install list if missing"
       set_fact:
         packages_to_install: "{{ packages_to_install + [ package_name ] }}"
       when: rpm_info.failed

roles/keycloak/tasks/fastpackages/install.yml

@@ -1,5 +1,6 @@
 ---
-- set_fact:
+- name: Set facts
+  set_fact:
     update_cache: true
     packages_to_install: []
 

roles/keycloak/tasks/install.yml

@@ -63,7 +63,7 @@
   register: archive_path
 
 ## download to controller
-- name: Check load download archive path
+- name: Check local download archive path
   stat:
     path: "{{ lookup('env', 'PWD') }}"
   register: local_path
@@ -81,7 +81,7 @@
     - not keycloak_rhsso_enable
     - not keycloak_offline_install
 
-- name: Performing download from RHN
+- name: Perform download from RHN
   redhat_csp_download:
     url: "{{ keycloak_rhsso_download_url }}"
     dest: "{{ local_path.stat.path }}/{{ keycloak.bundle }}"
@@ -110,6 +110,12 @@
     - not keycloak_offline_install
     - not keycloak_rhn_url in keycloak_rhsso_download_url
 
+- name: Check downloaded archive
+  stat:
+    path: "{{ local_path.stat.path }}/{{ keycloak.bundle }}"
+  register: local_archive_path
+  delegate_to: localhost
+
 ## copy and unpack
 - name: Copy archive to target nodes
   copy:
@@ -119,6 +125,10 @@
     group: "{{ keycloak_service_group }}"
     mode: 0750
   register: new_version_downloaded
+  when:
+    - not archive_path.stat.exists
+    - local_archive_path.stat is defined
+    - local_archive_path.stat.exists
   become: yes
 
 - name: "Check target directory: {{ keycloak.home }}"

roles/keycloak/tasks/main.yml

@@ -1,7 +1,7 @@
 ---
 # tasks file for keycloak
 
-- name: Prerequisites
+- name: Check prerequisites
   include_tasks: prereqs.yml
   tags:
     - prereqs
@@ -38,6 +38,7 @@
           - "-rmaster"
           - "-u{{ keycloak_admin_user }}"
           - "-p{{ keycloak_admin_password }}"
+      changed_when: yes
       become: yes
     - name: "Restart {{ keycloak.service_name }}"
       include_tasks: tasks/restart_keycloak.yml

roles/keycloak/tasks/systemd.yml

@@ -56,7 +56,8 @@
       - keycloak_service_status is defined
       - keycloak_service_status.stdout is defined
 
-- meta: flush_handlers
+- name: Flush handlers
+  meta: flush_handlers
 
 - name: "Wait until Keycloak becomes active {{ keycloak.health_url }}"
   uri:

roles/keycloak_realm/README.md

@@ -9,13 +9,18 @@ Role Defaults
 
 | Variable | Description | Default |
 |:---------|:------------|:---------|
-|`keycloak_admin_user` | Administration console user account | `admin` |
-|`keycloak_host` | hostname | `localhost` |
-|`keycloak_http_port` | HTTP port | `8080` |
-|`keycloak_https_port` | TLS HTTP port | `8443` |
-|`keycloak_auth_realm` | Name of the main authentication realm | `master` |
-|`keycloak_rhsso_enable` | Define service is an upstream(Keycloak) or RHSSO | `master` |
-
+|`keycloak_admin_user`| Administration console user account | `admin` |
+|`keycloak_host`| hostname | `localhost` |
+|`keycloak_http_port`| HTTP port | `8080` |
+|`keycloak_https_port`| TLS HTTP port | `8443` |
+|`keycloak_auth_realm`| Name of the main authentication realm | `master` |
+|`keycloak_rhsso_enable`| Define service is an upstream(Keycloak) or RHSSO | `master` |
+|`keycloak_management_http_port`| Management port | `9990` |
+|`keycloak_auth_client`| Authentication client for configuration REST calls | `admin-cli` |
+|`keycloak_client_public`| Configure a public realm client | `True` |
+|`keycloak_client_web_origins`| Web origins for realm client | `+` |
+|`keycloak_url`| URL for configuration rest calls | `http://{{ keycloak_host }}:{{ keycloak_http_port }}` |
+|`keycloak_management_url`| URL for management console rest calls | `http://{{ keycloak_host }}:{{ keycloak_management_http_port }}` |
 
 
 Role Variables
@@ -37,6 +42,7 @@ The following variables are available for creating clients:
 |`keycloak_client_default_roles` | List of default role name for clients | `[]` |
 |`keycloak_client_users` | List of user/role mappings for a client | `[]` |
 
+
 The following variable are available for creating user federation:
 
 | Variable | Description | Default |
@@ -52,14 +58,15 @@ Variable formats
 ```yaml
     - realm:  <name of the realm in which user federation should be configured, required>
       name: <name of the user federation provider, required>
-      provider_id: <Type of the user federation provider, required>
-      provider_type: < Provider Type, default is set to org.keycloak.storage.UserStorageProvider>
-      config: <Dictionary of supported configuration values, required>
-      mappers: <List of supported configuration values, required>
+      provider_id: <type of the user federation provider, required>
+      provider_type: <Provider Type, default is set to org.keycloak.storage.UserStorageProvider>
+      config: <dictionary of supported configuration values, required>
+      mappers: <list of supported configuration values, required>
 ```
 
 Refer to [docs](https://docs.ansible.com/ansible/latest/collections/community/general/keycloak_user_federation_module.html) for information on supported variables.
 
+
 * `keycloak_clients`, a list of:
 
 ```yaml
@@ -90,7 +97,8 @@ Refer to [docs](https://docs.ansible.com/ansible/latest/collections/community/ge
       realm: <name of the realm>
 ```
 
-For a comprehensive example, refer to the [playbook](playbooks/keycloak.yml).
+For a comprehensive example, refer to the [playbook](../../playbooks/keycloak_realm.yml).
+
 
 Example Playbook
 ----------------

roles/keycloak_realm/defaults/main.yml

@@ -31,6 +31,7 @@ keycloak_auth_client: admin-cli
 #    public_client: "{{ keycloak_client_public }}"
 #    web_origins: "{{ keycloak_client_web_origins }}"
 #    users: "{{ keycloak_client_users }}"
+keycloak_clients: []
 
 # list of roles to create in the client
 keycloak_client_default_roles: []

roles/keycloak_realm/meta/argument_specs.yml

@@ -4,90 +4,90 @@ argument_specs:
             keycloak_host:
                 # line 3 of keycloak_realm/defaults/main.yml
                 default: "localhost"
-                description: "TODO document argument"
+                description: "hostname for rest calls"
                 type: "str"
             keycloak_http_port:
                 # line 4 of keycloak_realm/defaults/main.yml
                 default: 8080
-                description: "TODO document argument"
+                description: "HTTP port"
                 type: "int"
             keycloak_https_port:
                 # line 5 of keycloak_realm/defaults/main.yml
                 default: 8443
-                description: "TODO document argument"
+                description: "HTTPS port"
                 type: "int"
             keycloak_management_http_port:
                 # line 6 of keycloak_realm/defaults/main.yml
                 default: 9990
-                description: "TODO document argument"
+                description: "Management port"
                 type: "int"
             keycloak_rhsso_enable:
                 # line 7 of keycloak_realm/defaults/main.yml
                 default: false
-                description: "TODO document argument"
+                description: "Enable Red Hat Single Sign-on"
                 type: "bool"
             keycloak_admin_user:
                 # line 10 of keycloak_realm/defaults/main.yml
                 default: "admin"
-                description: "TODO document argument"
+                description: "Administration console user account"
                 type: "str"
             keycloak_auth_realm:
                 # line 11 of keycloak_realm/defaults/main.yml
                 default: "master"
-                description: "TODO document argument"
+                description: "Name of the main authentication realm"
                 type: "str"
             keycloak_auth_client:
                 # line 12 of keycloak_realm/defaults/main.yml
                 default: "admin-cli"
-                description: "TODO document argument"
+                description: "Authentication client for configuration REST calls"
                 type: "str"
             keycloak_client_default_roles:
                 # line 36 of keycloak_realm/defaults/main.yml
                 default: "[]"
-                description: "TODO document argument"
+                description: "List of roles to configure as client default"
                 type: "list"
             keycloak_client_public:
                 # line 39 of keycloak_realm/defaults/main.yml
                 default: true
-                description: "TODO document argument"
+                description: "Configure a public realm client"
                 type: "bool"
             keycloak_client_web_origins:
                 # line 42 of keycloak_realm/defaults/main.yml
                 default: "+"
-                description: "TODO document argument"
+                description: "Web origins for realm client"
                 type: "str"
             keycloak_client_users:
                 # line 49 of keycloak_realm/defaults/main.yml
                 default: "[]"
-                description: "TODO document argument"
+                description: "List of users to configure in the realm client"
                 type: "list"
             keycloak_user_federation:
                 # line 52 of keycloak_realm/defaults/main.yml
                 default: "[]"
-                description: "TODO document argument"
+                description: "List of user federations to configure in the realm"
                 type: "list"
             keycloak_admin_password:
                 # line 5 of keycloak_realm/vars/main.yml
                 required: true
-                description: "TODO document argument"
+                description: "Password for the administration console user account"
                 type: "str"
             keycloak_realm:
                 # line 8 of keycloak_realm/vars/main.yml
                 required: true
-                description: "TODO document argument"
+                description: "Name of the realm to be configured"
                 type: "str"
             keycloak_clients:
                 # line 11 of keycloak_realm/vars/main.yml
-                required: true
-                description: "TODO document argument"
-                type: "str"
+                default: "[]"
+                description: "List of client declarations for the realm"
+                type: "list"
             keycloak_url:
                 # line 14 of keycloak_realm/vars/main.yml
                 default: "http://{{ keycloak_host }}:{{ keycloak_http_port }}"
-                description: "TODO document argument"
+                description: "URL for configuration rest calls"
                 type: "str"
             keycloak_management_url:
                 # line 15 of keycloak_realm/vars/main.yml
                 default: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}"
-                description: "TODO document argument"
+                description: "URL for management console rest calls"
                 type: "str"

roles/keycloak_realm/meta/main.yml

@@ -13,7 +13,6 @@ galaxy_info:
   platforms:
    - name: EL
      versions:
-     - 7
      - 8
 
   galaxy_tags:

roles/keycloak_realm/vars/main.yml

@@ -7,9 +7,6 @@ keycloak_admin_password:
 # name of the realm to create, this is a required variable
 keycloak_realm:
 
-# keycloak realm clients, this is a required variable
-keycloak_clients:
-
 # other settings
 keycloak_url: "http://{{ keycloak_host }}:{{ keycloak_http_port }}"
 keycloak_management_url: "http://{{ keycloak_host }}:{{ keycloak_management_http_port }}"