Acelerando los desarrollos con contenedores : Keycloak (Parte 3)

Publicado por Víctor Madrid el 04 August 2022

Arquitectura de SolucionesKeycloakExportImportConfiguraciónPersistencia

En este tercer artículo se va a mostrar cómo poder disponer de un contenedor de Keycloak la característica de importar y exportar configuraciones.

Aconsejo leer el primer artículo para entender algunos conceptos y ciertos aspectos de la configuración y uso de Keycloak ;-).

Posteriormente si quieres puedes leer el segundo artículo para entender temas de persistencia sobre Keycloak

Este artículo está dividido en 4 partes:

1. Introducción
2. Stack Tecnológico
3. Ejemplos de Uso
4. Conclusiones

1. Introducción

En este apartado se tratarán los siguiente puntos :

1.1. Introducción al uso de contenedores como aceleradores del desarrollo
1.2. ¿Qué necesidades tenemos para tener un "Keycloak" con contenedores?

1.1. Introducción al uso de contenedores como aceleradores del desarrollo

Para centralizar esta información en un único punto y así poder facilitar su consulta se ha diseñado un artículo específico

1.2. ¿Qué necesidades tenemos para requerir un "Keycloak" con contenedores e importación/exportación de configuraciones?

Los motivos principales que me llevaron a tratar de investigar en tener un Keycloak dentro de un contenedor fueron los siguientes:

Disponer de una instalación inmutable
Replicar la instalación del producto del cliente en local (versionado, entorno, etc.)
Minimizar en un entorno previo los posibles cambios de configuración que pudiéramos requerir --> Perdiendo el miedo a los cambios :-)
Asegurarse de que a todo el mundo le funcionaba de primeras
Ayudar al equipo a coger experiencia en el uso de Keycloak
Disponer en el entorno local de la misma pieza que se utilizará en entornos altos
Investigar previamente cómo funciona su API de integración
Ayudarme a establecer cierta lógica de negocio, gestión de errores sobre la pieza de desarrolla que contenga la integración

Y en concreto con la importación / exportación de configuraciones :

Utilizar la configuración existente en otro entorno
Poder realizar cambios sin miedo a romper
Posibilidad persistir la configuración si se genera un volumen
...

2. Stack Tecnológico

Este es stack tecnológico elegido para implementar la funcionalidad "Keycloak":

Docker - Tecnología de Contenedores/Containers
Docker Hub - Repositorio de Docker Público donde se ubican las imágenes oficiales
Keycloak - Herramienta IAM / IdP
Postgresql - Base de datos relacional

3. Ejemplos de Uso

Para enseñar a utilizarlo y así practicar se ha habilitado un repositorio, este repositorio se reutilizará para otros artículos de "Acelerando los desarrollos con contenedores".

Este artículo consta de dos modos :

Modo sólo import
Modo import + persistencia

Modo sólo import

La parte de que tiene que ver con este artículo se encuentra en el apartado de docker/keycloak/basic-with-import

Este proyecto consta del siguiente elemento:

Contenedor de Keycloak con Import
Proporciona la instalación del producto en la versión establecida o bien en la última versión disponible en Docker Hub
Proporciona la configuración para su uso (usuarios, password, etc) con una cuenta del tipo admin mediante variables de entorno (esta funcionalidad esta proporcionada por el propio contenedor)
Proporciona la configuración para ver trazas de depuración
Proporciona el fichero exportado previamente y que contiene una configuración determinada, dicho fichero será importado por Keycloak en el arranque. Para ello establece un volumen de intercambio entre un fichero en una ruta local y el mismo fichero dentro del contenedor

Ejemplo de fichero "docker-compose.yaml"

version: '3'  
services:

  keycloak:
    #image: jboss/keycloak
    image: jboss/keycloak:16.1.0
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: password
      KEYCLOAK_LOGLEVEL: DEBUG
      ROOT_LOGLEVEL: DEBUG
      KEYCLOAK_IMPORT: /tmp/realm-export.json
    ports:
      - '8083:8080'
    volumes:
      - ./config/realm-export.json:/tmp/realm-export.json

Para ver como lanzarlo ver fichero README dentro del proyecto.

Modo import + persistencia

Contenedor de Keycloak con import + persistencia
Proporciona la instalación del producto en la versión establecida o bien en la última versión disponible en Docker Hub
Proporciona la configuración para su uso (usuarios, password, etc) con una cuenta del tipo admin mediante variables de entorno (esta funcionalidad esta proporcionada por el propio contenedor)
Proporciona la configuración para ver trazas de depuración
Proporciona el fichero exportado previamente y que contiene una configuración determinada, dicho fichero será importado por Keycloak en el arranque. Para ello establece un volumen de intercambio entre un fichero en una ruta local y el mismo fichero dentro del contenedor
Proporciona la ejecución de un comando para autorizar la actualización con el fichero
Proporciona las variables de entorno para configurar la base de datos propuesta
Proporciona la base de datos seleccionada (en este caso postgres), su configuración y la definición de un volumen para persistencia
Proporciona un script de carga de base de datos para inicializarla

