Rol de Ansible para Keycloak

Este rol está diseñado para desplegar Keycloak en un sistema gestionado por systemd para propósitos de pruebas y desarrollo. El rol instalará Keycloak desde un archivo zip oficial descargado en el sistema objetivo.

El servidor Keycloak se configurará como un servicio de systemd llamado keycloak, ejecutándose como un usuario del sistema llamado keycloak. El rol se encargará de crear el usuario del sistema y el servicio.

Este rol también maneja parte de la configuración inicial del servidor Keycloak. Esto incluye configurar los puertos a escuchar, crear un usuario administrador inicial y configurar TLS mediante certificados autofirmados o proporcionados. La configuración del cortafuegos también se gestiona.

Uso

Elige un playbook para el escenario de TLS que te interese. Los siguientes playbooks de ejemplo están incluidos en este repositorio:

• tls-self-signed.yml - TLS a través de un certificado autofirmado generado automáticamente
• tls-cert-key.yml - TLS a través de archivos de certificado/clave proporcionados
• tls-pkcs12.yml - TLS a través de un paquete PKCS12 proporcionado

Todos los playbooks de ejemplo utilizan ansible-vault para las variables sensibles. Los ejemplos usan password para todos los secretos, incluido el propio password del vault. Se deben generar nuevos secretos y actualizarlos en los playbooks para evitar usar el ejemplo codificado. Las instrucciones para hacerlo están en comentarios en los playbooks de ejemplo.

Para ejecutar tu playbook elegido, asegúrate de agregar la opción --ask-vault-pass como en este ejemplo:

ansible-playbook --ask-vault-pass -i <inventario/lista de hosts> <playbook>

Si ya existe un despliegue de la misma versión de Keycloak en el sistema objetivo, el playbook fallará para evitar perder datos dentro de la base de datos de Keycloak. Se puede establecer una variable de fuerza para sobrescribir el despliegue existente. Esto se puede configurar como una variable en el playbook o añadirse en la línea de comandos como una extra-var:

ansible-playbook ... --extra-vars "keycloak_force_install=yes"

Controlar la ubicación del archivo de Keycloak

Por defecto, el archivo de Keycloak se descargará en el sistema local donde se esté ejecutando el playbook. Residira en el directorio especificado por la variable keycloak_local_download_dest. Cuando se extraiga el archivo en el sistema objetivo, el archivo se leerá en el sistema local y los archivos se crearán en el destino. Este comportamiento tiene la ventaja de descargar el archivo solo una vez y no almacenar el archivo en el objetivo, pero incurre en un costo de red al transferir el contenido del archivo nuevamente para cada objetivo durante el proceso de extracción. Si tienes una conexión de red de carga lenta en el host que ejecuta el playbook, la extracción no local puede ser inviable.

Alternativamente, tienes la opción de descargar el archivo directamente al objetivo y extraerlo allí, esto se controla mediante la variable keycloak_archive_on_target. Esto tiene la ventaja de transferir los datos del archivo solo una vez. La extracción del archivo será rápida porque no hay tráfico de red durante la extracción ya que todos los datos son locales al objetivo. Sin embargo, dejará el archivo en el objetivo después de la extracción.

Para cambiar la ubicación del archivo en la línea de comandos, agrega este argumento a tu comando de playbook:

-e "{keycloak_archive_on_target: True}"

Variables

Puedes elegir qué versión de Keycloak instalar configurando la siguiente variable. Esta se usará para determinar la URL de descarga desde https://www.keycloak.org/downloads.html:

• keycloak_version (por defecto: 4.8.2.Final)

La siguiente variable siempre debe proporcionarse, ya que el rol no tiene una predeterminación codificada:

• keycloak_admin_password (usa ansible-vault para proteger)

Puedes elegir un nombre de cuenta de administrador no predeterminado configurando la siguiente variable:

• keycloak_admin_user (por defecto: admin)

Para configurar la interfaz y los puertos en los que el servidor Keycloak escucha, se pueden establecer las siguientes variables:

• keycloak_bind_address (por defecto: 0.0.0.0)
• keycloak_http_port (por defecto: 8080)
• keycloak_https_port (por defecto: 8443)

Para TLS a través de un paquete PKCS12, se deben proporcionar las siguientes variables adicionales:

• keycloak_tls_pkcs12 (ruta al paquete PKCS12)
• keycloak_tls_pkcs12_passphrase (usa ansible-vault para proteger)
• keycloak_tls_pkcs12_alias (nombre de la clave/certificación en keycloak_tls_pkcs12)

