Merge pull request #11 from guidograzioli/polish_argument_specs

document argument_specs

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
+- 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`)
+- 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`)
+- 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,7 +55,7 @@ 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)
@@ -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

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_realm/README.md

@@ -37,6 +37,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 +53,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_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>
+      config: <dictionary of supported configuration values, required>
-      mappers: <List 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 +92,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
+                default: "[]"
-                description: "TODO document argument"
+                description: "List of client declarations for the realm"
-                type: "str"
+                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/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 }}"