ansible-collections/middleware_automation.keycloak
1
0
Fork 0
mirror of https://github.com/ansible-middleware/keycloak.git synced 2025-04-09 04:10:27 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Update docs for main

Browse source
This commit is contained in:
github-actions 2022-03-11 14:22:00 +00:00
parent 5f85c3967e
commit c35a3d42c6
15 changed files with 477 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
main/README.html
View file

@ -73,6 +73,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

4
main/_sources/developing.md.txt
View file

@ -1,7 +1,7 @@
## Contributor's Guidelines
- All YAML files named with '.yml' extension
- All YAML files named with `.yml` extension
- 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
@ -11,4 +11,4 @@
- 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 role arguments have a specification in `meta/argument_specs.yml`
- All playbooks/roles should be focused on compatibility with Ansible Tower
- All playbooks/roles should be focused on compatibility with Ansible Automation Platform

61
main/_sources/releasing.md.txt Normal file
View file

@ -0,0 +1,61 @@
# Collection Versioning Strategy
Each supported collection maintained by Ansible follows Semantic Versioning 2.0.0 (https://semver.org/), for example:
Given a version number MAJOR.MINOR.PATCH, the following is incremented:
MAJOR version: when making incompatible API changes (see Feature Release scenarios below for examples)
MINOR version: when adding features or functionality in a backwards compatible manner, or updating testing matrix and/or metadata (deprecation)
PATCH version: when adding backwards compatible bug fixes or security fixes (strict).
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
The first version of a generally available supported collection on Ansible Automation Hub shall be version 1.0.0. NOTE: By default, all newly created collections may begin with a smaller default version of 0.1.0, and therefore a version of 1.0.0 should be explicitly stated by the collection maintainer.
## New content is added to an existing collection
Assuming the current release is 1.0.0, and a new module is ready to be added to the collection, the minor version would be incremented to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.
## New feature to existing plugin or role within a collection (backwards compatible)
Assuming the current release is 1.0.0, and new features for an existing module are ready for release . We would increment the MINOR version to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.
## Bug fix or security fix to existing content within a collection
Assuming the current release is 1.0.0 and a bug is fixed prior to the next minor release, the PATCH version would be incremented to 1.0.1. The patch indicates only a bug was fixed within a current version. The PATCH release does not contain new content, nor was functionality removed. Bug fixes may be included in a MINOR or MAJOR feature release if the timing allows, eliminating the need for a PATCH dedicated to the fix.
## Breaking change to any content within a collection
Assuming the current release is 1.0.0, and a breaking change (API or module) is introduced for a user or developer. The MAJOR version would be incremented to 2.0.0.
Examples of breaking changes within a collection may include but are not limited to:
- Argspec changes for a module that require either inventory structure or playbook changes.
- A change in the shape of either the inbound or returned payload of a filter plugin.
- Changes to a connection plugin that require additional inventory parameters or ansible.cfg entries.
- New functionality added to a module that changes the outcome of that module as released in previous versions.
- The removal of plugins from a collection.
## Content removed from a collection
Deleting a module or API is a breaking change. Please see the 'Breaking change' section for how to version this.
## A typographical error was fixed in the documentation for a collection
A correction to the README would be considered a bug fix and the PATCH incremented. See 'Bug fix' above.
## Documentation added/removed/modified within a collection
Only the PATCH version should be increased for a release that contains changes limited to revised documentation.
## Release automation
New releases are triggered by annotated git tags named after semantic versioning. The automation publishes the built artifacts to ansible-galaxy and github releases page.

49
main/_sources/testing.md.txt Normal file
View file

@ -0,0 +1,49 @@
# Testing
## Continuous integration
The collection is tested with a [molecule](https://github.com/ansible-community/molecule) setup covering the included roles and verifying correct installation and idempotency.
In order to run the molecule tests locally with python 3.9 available, after cloning the repository:
```
pip install yamllint 'molecule[docker]~=3.5.2' ansible-core flake8 ansible-lint voluptuous
molecule test --all
```
## Integration testing
Demo repositories which depend on the collection, and aggregate functionality with other middleware_automation collections, are automatically rebuilt
at every collection release to ensure non-breaking changes and consistent behaviour.
The repository are:
- [Flange demo](https://github.com/ansible-middleware/flange-demo)
A deployment of Wildfly cluster integrated with keycloak and infinispan.
- [CrossDC keycloak demo](https://github.com/ansible-middleware/cross-dc-rhsso-demo)
A clustered multi-regional installation of keycloak with infinispan remote caches.
## Test playbooks
Sample playbooks are provided in the `playbooks/` directory; to run the playbooks locally (requires a rhel system with python 3.9+, ansible, and systemd) the steps are as follows:
```
# setup environment
pip install ansible-core
# clone the repository
git clone https://github.com/ansible-middleware/keycloak
cd keycloak
# install collection dependencies
ansible-galaxy collection install -r requirements.yml
# install collection python deps
pip install -r requirements.txt
# create inventory for localhost
cat << EOF > inventory
[keycloak]
localhost ansible_connection=local
EOF
# run the playbook
ansible-playbook -i inventory playbooks/keycloak.yml
```

8
main/developing.html
View file

@ -19,6 +19,7 @@
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Testing" href="testing.html" />
<link rel="prev" title="Role Index" href="roles/index.html" />
</head>
@ -45,6 +46,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>
@ -74,7 +77,7 @@
<section id="contributor-s-guidelines">
<h1>Contributor’s Guidelines<a class="headerlink" href="#contributor-s-guidelines" title="Permalink to this headline"></a></h1>
<ul class="simple">
<li><p>All YAML files named with ‘.yml’ extension</p></li>
<li><p>All YAML files named with <code class="docutils literal notranslate"><span class="pre">.yml</span></code> extension</p></li>
<li><p>Use spaces around jinja variables. <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">var</span> <span class="pre">}}</span></code> over <code class="docutils literal notranslate"><span class="pre">{{var}}</span></code></p></li>
<li><p>Variables that are internal to the role should be lowercase and start with the role name</p></li>
<li><p>Keep roles self contained - Roles should avoid including tasks from other roles when possible</p></li>
@ -84,7 +87,7 @@
<li><p>Indentation - Use 2 spaces for each indent</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vars/</span></code> vs <code class="docutils literal notranslate"><span class="pre">defaults/</span></code> - internal or interpolated variables that don’t need to change or be overridden by user go in <code class="docutils literal notranslate"><span class="pre">vars/</span></code>, those that a user would likely override, go under <code class="docutils literal notranslate"><span class="pre">defaults/</span></code> directory</p></li>
<li><p>All role arguments have a specification in <code class="docutils literal notranslate"><span class="pre">meta/argument_specs.yml</span></code></p></li>
<li><p>All playbooks/roles should be focused on compatibility with Ansible Tower</p></li>
<li><p>All playbooks/roles should be focused on compatibility with Ansible Automation Platform</p></li>
</ul>
</section>
@ -93,6 +96,7 @@
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="roles/index.html" class="btn btn-neutral float-left" title="Role Index" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="testing.html" class="btn btn-neutral float-right" title="Testing" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>

2
main/genindex.html
View file

@ -43,6 +43,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

19
main/index.html
View file

@ -45,6 +45,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>
@ -92,6 +94,23 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="testing.html#continuous-integration">Continuous integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#integration-testing">Integration testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html#test-playbooks">Test playbooks</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a><ul>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#new-content-is-added-to-an-existing-collection">New content is added to an existing collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#new-feature-to-existing-plugin-or-role-within-a-collection-backwards-compatible">New feature to existing plugin or role within a collection (backwards compatible)</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#bug-fix-or-security-fix-to-existing-content-within-a-collection">Bug fix or security fix to existing content within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#breaking-change-to-any-content-within-a-collection">Breaking change to any content within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#content-removed-from-a-collection">Content removed from a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#a-typographical-error-was-fixed-in-the-documentation-for-a-collection">A typographical error was fixed in the documentation for a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#documentation-added-removed-modified-within-a-collection">Documentation added/removed/modified within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="releasing.html#release-automation">Release automation</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound">

BIN
main/objects.inv
View file

Binary file not shown.

167
main/releasing.html Normal file
View file

@ -0,0 +1,167 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Collection Versioning Strategy &mdash; Keycloak Ansible Collection documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/ansible-basic-sphinx-ext.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Testing" href="testing.html" />
</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="index.html" class="icon icon-home"> Keycloak Ansible Collection
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="README.html">Ansible Collection - middleware_automation.keycloak</a></li>
<li class="toctree-l1"><a class="reference internal" href="roles/index.html">Role Index</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Collection Versioning Strategy</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#new-content-is-added-to-an-existing-collection">New content is added to an existing collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#new-feature-to-existing-plugin-or-role-within-a-collection-backwards-compatible">New feature to existing plugin or role within a collection (backwards compatible)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#bug-fix-or-security-fix-to-existing-content-within-a-collection">Bug fix or security fix to existing content within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#breaking-change-to-any-content-within-a-collection">Breaking change to any content within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#content-removed-from-a-collection">Content removed from a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#a-typographical-error-was-fixed-in-the-documentation-for-a-collection">A typographical error was fixed in the documentation for a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#documentation-added-removed-modified-within-a-collection">Documentation added/removed/modified within a collection</a></li>
<li class="toctree-l2"><a class="reference internal" href="#release-automation">Release automation</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Keycloak Ansible Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
<li>Collection Versioning Strategy</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/releasing.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="collection-versioning-strategy">
<h1>Collection Versioning Strategy<a class="headerlink" href="#collection-versioning-strategy" title="Permalink to this headline"></a></h1>
<p>Each supported collection maintained by Ansible follows Semantic Versioning 2.0.0 (https://semver.org/), for example:
Given a version number MAJOR.MINOR.PATCH, the following is incremented:</p>
<p>MAJOR version: when making incompatible API changes (see Feature Release scenarios below for examples)</p>
<p>MINOR version: when adding features or functionality in a backwards compatible manner, or updating testing matrix and/or metadata (deprecation)</p>
<p>PATCH version: when adding backwards compatible bug fixes or security fixes (strict).</p>
<p>Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.</p>
<p>The first version of a generally available supported collection on Ansible Automation Hub shall be version 1.0.0. NOTE: By default, all newly created collections may begin with a smaller default version of 0.1.0, and therefore a version of 1.0.0 should be explicitly stated by the collection maintainer.</p>
<section id="new-content-is-added-to-an-existing-collection">
<h2>New content is added to an existing collection<a class="headerlink" href="#new-content-is-added-to-an-existing-collection" title="Permalink to this headline"></a></h2>
<p>Assuming the current release is 1.0.0, and a new module is ready to be added to the collection, the minor version would be incremented to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.</p>
</section>
<section id="new-feature-to-existing-plugin-or-role-within-a-collection-backwards-compatible">
<h2>New feature to existing plugin or role within a collection (backwards compatible)<a class="headerlink" href="#new-feature-to-existing-plugin-or-role-within-a-collection-backwards-compatible" title="Permalink to this headline"></a></h2>
<p>Assuming the current release is 1.0.0, and new features for an existing module are ready for release . We would increment the MINOR version to 1.1.0. The change in the MINOR version indicates an additive change was made while maintaining backward compatibility for existing content within the collection.</p>
</section>
<section id="bug-fix-or-security-fix-to-existing-content-within-a-collection">
<h2>Bug fix or security fix to existing content within a collection<a class="headerlink" href="#bug-fix-or-security-fix-to-existing-content-within-a-collection" title="Permalink to this headline"></a></h2>
<p>Assuming the current release is 1.0.0 and a bug is fixed prior to the next minor release, the PATCH version would be incremented to 1.0.1. The patch indicates only a bug was fixed within a current version. The PATCH release does not contain new content, nor was functionality removed. Bug fixes may be included in a MINOR or MAJOR feature release if the timing allows, eliminating the need for a PATCH dedicated to the fix.</p>
</section>
<section id="breaking-change-to-any-content-within-a-collection">
<h2>Breaking change to any content within a collection<a class="headerlink" href="#breaking-change-to-any-content-within-a-collection" title="Permalink to this headline"></a></h2>
<p>Assuming the current release is 1.0.0, and a breaking change (API or module) is introduced for a user or developer. The MAJOR version would be incremented to 2.0.0.</p>
<p>Examples of breaking changes within a collection may include but are not limited to:</p>
<ul class="simple">
<li><p>Argspec changes for a module that require either inventory structure or playbook changes.</p></li>
<li><p>A change in the shape of either the inbound or returned payload of a filter plugin.</p></li>
<li><p>Changes to a connection plugin that require additional inventory parameters or ansible.cfg entries.</p></li>
<li><p>New functionality added to a module that changes the outcome of that module as released in previous versions.</p></li>
<li><p>The removal of plugins from a collection.</p></li>
</ul>
</section>
<section id="content-removed-from-a-collection">
<h2>Content removed from a collection<a class="headerlink" href="#content-removed-from-a-collection" title="Permalink to this headline"></a></h2>
<p>Deleting a module or API is a breaking change. Please see the ‘Breaking change’ section for how to version this.</p>
</section>
<section id="a-typographical-error-was-fixed-in-the-documentation-for-a-collection">
<h2>A typographical error was fixed in the documentation for a collection<a class="headerlink" href="#a-typographical-error-was-fixed-in-the-documentation-for-a-collection" title="Permalink to this headline"></a></h2>
<p>A correction to the README would be considered a bug fix and the PATCH incremented. See ‘Bug fix’ above.</p>
</section>
<section id="documentation-added-removed-modified-within-a-collection">
<h2>Documentation added/removed/modified within a collection<a class="headerlink" href="#documentation-added-removed-modified-within-a-collection" title="Permalink to this headline"></a></h2>
<p>Only the PATCH version should be increased for a release that contains changes limited to revised documentation.</p>
</section>
<section id="release-automation">
<h2>Release automation<a class="headerlink" href="#release-automation" title="Permalink to this headline"></a></h2>
<p>New releases are triggered by annotated git tags named after semantic versioning. The automation publishes the built artifacts to ansible-galaxy and github releases page.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="testing.html" class="btn btn-neutral float-left" title="Testing" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</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>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>

2
main/roles/index.html
View file

@ -46,6 +46,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

2
main/roles/keycloak.html
View file

@ -44,6 +44,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

2
main/roles/keycloak_realm.html
View file

@ -44,6 +44,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

2
main/search.html
View file

@ -46,6 +46,8 @@
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>

2
main/searchindex.js
View file

File diff suppressed because one or more lines are too long

160
main/testing.html Normal file
View file

@ -0,0 +1,160 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Testing &mdash; Keycloak Ansible Collection documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/ansible-basic-sphinx-ext.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Collection Versioning Strategy" href="releasing.html" />
<link rel="prev" title="Contributor’s Guidelines" href="developing.html" />
</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="index.html" class="icon icon-home"> Keycloak Ansible Collection
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="README.html">Ansible Collection - middleware_automation.keycloak</a></li>
<li class="toctree-l1"><a class="reference internal" href="roles/index.html">Role Index</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer documentation</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="developing.html">Contributor’s Guidelines</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#continuous-integration">Continuous integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="#integration-testing">Integration testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#test-playbooks">Test playbooks</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="releasing.html">Collection Versioning Strategy</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Keycloak Ansible Collection</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
<li>Testing</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/testing.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="testing">
<h1>Testing<a class="headerlink" href="#testing" title="Permalink to this headline"></a></h1>
<section id="continuous-integration">
<h2>Continuous integration<a class="headerlink" href="#continuous-integration" title="Permalink to this headline"></a></h2>
<p>The collection is tested with a <a class="reference external" href="https://github.com/ansible-community/molecule">molecule</a> setup covering the included roles and verifying correct installation and idempotency.
In order to run the molecule tests locally with python 3.9 available, after cloning the repository:</p>
<div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">pip install yamllint &#39;molecule[docker]~=3.5.2&#39; ansible-core flake8 ansible-lint voluptuous</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">molecule test --all</span><span class="w"></span>
</pre></div>
</div>
</section>
<section id="integration-testing">
<h2>Integration testing<a class="headerlink" href="#integration-testing" title="Permalink to this headline"></a></h2>
<p>Demo repositories which depend on the collection, and aggregate functionality with other middleware_automation collections, are automatically rebuilt
at every collection release to ensure non-breaking changes and consistent behaviour.</p>
<p>The repository are:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/ansible-middleware/flange-demo">Flange demo</a>
A deployment of Wildfly cluster integrated with keycloak and infinispan.</p></li>
<li><p><a class="reference external" href="https://github.com/ansible-middleware/cross-dc-rhsso-demo">CrossDC keycloak demo</a>
A clustered multi-regional installation of keycloak with infinispan remote caches.</p></li>
</ul>
</section>
<section id="test-playbooks">
<h2>Test playbooks<a class="headerlink" href="#test-playbooks" title="Permalink to this headline"></a></h2>
<p>Sample playbooks are provided in the <code class="docutils literal notranslate"><span class="pre">playbooks/</span></code> directory; to run the playbooks locally (requires a rhel system with python 3.9+, ansible, and systemd) the steps are as follows:</p>
<div class="highlight-YAML+Jinja notranslate"><div class="highlight"><pre><span></span><span class="c1"># setup environment</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">pip install ansible-core</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain"># clone the repository</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">git clone https://github.com/ansible-middleware/keycloak</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">cd keycloak</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain"># install collection dependencies</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">ansible-galaxy collection install -r requirements.yml</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain"># install collection python deps</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">pip install -r requirements.txt</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain"># create inventory for localhost</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">cat &lt;&lt; EOF &gt; inventory</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">[keycloak]</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">localhost ansible_connection=local</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">EOF</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain"># run the playbook</span><span class="w"></span>
<span class="l l-Scalar l-Scalar-Plain">ansible-playbook -i inventory playbooks/keycloak.yml</span><span class="w"></span>
</pre></div>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="developing.html" class="btn btn-neutral float-left" title="Contributor’s Guidelines" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="releasing.html" class="btn btn-neutral float-right" title="Collection Versioning Strategy" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</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>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>