Para TLS a través de archivos de clave/certificado, se deben proporcionar las siguientes variables adicionales:

• keycloak_tls_cert (ruta al archivo del certificado del servidor TLS)
• keycloak_tls_key (ruta al archivo de la clave del servidor TLS)

NOTA: los archivos TLS de origen (keycloak_tls_pkcs12, keycloak_tls_cert, keycloak_tls_key) utilizados para crear el almacén de claves de Keycloak pueden estar ubicados en el controlador de Ansible (es decir, local) o en el host remoto objetivo. Por defecto, el rol supone que los archivos TLS de origen son locales. Sin embargo, si los archivos TLS de origen están ubicados en el objetivo remoto, establece la variable keycloak_tls_files_on_target a True.

Puedes controlar los valores de tiempo de espera con las siguientes variables:

keycloak_startup_timeout: Número de segundos que se deben esperar para que Keycloak inicie.

keycloak_jboss_config_connect_timeout: Número de milisegundos para esperar a que la utilidad de configuración de jboss se conecte al servidor wildfly.

keycloak_jboss_config_command_timeout: Número de segundos para esperar a que la utilidad de configuración de jboss complete cada comando ejecutado en el archivo de configuración.

Consulta roles/keycloak/defaults/main.yml para una lista de otros valores predeterminados de variables que se pueden sobrescribir.

Pruebas

Se proporcionan pruebas de in-tree que utilizan molecule para probar el rol contra contenedores de docker. Estas pruebas están diseñadas para ser utilizadas por CI, pero también pueden ejecutarse localmente para probar mientras se desarrolla.

Problema del nombre del rol

ADVERTENCIA: Para las pruebas in-tree, el nombre del directorio debe coincidir con el nombre del rol de Ansible Galaxy.

NOTA: En estos ejemplos se asume que el repositorio ha sido clonado en ~/src/.

Ansible espera que un rol tenga una estructura de directorio prescrita. Por ejemplo, si el rol se llama my_role, Ansible esperará encontrar un directorio llamado my_role en el ANSIBLE_ROLES_PATH con subdirectorios similares a esto:

my_role/
├── defaults
├── files
├── handlers
├── meta
├── tasks
├── templates
├── tests
└── vars

Por convención, la mayoría de los roles de Galaxy se crean en un repositorio de git cuyo directorio de nivel superior contiene los subdirectorios de rol anteriores, por lo que el directorio creado al clonar el repositorio de git se convierte en el nombre del rol. Usando el ejemplo anterior, el repositorio de git se llamaría my_role. Sin embargo, la mayoría de los repositorios de git no están nombrados idénticamente como su nombre de rol de Galaxy. Si intentas ejecutar molecule test en la parte superior de un árbol de git clonado con el nombre de repositorio predeterminado, recibirás un error de rol no encontrado como este:

ERROR! el rol 'nkinder.keycloak' no fue encontrado en /home/$USER/src/ansible-keycloak/molecule/default/roles:/tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src:/home/$USER/src/ansible-keycloak/molecule/default

La solución a esto es sencilla; al clonar el repositorio de git, proporciona un nombre de directorio que coincida con el nombre del rol en el archivo molecule/default/playbook.yml.

Para determinar el nombre del rol, molecule encontrará su definición en molecule/default/playbook.yml:

  roles:
    - role: nkinder.keycloak

Por lo tanto, el nombre del rol que usará molecule es nkinder.keycloak.

Así que para clonar este repositorio haz esto:

$ cd ~/src
$ git clone [email protected]:nkinder/ansible-keycloak.git nkinder.keycloak

Por supuesto, si clonas desde un fork de GitHub, deberás ajustar la URL del repositorio en consecuencia.

Necesitarás cambiar al repositorio clonado:

$ cd nkinder.keycloak

Cuando ejecutes molecule test desde el directorio superior del repositorio de git, molecule obtendrá la ruta del directorio de trabajo actual y, a partir de eso, encontrará la ruta al directorio de nivel superior, luego establecerá el ANSIBLE_ROLES_PATH para incluir el directorio de nivel superior del repositorio del rol. Por lo tanto, cuando ansible se ejecute, encontrará tu rol a través del nombre del directorio de tu repositorio de git. Por ejemplo:

ANSIBLE_ROLES_PATH: /tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src

Dado que ansible está buscando un rol llamado nkinder.keycloak, buscará en los directorios listados en ANSIBLE_ROLES_PATH y utilizará los archivos que encuentre en /home/$USER/src/nkinder.keycloak.

