docs(collection): document all roles and fix metadata drift
Replace ansible-galaxy init placeholders across the collection and correct documentation that drifted from the code, after a multi-agent review of every role README against its defaults, tasks and templates. Collection level: - README: role table for all 16 roles, requirements and role-ordering - galaxy.yml: declare community.docker and community.general deps, real description/tags/urls; normalize license to MIT-0 - meta/runtime.yml: requires_ansible '>=2.15.0' - plugins/README: document the homarr_layout filter and garage_credentials lookup instead of scaffold boilerplate Per-role meta/main.yml and README for the placeholder roles (389ds, authentik, authentik_outpost_ldap, base, collabora, drawio, garage, homarr, httpbin, keycloak, nextcloud, opencloud, traefik). Correctness fixes found during review: - keycloak: wrong domain default, drop invented keycloak_cert_resolver, document the provisioning feature - garage: root_domain is .s3.<first-entry>, not the bare domain - opnform: jwt/front_api secrets use `openssl rand -hex 32`; align the validation fail_msg in tasks/main.yml accordingly - send: S3 example references garage_s3_domains[0] (was singular) - opencloud: document required opencloud_wopi_domain License normalized to MIT-0 across galaxy.yml, role meta and READMEs to match the SPDX headers.
This commit is contained in:
Simon Bärlocher
parent
19864d79b2
commit
3236ca332f
38 changed files with 740 additions and 625 deletions
|
|
@ -1,65 +1,119 @@
|
|||
Keycloak
|
||||
=========
|
||||
# Keycloak
|
||||
|
||||
Ansible role to deploy Keycloak with PostgreSQL database using Docker Compose.
|
||||
Ansible role to deploy Keycloak with a PostgreSQL backend via Docker
|
||||
Compose, published behind Traefik. Optionally provisions realm resources
|
||||
(groups, users, OIDC clients, identity providers, LDAP user federations)
|
||||
through the `community.general` Keycloak modules.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
|
||||
- Docker and Docker Compose installed on the target host
|
||||
- Ansible collection: `community.docker`
|
||||
- Traefik reverse proxy (for external access)
|
||||
- Docker and Docker Compose on the target host (e.g. via
|
||||
`digitalboard.core.base`)
|
||||
- Ansible collections: `community.docker`, and `community.general` when
|
||||
`keycloak_provisioning_enabled` is true
|
||||
- Traefik reverse proxy with the `proxy` network already created (for
|
||||
external access)
|
||||
|
||||
Role Variables
|
||||
--------------
|
||||
## Role variables
|
||||
|
||||
Key variables defined in `defaults/main.yml`:
|
||||
Key variables from `defaults/main.yml`:
|
||||
|
||||
**Base Configuration:**
|
||||
- `docker_compose_base_dir`: Base directory for Docker Compose files (default: `/etc/docker/compose`)
|
||||
- `docker_volume_base_dir`: Base directory for Docker volumes (default: `/srv/data`)
|
||||
### Base configuration
|
||||
|
||||
**Keycloak Configuration:**
|
||||
- `keycloak_service_name`: Service name (default: `keycloak`)
|
||||
- `keycloak_domain`: Domain name for Keycloak (default: `auth.digitalboard.ch`)
|
||||
- `keycloak_image`: Keycloak Docker image (default: `quay.io/keycloak/keycloak:24.0.1`)
|
||||
- `keycloak_port`: Internal Keycloak port (default: `8080`)
|
||||
- `keycloak_admin_user`: Admin username (default: `admin`)
|
||||
- `keycloak_admin_password`: Admin password (default: `changeme`)
|
||||
- `keycloak_log_level`: Log level (default: `INFO`)
|
||||
- `keycloak_proxy_mode`: Proxy mode (default: `edge`)
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `docker_compose_base_dir` | `/etc/docker/compose` | Base dir for Compose projects. |
|
||||
| `docker_volume_base_dir` | `/srv/data` | Base dir for persistent volumes. |
|
||||
| `keycloak_service_name` | `keycloak` | Compose/service name; builds the per-service paths. |
|
||||
|
||||
**PostgreSQL Configuration:**
|
||||
- `keycloak_postgres_image`: PostgreSQL Docker image (default: `postgres:15`)
|
||||
- `keycloak_postgres_db`: Database name (default: `keycloak`)
|
||||
- `keycloak_postgres_user`: Database user (default: `keycloak`)
|
||||
- `keycloak_postgres_password`: Database password (default: `changeme`)
|
||||
### Keycloak
|
||||
|
||||
**Traefik Configuration:**
|
||||
- `keycloak_traefik_network`: Traefik network name (default: `proxy`)
|
||||
- `keycloak_backend_network`: Backend network name (default: `backend`)
|
||||
- `keycloak_use_ssl`: Enable SSL (default: `true`)
|
||||
- `keycloak_cert_resolver`: Certificate resolver name (default: `dns`)
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `keycloak_domain` | `keycloak.local.test` | Host rule and `KC_HOSTNAME`. |
|
||||
| `keycloak_image` | `quay.io/keycloak/keycloak:24.0.1` | Keycloak image. |
|
||||
| `keycloak_port` | `8080` | Internal HTTP port advertised to Traefik. |
|
||||
| `keycloak_admin_user` | `admin` | Bootstrap admin user. |
|
||||
| `keycloak_admin_password` | `changeme` | Admin password — **override this**. |
|
||||
| `keycloak_log_level` | `INFO` | `KC_LOG_LEVEL`. |
|
||||
| `keycloak_proxy_mode` | `edge` | `KC_PROXY` mode. |
|
||||
| `keycloak_gzip_enabled` | `false` | Toggle Keycloak GZIP response encoding. |
|
||||
| `keycloak_truststore_certificates` | `[]` | Host PEM paths mounted into the truststore (`KC_TRUSTSTORE_PATHS`). |
|
||||
| `keycloak_extra_hosts` | `[]` | Extra `host:ip` entries for the container. |
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
### PostgreSQL
|
||||
|
||||
This role requires the Traefik reverse proxy to be configured and the `proxy` network to be created.
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `keycloak_postgres_image` | `postgres:15` | PostgreSQL image. |
|
||||
| `keycloak_postgres_db` | `keycloak` | Database name. |
|
||||
| `keycloak_postgres_user` | `keycloak` | Database user. |
|
||||
| `keycloak_postgres_password` | `changeme` | Database password — **override this**. |
|
||||
|
||||
Example Playbook
|
||||
----------------
|
||||
### Traefik
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `keycloak_traefik_network` | `proxy` | External Traefik network. |
|
||||
| `keycloak_backend_network` | `backend` | Internal network to PostgreSQL. |
|
||||
| `keycloak_use_ssl` | `true` | Route on `websecure` with `tls=true` instead of `web`. |
|
||||
|
||||
TLS is requested from Traefik via `tls=true`; the role does not set a
|
||||
certificate resolver, so Traefik issues/serves the certificate according
|
||||
to its own configuration.
|
||||
|
||||
### Provisioning (optional)
|
||||
|
||||
Provisioning runs only when `keycloak_provisioning_enabled` is true. The
|
||||
tasks wait for the `/health/ready` endpoint and then call the
|
||||
`community.general.keycloak_*` modules, delegated to `localhost` against
|
||||
`keycloak_auth_url` (derived from `keycloak_use_ssl` + `keycloak_domain`).
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `keycloak_provisioning_enabled` | `false` | Enable realm provisioning. |
|
||||
| `keycloak_realm` | `default` | Target realm; created unless `master`. |
|
||||
| `keycloak_realm_display_name` | `Default Realm` | Realm display name. |
|
||||
| `keycloak_auth_url` | derived | API base URL for provisioning. |
|
||||
| `keycloak_groups` | `[]` | Groups to create. |
|
||||
| `keycloak_local_users` | `[]` | Local users to create. |
|
||||
| `keycloak_oidc_clients` | `[]` | OIDC clients to create. |
|
||||
| `keycloak_identity_providers` | `[]` | Identity providers (e.g. Entra ID). |
|
||||
| `keycloak_user_federations` | `[]` | LDAP user federations. |
|
||||
| `keycloak_removed_users` | `[]` | Usernames to delete. |
|
||||
| `keycloak_removed_groups` | `[]` | Group names to delete. |
|
||||
| `keycloak_removed_clients` | `[]` | Client IDs to delete. |
|
||||
| `keycloak_removed_identity_providers` | `[]` | IdP aliases to delete. |
|
||||
| `keycloak_removed_user_federations` | `[]` | Federation names to delete. |
|
||||
|
||||
See `defaults/main.yml` for the full entry shape of each list.
|
||||
|
||||
## Dependencies
|
||||
|
||||
This role requires the Traefik reverse proxy to be configured and the
|
||||
`proxy` network to be created beforehand (it is referenced as an external
|
||||
network in the Compose file). The `backend` network is created by the
|
||||
Compose project itself.
|
||||
|
||||
## Example playbook
|
||||
|
||||
```yaml
|
||||
- hosts: backend_servers
|
||||
roles:
|
||||
- role: keycloak
|
||||
- role: digitalboard.core.keycloak
|
||||
vars:
|
||||
keycloak_domain: "auth.example.com"
|
||||
keycloak_admin_password: "secure_password"
|
||||
keycloak_postgres_password: "secure_db_password"
|
||||
keycloak_admin_password: "{{ vault_keycloak_admin_password }}"
|
||||
keycloak_postgres_password: "{{ vault_keycloak_pg_password }}"
|
||||
keycloak_provisioning_enabled: true
|
||||
keycloak_oidc_clients:
|
||||
- client_id: nextcloud
|
||||
name: "Nextcloud"
|
||||
client_secret: "{{ vault_nextcloud_client_secret }}"
|
||||
redirect_uris:
|
||||
- "https://nextcloud.example.com/apps/user_oidc/code"
|
||||
```
|
||||
|
||||
License
|
||||
-------
|
||||
## License
|
||||
|
||||
MIT-0
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue