Skip to content

Commit dbad4ea

Browse files
guidograzioliguidograzioli
committed
Update documentation
1 parent c5ee73c commit dbad4ea

File tree

2 files changed

+106
-74
lines changed

2 files changed

+106
-74
lines changed

‎README.md‎

Lines changed: 49 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -46,57 +46,71 @@ A requirement file is provided to install:
4646

4747
## Usage
4848

49+
4950
### Install Playbook
5051

51-
`playbooks/keycloak.yml` installs the upstream(Keycloak) based on the defined variables.
52-
`playbooks/rhsso.yml` installs Red Hat Single Sign-On(RHSSO) based on defined variables.
52+
* [`playbooks/keycloak.yml`](playbooks/keycloak.yml) installs the upstream(Keycloak) based on the defined variables.
53+
* [`playbooks/rhsso.yml`](playbooks/rhsso.yml) installs Red Hat Single Sign-On(RHSSO) based on defined variables.
5354

54-
### Choosing between upstream(Keycloak) project and Red Hat Single Sign-On(RHSSO)
55+
Both playbooks include the `keycloak` role, with different settings, as described in the following sections.
5556

56-
The roles supports installing upstream(Keycloak) or Red Hat Single Sign-On in the following ways
57+
For service configuration details, refer to the [keycloak role README](roles/keycloak/README.md).
5758

58-
#### Install upstream(Keycloak) from remote source
5959

60-
This is default approach, there is one required variable
60+
### Choosing between upstream project (Keycloak) and Red Hat Single Sign-On (RHSSO)
6161

62-
```
63-
keycloak_admin_password: "<changeme>"
64-
```
62+
The general flag `keycloak_rhsso_enable` controls what to install between upstream(Keycloak, when `False`) or Red Hat Single Sign-On (when `True`).
63+
The default value for the flag if `True` when Red Hat Network credentials are defined, `False` otherwise.
6564

66-
#### Install upstream(Keycloak) from local source when the following variable is defined
6765

68-
```
69-
keycloak_admin_password: "<changeme>"
70-
zip_file_local_path: <keycloak zip file on Ansible control node local path>
71-
```
66+
#### Install upstream (Keycloak) from keycloak releases
7267

73-
#### Install RHSSO from the Red Hat Customer Support Portal, when the following variables are defined
68+
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.
7469

75-
```
76-
keycloak_admin_password: "<changeme>"
70+
71+
#### Install RHSSO from the Red Hat Customer Support Portal
72+
73+
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.
74+
75+
```yaml
7776
rhn_username: '<customer_portal_username>'
7877
rhn_password: '<customer_portal_password>'
79-
rhsso_rhn_id: '<sso_product_id>'
78+
# (keycloak_rhsso_enable defaults to True)
8079
```
8180

82-
where `sso_product_id` is the ID for the specific Red Hat Single Sign-On version, ie. _101971_ will install version _7.5_)
8381

84-
#### Install RHSSO from remote sources like Nexus etc, when the following variables are defined
82+
#### Install from controller node (local source)
8583

84+
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
85+
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.
86+
87+
```yaml
88+
keycloak_offline_install: True
8689
```
87-
keycloak_admin_password: "<changeme>"
90+
91+
And depending on `keycloak_rhsso_enable`:
92+
93+
* `True`: install RHSSO using file rh-sso-x.y.z-server-dist.zip
94+
* `False`: install keycloak using file keycloak-x.y.zip
95+
96+
97+
#### Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)
98+
99+
For RHSSO:
100+
101+
```yaml
88102
keycloak_rhsso_enable: True
89-
rhsso_source_download_url: '<url to download RHSSO zip file>'
103+
keycloak_rhsso_download_url: "https://<internal-nexus.private.net>/<path>/<to>/rh-sso-x.y.z-server-dist.zip"
90104
```
91105

92-
#### Install RHSSO from local source when the following variable is defined
106+
For keycloak:
93107

94-
```
95-
keycloak_admin_password: "<changeme>"
96-
keycloak_rhsso_enable: True
97-
zip_file_local_path: <rhsso zip file on Ansible control node local path>
108+
```yaml
109+
keycloak_rhsso_enable: False
110+
keycloak_download_url: "https://<internal-nexus.private.net>/<path>/<to>/keycloak-x.y.zip"
98111
```
99112