NOTA: molecule almacenará algunos archivos en un directorio temporal durante la duración de una ejecución de prueba, este es el MOLECULE_EPHEMERAL_DIRECTORY y en nuestros ejemplos es /tmp/molecule/ansible-keycloak/default, de ahí el primer camino en el ANSIBLE_ROLES_PATH anterior.

NOTA: git no requiere que el nombre del directorio de nivel superior en el repositorio coincida con el nombre del repositorio de git. A pesar de que el nombre del directorio del repositorio clonado será diferente al nombre del repositorio, todas las operaciones de git funcionarán como se espera porque la URL del repositorio está especificada como un remoto en .git/config.

Las pruebas se realizan mejor instalando molecule en un virtualenv:

  $ virtualenv .venv
  $ source .venv/bin/activate
  $ pip install molecule docker

NOTA: Debes nombrar el directorio de virtualenv como .venv porque molecule lo espera.

ADVERTENCIA: Si ya habías clonado el repositorio bajo el nombre del repositorio en lugar del nombre del rol, puedes renombrar el directorio del repositorio; sin embargo, si creaste .venv antes del renombramiento, deberás eliminar .venv y recrearlo porque el virtualenv habrá incrustado las anticuadas rutas de acceso.

Por defecto, molecule utiliza docker para construir y ejecutar imágenes de prueba. Necesitarás tener docker instalado y el demonio de Docker ejecutándose:

# Para instalar el paquete docker
$ sudo dnf install docker

# Para iniciar el servicio de Docker usa:
$ sudo systemctl start docker

# Verifica que Docker se haya instalado y esté funcionando correctamente ejecutando
# la imagen hello-world de Docker.

$ sudo docker run hello-world

# Para iniciar opcionalmente el demonio de Docker al arranque:
$ sudo systemctl enable docker

Es necesario ejecutar las pruebas como un usuario autorizado para ejecutar el comando docker sin usar sudo. Esto típicamente se logra añadiendo tu usuario al grupo 'docker' en tu sistema.

$ sudo groupadd docker
$ sudo gpasswd -a $USER docker
$ sudo systemctl restart docker

# La membresía en grupos se evalúa cuando creas una nueva sesión de inicio.
# A menos que cierres sesión y vuelvas a iniciar, tendrás que usar `newgrp`
# para agregar la membresía de tu grupo `docker` en la sesión de inicio actual.
$ newgrp docker

Además, hay un desafío relacionado con python-libselinux en plataformas que utilizan SELinux. Si estás utilizando un virtualenv, debes asegurarte de que el módulo python de selinux esté disponible en el virtualenv. Incluso si está instalado en tu host controlador de ansible y en el host objetivo, algunas de las tareas que se delegan al localhost usarán el virtualenv. El módulo selinux no se puede instalar a través de pip. Una solución alternativa para esto es copiar todo el directorio selinux de tu ubicación de site-packages del sistema (/usr/lib64/$PY_VERSION/site-packages/selinux en x86_64) en el directorio de site-packages del virtualenv. También necesitarás copiar el archivo .so de selinux desde el directorio de site-packages (no se encuentra dentro del directorio selinux). El nombre del selinux.so varía entre Python2 y Python3.

En Python2, el nombre base del .so es _selinux.so, para Python 2.7 en x86_64 sería este .so:

/usr/lib64/python2.7/site-packages/_selinux.so

En Python3, el nombre base del .so agrega cpython, la versión de python, la arquitectura y el SO; para Python 3.7 en x86_64 se vería así:

/usr/lib64/python3.7/site-packages/_selinux.cpython-37m-x86_64-linux-gnu.so

Una vez que tu virtualenv esté configurado correctamente, las pruebas se pueden ejecutar con estos comandos:

$ cd nkinder.keycloak # Tu repositorio cuyo directorio coincide con el nombre del rol de Galaxy
$ molecule test

SUGERENCIA: Añadir --debug al comando molecule puede ayudar a diagnosticar problemas, así como capturar la salida en un archivo de registro; podrías querer hacer esto:

$ molecule --debug test 2>&1 | tee molecule.log

Por defecto, el objetivo de la prueba será la última imagen centos de Docker Hub. Puedes probar con una imagen/etiqueta diferente así:

$ MOLECULE_DISTRO="fedora:28" molecule test`

POR HACER

• Agregar un playbook de ejemplo que use ansible-freeipa para crear el servicio de Keycloak y obtener el certificado.
• Agregar un playbook de ejemplo que cree un realm/client usando el módulo keycloak_client.
• Agregar la capacidad de configurar IdM como backend de identidad para Keycloak a través del proveedor SSSD.