Ejemplo de fichero "docker-compose.yaml"

version: '3'  
services:

  db:
    #image: postgres
    image: postgres:14.2
    environment: 
      POSTGRES_DB: keycloakdb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - '5432:5432'
    volumes:
      - ./db:/var/lib/postgresql/data
      - ./config/postgres:/docker-entrypoint-initdb.d

  keycloak:
    #image: jboss/keycloak
    image: jboss/keycloak:16.1.0
    environment:
      DB_VENDOR: POSTGRES
      DB_ADDR: db
      DB_DATABASE: keycloakdb
      DB_USER: postgres
      DB_PASSWORD: postgres
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: password
      #KEYCLOAK_LOGLEVEL: DEBUG
      #ROOT_LOGLEVEL: DEBUG
      KEYCLOAK_IMPORT: /tmp/realm-export.json
    ports:
      - '8083:8080'
    volumes:
      - ./config/keycloak/realm-export.json:/tmp/realm-export.json
    command: ["-Dkeycloak.profile.feature.upload_scripts=enabled"]
    depends_on:
      - db

volumes:  
  db:
    driver: local

Para ver como lanzarlo ver fichero README dentro del proyecto.

3.1. Scripts de Soporte

N/A

3.2. Investigar lo que se usa

Cuando uno crea un contenedor basado en una imagen, ya se ha visto que consideraciones se deben tener para llegar a entender que es lo que hace.

Si tienes alguna duda vuelve a revisar el apartado "Soporte de Análisis de Contenedores" del artículo de introducción : Acelerando los desarrollos con contenedores: Introducción

Ejemplo de ejecución para mostrar la información del proceso ejecutado tras realizar un "up"

Ejemplo de inspección sobre el contenedor creado

Ejemplo de investigación general dentro del contenedor

Se podrán validar algunos de los aspectos configurados como puede ser la cadena de conexión a la base de datos, etc.

3.3. Verificar resultados

Se accede a la URL del Keycloak con:

http://localhost:8083/

Accediendo a la consola de administración (Administration Console)

Verificando el acceso con el usuario declarado en las variables de entorno

3.4. Preparación de la Configuración

Generación del fichero de exportación

Si se quiere tener una configuración inicial se aconseja seguir el primer artículo y a partir de ahí generar el fichero de exportación : realm-export.json

Para este artículo se ha hecho uso de la importación del fichero de configuración anterior

3.5. Probar la importación

Modo sólo import

Pasos a seguir:

Arrancar el fichero docker-compose proporcionado
Nota : En este caso tardará más el arranque al inicializar la configuración
Acceder a la plataforma con el usuario admin utilizado (si es necesario)
Verificar si existe el realm "test"

Acceder a la opción "Clients"
Verificar que existe el cliente "client-postman"

Acceder a la opción "Users"
Verificar que NO existen usuarios

Modo import + persistencia

Arrancar el fichero docker-compose proporcionado
Nota : En este caso tardará más el arranque al inicializar la configuración y la base de datos
Acceder a la plataforma con el usuario admin utilizado (si es necesario)
Verificar si existe el realm "test"
Acceder a la opción "Clients"
Verificar que existe el cliente "client-postman"
Acceder a la opción "Users"
Verificar que NO existen usuarios
Pulsar sobre el botón "Add user" de la cabecera de la tabla
Establecer el id : user-temp
Pulsar sobre el botón "Save"
Verificar que aparece disponible en la tabla de usuarios
Para el fichero docker-compose
Arrancar el fichero docker-compose proporcionado
Acceder a la plataforma con el usuario admin utilizado (si es necesario)
Acceder a la opción "Users"
Verificar que sigue existiendo el usuari "user-temp"
NOTA: Acordaros de borrarlo porque no va a servir para nada

4. Conclusiones

En este caso seguimos añadiendo a las conclusiones anteriores, pero ahora añadimos una cosa muy interesante sabríamos utilizar configuraciones parecidas entre entornos y entre proyectos

Por lo que :

Podríamos aprovisionar y configurar entornos de forma super rápida
Si algo funciona y está bien montado lo podemos utilizar en otros sitios

Espero que os haya gustado y sobre todo que os sea de utilidad.

Si te ha gustado, ¡síguenos en Twitter para estar al día de próximos posts!