113+
100114
### Example installation command
101115

102116
Execute the following command from the source root directory
@@ -113,17 +127,20 @@ ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e
113127
localhost ansible_connection=local
114128
```
115129
130+
116131
## Configuration
117132
133+
118134
### Config Playbook
119135
120-
`playbooks/keycloak-realm.yml` creates provided realm, user federation(s), client(s), client role(s) and client user(s) if they don't exist.
136+
[`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.
137+
121138
122139
### Example configuration command
123140
124141
Execute the following command from the source root directory
125142
126-
```
143+
```bash
127144
ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test
128145
```
129146

@@ -136,6 +153,9 @@ ansible-playbook -i <ansible_hosts> playbooks/keycloak-realm.yml -e keycloak_adm
136153
localhost ansible_connection=local
137154
```
138155

156+
For configuration details, refer to the [keycloak_realm role README](roles/keycloak_realm/README.md).
157+
158+
139159
## License
140160

141161
Apache License v2.0 or later

‎roles/keycloak/README.md‎

Lines changed: 57 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,15 @@ This role requires the `python3-netaddr` library installed on the controller nod
1414
* or via the collection: `pip install -r requirements.txt`
1515

1616

17+
Dependencies
18+
------------
19+
20+
The roles depends on:
21+
22+
* 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.
23+
* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection
24+
25+
1726
Versions
1827
--------
1928

@@ -25,9 +34,10 @@ Versions
2534
Role Defaults
2635
-------------
2736

37+
* Service configuration
38+
2839
| Variable | Description | Default |
2940
|:---------|:------------|:---------|
30-
|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` |
3141
|`keycloak_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` |
3242
|`keycloak_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_ha_enabled` is True, else `False` |
3343
|`keycloak_admin_user`| Administration console user account | `admin` |
@@ -41,14 +51,26 @@ Role Defaults
4151
|`keycloak_management_https_port`| TLS management port | `9993` |
4252
|`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` |
4353
|`keycloak_prefer_ipv4`| Prefer IPv4 stack and addresses for port binding | `True` |
44-
|`keycloak_offline_install` | perform an offline install | `False`|
4554
|`keycloak_config_standalone_xml`| filename for configuration | `keycloak.xml` |
4655
|`keycloak_service_user`| posix account username | `keycloak` |
4756
|`keycloak_service_group`| posix account group | `keycloak` |
4857
|`keycloak_service_pidfile`| pid file path for service | `/run/keycloak.pid` |
4958
|`jvm_package`| RHEL java package runtime | `java-1.8.0-openjdk-devel` |
5059

5160

61+
* Install options
62+
63+
| Variable | Description | Default |
64+
|:---------|:------------|:---------|
65+
|`keycloak_rhsso_enable`| Enable Red Hat Single Sign-on installation | `False` |
66+
|`keycloak_offline_install` | perform an offline install | `False`|
67+
|`keycloak_download_url`| Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/<version>/<archive>`|
68+
|`keycloak_rhsso_download_url`| Download URL for RHSSO | `https://access.redhat.com/jbossnetwork/restricted/softwareDownload.html?softwareId=<productID>`|
69+
|`keycloak_version`| keycloak.org package version | `15.0.2` |
70+
|`keycloak_rhsso_version`| RHSSO version | `7.5.0` |
71+
|`keycloak_dest`| Installation root path | `/opt/keycloak` |
72+
73+
5274
Role Variables
5375
--------------
5476

@@ -84,32 +106,14 @@ The following variables are _required_ only when `keycloak_db_enabled` is True:
84106
|`keycloak_db_user` | username for connecting to postgres | `keycloak-user` |
85107
|`keycloak_db_pass` | password for connecting to postgres | `keycloak-pass` |
86108

