From dbad4ea086388ceead630bcd5eb5e06401cd91e2 Mon Sep 17 00:00:00 2001 From: Guido Grazioli Date: Thu, 27 Jan 2022 16:34:06 +0100 Subject: [PATCH] Update documentation --- README.md | 78 +++++++++++++++++++----------- roles/keycloak/README.md | 102 ++++++++++++++++++++++----------------- 2 files changed, 106 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 616fe87..caafef7 100644 --- a/README.md +++ b/README.md @@ -46,56 +46,70 @@ A requirement file is provided to install: ## Usage + ### Install Playbook -`playbooks/keycloak.yml` installs the upstream(Keycloak) based on the defined variables. -`playbooks/rhsso.yml` installs Red Hat Single Sign-On(RHSSO) based on defined variables. +* [`playbooks/keycloak.yml`](playbooks/keycloak.yml) installs the upstream(Keycloak) based on the defined variables. +* [`playbooks/rhsso.yml`](playbooks/rhsso.yml) installs Red Hat Single Sign-On(RHSSO) based on defined variables. -### Choosing between upstream(Keycloak) project and Red Hat Single Sign-On(RHSSO) +Both playbooks include the `keycloak` role, with different settings, as described in the following sections. -The roles supports installing upstream(Keycloak) or Red Hat Single Sign-On in the following ways +For service configuration details, refer to the [keycloak role README](roles/keycloak/README.md). -#### Install upstream(Keycloak) from remote source -This is default approach, there is one required variable +### Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO) -``` -keycloak_admin_password: "" -``` +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. -#### Install upstream(Keycloak) from local source when the following variable is defined -``` -keycloak_admin_password: "" -zip_file_local_path: -``` +#### Install upstream (Keycloak) from keycloak releases -#### Install RHSSO from the Red Hat Customer Support Portal, when the following variables are defined +This is the default approach when RHN credentials are not defined. Keycloak is downloaded from keycloak builds (hosted on github.com) locally, and distributed to target nodes. -``` -keycloak_admin_password: "" + +#### Install RHSSO from the Red Hat Customer Support Portal + +Define the credentials as follows, and the default behaviour is to download a fresh archive of RHSSO on the controller node, then distribute to target nodes. + +```yaml rhn_username: '' rhn_password: '' -rhsso_rhn_id: '' +# (keycloak_rhsso_enable defaults to True) ``` -where `sso_product_id` is the ID for the specific Red Hat Single Sign-On version, ie. _101971_ will install version _7.5_) -#### Install RHSSO from remote sources like Nexus etc, when the following variables are defined +#### Install from controller node (local source) +Making the keycloak zip archive (or the RHSSO zip archive), available to the playbook repository root directory, and setting `keycloak_offline_install` to `True`, allows to skip +the download tasks. The local path for the archive matches the downloaded archive path, so it is also used as a cache when multiple hosts are provisioned in a cluster. + +```yaml +keycloak_offline_install: True ``` -keycloak_admin_password: "" + +And depending on `keycloak_rhsso_enable`: + +* `True`: install RHSSO using file rh-sso-x.y.z-server-dist.zip +* `False`: install keycloak using file keycloak-x.y.zip + + +#### Install from alternate sources (like corporate Nexus, artifactory, proxy, etc) + +For RHSSO: + +```yaml keycloak_rhsso_enable: True -rhsso_source_download_url: '' +keycloak_rhsso_download_url: "https://///rh-sso-x.y.z-server-dist.zip" ``` -#### Install RHSSO from local source when the following variable is defined +For keycloak: +```yaml +keycloak_rhsso_enable: False +keycloak_download_url: "https://///keycloak-x.y.zip" ``` -keycloak_admin_password: "" -keycloak_rhsso_enable: True -zip_file_local_path: -``` + ### Example installation command @@ -113,17 +127,20 @@ ansible-playbook -i -e @rhn-creds.yml playbooks/keycloak.yml -e localhost ansible_connection=local ``` + ## Configuration + ### Config Playbook -`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 provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist. + ### Example configuration command Execute the following command from the source root directory -``` +```bash ansible-playbook -i playbooks/keycloak-realm.yml -e keycloak_admin_password= -e keycloak_realm=test ``` @@ -136,6 +153,9 @@ ansible-playbook -i 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). + + ## License Apache License v2.0 or later diff --git a/roles/keycloak/README.md b/roles/keycloak/README.md index 8c367f7..3dffb47 100644 --- a/roles/keycloak/README.md +++ b/roles/keycloak/README.md @@ -14,6 +14,15 @@ This role requires the `python3-netaddr` library installed on the controller nod * or via the collection: `pip install -r requirements.txt` +Dependencies +------------ + +The roles depends on: + +* the `redhat_csp_download` role from [middleware_automation.redhat_csp_download](https://github.com/ansible-middleware/redhat-csp-download) collection if Red Hat Single Sign-on zip have to be downloaded from RHN. +* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection + + Versions -------- @@ -25,9 +34,10 @@ Versions Role Defaults ------------- +* Service configuration + | Variable | Description | Default | |:---------|:------------|:---------| -|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` | |`keycloak_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` | |`keycloak_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_ha_enabled` is True, else `False` | |`keycloak_admin_user`| Administration console user account | `admin` | @@ -41,7 +51,6 @@ Role Defaults |`keycloak_management_https_port`| TLS management port | `9993` | |`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` | |`keycloak_prefer_ipv4`| Prefer IPv4 stack and addresses for port binding | `True` | -|`keycloak_offline_install` | perform an offline install | `False`| |`keycloak_config_standalone_xml`| filename for configuration | `keycloak.xml` | |`keycloak_service_user`| posix account username | `keycloak` | |`keycloak_service_group`| posix account group | `keycloak` | @@ -49,6 +58,19 @@ Role Defaults |`jvm_package`| RHEL java package runtime | `java-1.8.0-openjdk-devel` | +* Install options + +| Variable | Description | Default | +|:---------|:------------|:---------| +|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` | +|`keycloak_offline_install` | perform an offline install | `False`| +|`keycloak_download_url`| Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download//`| +|`keycloak_rhsso_download_url`| Download URL for RHSSO | `https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId=`| +|`keycloak_version`| keycloak.org package version | `15.0.2` | +|`keycloak_rhsso_version`| RHSSO version | `7.5.0` | +|`keycloak_dest`| Installation root path | `/opt/keycloak` | + + Role Variables -------------- @@ -84,32 +106,14 @@ The following variables are _required_ only when `keycloak_db_enabled` is True: |`keycloak_db_user` | username for connecting to postgres | `keycloak-user` | |`keycloak_db_pass` | password for connecting to postgres | `keycloak-pass` | -The following variable can be used to install Keycloak or Red Hat Single Sign-On from local path: -| Variable | Description | Example | -|:---------|:------------|:---------| -|`zip_file_local_path` | Full local path of upstream(Keycloak) or Red Hat Single Sign-On zip file on Ansible control plane | `tmp/rhsso/rh-sso-7.5-server-dist.zip` | +Example Playbooks +----------------- -The following variable can be used to install Red Hat Single Sign-On from source via url, auth support is not added right now. - -| Variable | Description | Example | -|:---------|:------------|:---------| -|`rhsso_source_download_url` | URL to download Red Hat Single Sign-On zip file from source | `http://localhost:8081/nexus/rhsso/rh-sso-7.5-server-dist.zip` | +_NOTE_: use ansible vaults or other security systems for storing credentials. -Dependencies ------------- - -The roles depends on: - -* the `redhat_csp_download` role from [middleware_automation.redhat_csp_download](https://github.com/ansible-middleware/redhat-csp-download) collection if Red Hat Single Sign-on zip have to be downloaded from RHN. -* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection - - -Example Playbook ----------------- - -The following is an example playbook that makes use of the role to install keycloak from remote +* The following is an example playbook that makes use of the role to install keycloak from remote: ```yaml --- @@ -124,23 +128,7 @@ The following is an example playbook that makes use of the role to install keycl keycloak_admin_password: "changeme" ``` -The following is an example playbook that makes use of the role to install keycloak from local path on Ansible node - -```yaml ---- -- hosts: ... - collections: - - middleware_automation.keycloak - tasks: - - name: Include keycloak role - include_role: - name: keycloak - vars: - keycloak_admin_password: "changeme" - zip_file_local_path: "/tmp/keycloak/keycloak-16.1.0.zip" # This should be local path on Ansible node of upstream(keycloak) zip file -``` - -The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN +* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN: ```yaml --- @@ -157,9 +145,30 @@ The following is an example playbook that makes use of the role to install Red H vars: keycloak_admin_password: "changeme" keycloak_rhsso_enable: True + rhn_username: '' + rhn_password: '' ``` -The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from source url + +* The following example playbook makes use of the role to install keycloak from the controller node: + +```yaml +--- +- hosts: ... + collections: + - middleware_automation.keycloak + tasks: + - name: Include keycloak role + include_role: + name: keycloak + vars: + keycloak_admin_password: "changeme" + keycloak_offline_install: True + # This should be the filename of keycloak archive on Ansible node: keycloak-16.1.0.zip +``` + + +* This playbook installs Red Hat Single Sign-On from an alternate url: ```yaml --- @@ -173,10 +182,12 @@ The following is an example playbook that makes use of the role to install Red H vars: keycloak_admin_password: "changeme" keycloak_rhsso_enable: True - rhsso_source_download_url: "" # This should be the full of remote source rhsso zip file + keycloak_rhsso_download_url: "" + # This should be the full of remote source rhsso zip file and can contain basic authentication credentials ``` -The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from local path on Ansible node + +* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from the controller node: ```yaml --- @@ -190,7 +201,8 @@ The following is an example playbook that makes use of the role to install Red H vars: keycloak_admin_password: "changeme" keycloak_rhsso_enable: True - zip_file_local_path: "/tmp/rhsso/rh-sso-7.5-server-dist.zip" # This should be local path on Ansible node of rhsso zip file + keycloak_offline_install: True + # This should be the filename of rhsso zip file on Ansible node: rh-sso-7.5-server-dist.zip ``` License