87-
The following variable can be used to install Keycloak or Red Hat Single Sign-On from local path:
88-
89-
| Variable | Description | Example |
90-
|:---------|:------------|:---------|
91-
|`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` |
92-
93-
The following variable can be used to install Red Hat Single Sign-On from source via url, auth support is not added right now.
94-
95-
| Variable | Description | Example |
96-
|:---------|:------------|:---------|
97-
|`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` |
98-
99-
100-
Dependencies
101-
------------
102-
103-
The roles depends on:
104109

105-
* 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.
106-
* the `wildfly_driver` role from [middleware_automation.wildfly](https://github.com/ansible-middleware/wildfly) collection
110+
Example Playbooks
111+
-----------------
107112

113+
_NOTE_: use ansible vaults or other security systems for storing credentials.
108114

109-
Example Playbook
110-
----------------
111115

112-
The following is an example playbook that makes use of the role to install keycloak from remote
116+
* The following is an example playbook that makes use of the role to install keycloak from remote:
113117

114118
```yaml
115119
---
@@ -124,23 +128,7 @@ The following is an example playbook that makes use of the role to install keycl
124128
keycloak_admin_password: "changeme"
125129
```
126130
127-
The following is an example playbook that makes use of the role to install keycloak from local path on Ansible node
128-
129-
```yaml
130-
---
131-
- hosts: ...
132-
collections:
133-
- middleware_automation.keycloak
134-
tasks:
135-
- name: Include keycloak role
136-
include_role:
137-
name: keycloak
138-
vars:
139-
keycloak_admin_password: "changeme"
140-
zip_file_local_path: "/tmp/keycloak/keycloak-16.1.0.zip" # This should be local path on Ansible node of upstream(keycloak) zip file
141-
```
142-
143-
The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN
131+
* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from RHN:
144132
145133
```yaml
146134
---
@@ -157,9 +145,30 @@ The following is an example playbook that makes use of the role to install Red H
157145
vars:
158146
keycloak_admin_password: "changeme"
159147
keycloak_rhsso_enable: True
148+
rhn_username: '<customer portal username>'
149+
rhn_password: '<customer portal password>'
160150
```
161151
162-
The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from source url
152+
153+
* The following example playbook makes use of the role to install keycloak from the controller node:
154+
155+
```yaml
156+
---
157+
- hosts: ...
158+
collections:
159+
- middleware_automation.keycloak
160+
tasks:
161+
- name: Include keycloak role
162+
include_role:
163+
name: keycloak
164+
vars:
165+
keycloak_admin_password: "changeme"
166+
keycloak_offline_install: True
167+
# This should be the filename of keycloak archive on Ansible node: keycloak-16.1.0.zip
168+
```
169+
170+
171+
* This playbook installs Red Hat Single Sign-On from an alternate url:
163172

164173
```yaml
165174
---
@@ -173,10 +182,12 @@ The following is an example playbook that makes use of the role to install Red H
173182
vars:
174183
keycloak_admin_password: "changeme"
175184
keycloak_rhsso_enable: True
176-
rhsso_source_download_url: "<REPLACE with - Source download url>" # This should be the full of remote source rhsso zip file
185+
keycloak_rhsso_download_url: "<REPLACE with download url>"
186+
# This should be the full of remote source rhsso zip file and can contain basic authentication credentials
177187
```
178188

179-
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
189+
190+
* The following is an example playbook that makes use of the role to install Red Hat Single Sign-On from the controller node:
180191

181192
```yaml
182193
---
@@ -190,7 +201,8 @@ The following is an example playbook that makes use of the role to install Red H
190201
vars:
191202
keycloak_admin_password: "changeme"
192203
keycloak_rhsso_enable: True
193-
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
204+
keycloak_offline_install: True
205+
# This should be the filename of rhsso zip file on Ansible node: rh-sso-7.5-server-dist.zip
194206
```
195207

196208
License

0 commit comments

Comments
 (0)