Роль Ansible для Keycloak

Эта роль предназначена для развертывания Keycloak на системе с управлением systemd в целях тестирования и разработки. Роль установит Keycloak из официального загруженного zip-архива Keycloak на целевой системе.

Сервер Keycloak будет настроен как сервис systemd с именем keycloak, работающий под системой пользователя keycloak. Роль будет обрабатывать создание системного пользователя и сервиса.

Эта роль также выполняет некоторые начальные настройки сервера Keycloak. Это включает в себя настройку портов для прослушивания, создание начального admin-пользователя и настройку TLS с помощью самоподписанных или предоставленных сертификатов. Также настраивается фаервол.

Использование

Выберите плейбук для интересующего вас сценария TLS. В этом репозитории включены следующие примерные плейбуки:

• tls-self-signed.yml - TLS через автоматически сгенерированный самоподписанный сертификат
• tls-cert-key.yml - TLS через предоставленные файлы сертификата/ключа
• tls-pkcs12.yml - TLS через предоставленный пакет PKCS12

Все примерные плейбуки используют ansible-vault для защиты чувствительных переменных. В примерах используется password для всех секретов, включая сам пароль для хранилища. Новые секреты должны быть сгенерированы и обновлены в плейбуках, чтобы избежать использования жестко закодированного примера. Инструкции по этому находятся в комментариях в примерных плейбуках.

Чтобы выполнить выбранный вами плейбук, обязательно добавьте опцию --ask-vault-pass, как в этом примере:

ansible-playbook --ask-vault-pass -i <инвентарный файл/список хостов> <плейбук>

Если развертывание той же версии Keycloak уже существует на целевой системе, плейбук завершится ошибкой, чтобы предотвратить потерю данных в базе данных Keycloak. Можно установить переменную force, чтобы перезаписать существующее развертывание. Это можно сделать либо в плейбуке, либо добавить в командную строку как extra-var:

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

Управление местоположением архива Keycloak

По умолчанию архив Keycloak будет загружен на локальную систему, с которой запускается плейбук. Он будет располагаться в директории, указанной переменной keycloak_local_download_dest. Когда архив будет извлечён на целевой системе, он будет прочитан с локальной системы и файлы будут созданы на целевой системе. Это поведение имеет преимущество в том, что архив загружается только один раз и не хранится на целевой системе, но оно влечет за собой сетевые затраты на повторную передачу содержимого архива для каждой целевой системы в процессе извлечения. Если у вас медленное сетевое соединение для загрузки на хосте, запускающем плейбук, не локальное извлечение может быть неприемлемым.

Альтернативно, у вас есть возможность загрузить архив непосредственно на целевую систему и извлечь его там, это контролируется переменной keycloak_archive_on_target. Это имеет преимущество в том, что данные архива передаются только один раз. Извлечение архива будет быстрым, так как нет сетевого трафика во время извлечения, поскольку все данные локальны для целевой системы. Однако архив останется на целевой системе после извлечения.

Чтобы изменить местоположение архива в командной строке, добавьте этот аргумент к вашей команде плейбука:

-e "{keycloak_archive_on_target: True}"

Переменные

Вы можете выбрать, какую версию Keycloak установить, задав следующую переменную. Она будет использоваться для определения URL-адреса для загрузки с https://www.keycloak.org/downloads.html:

• keycloak_version (по умолчанию: 4.8.2.Final)

Следующую переменную всегда необходимо предоставить, так как роль не задает значение по умолчанию:

• keycloak_admin_password (используйте ansible-vault для защиты)

Вы можете выбрать имя админ-аккаунта, отличное от значения по умолчанию, задав следующую переменную:

• keycloak_admin_user (по умолчанию: admin)

Чтобы настроить интерфейс и порты, на которых сервер Keycloak будет слушать, можно задать следующие переменные:

• keycloak_bind_address (по умолчанию: 0.0.0.0)
• keycloak_http_port (по умолчанию: 8080)
• keycloak_https_port (по умолчанию: 8443)

Для TLS через пакет PKCS12 необходимо предоставить следующие дополнительные переменные:

• keycloak_tls_pkcs12 (путь к пакету PKCS12)
• keycloak_tls_pkcs12_passphrase (используйте ansible-vault для защиты)
• keycloak_tls_pkcs12_alias (имя ключа/сертификата в keycloak_tls_pkcs12)

Для TLS через файлы сертификата/ключа необходимо предоставить следующие дополнительные переменные:

• keycloak_tls_cert (путь к файлу сертификата сервера TLS)
• keycloak_tls_key (путь к файлу ключа сервера TLS)

ПРИМЕЧАНИЕ: исходные файлы TLS (keycloak_tls_pkcs12, keycloak_tls_cert, keycloak_tls_key), используемые для создания хранилища ключей Keycloak, могут находиться как на контроллере Ansible (т.е. локально), так и на удаленном целевом хосте. По умолчанию роль предполагает, что исходные файлы TLS являются локальными. Если же исходные файлы TLS находятся на удаленном целевом хосте, установите переменную keycloak_tls_files_on_target в True.

Вы можете управлять значениями тайм-аута с помощью следующих переменных:

keycloak_startup_timeout: Количество секунд, ожидаемых для запуска Keycloak.

keycloak_jboss_config_connect_timeout: Количество миллисекунд, ожидаемых для подключения утилиты настройки jboss к серверу wildfly.

keycloak_jboss_config_command_timeout: Количество секунд, ожидаемых для завершения утилиты настройки jboss каждой команды, выполняемой в конфигурационном файле.

Смотрите roles/keycloak/defaults/main.yml для списка других переменных по умолчанию, которые можно переопределить.

Тестирование

Предоставлены тесты в дереве, которые используют molecule для тестирования роли с использованием контейнеров docker. Эти тесты предназначены для использования в CI, но также могут быть выполнены локально для проверки во время разработки.

Проблема с именем роли

ПРЕДУПРЕЖДЕНИЕ: Для тестирования в дереве имя директории должно совпадать с именем роли Ansible Galaxy

ПРИМЕЧАНИЕ: В этих примерах предполагается, что репозиторий был клонирован в ~/src/

Ansible ожидает, что роль будет иметь определенную структуру директорий. Например, если роль называется my_role, Ansible будет ожидать найти директорию с именем my_role в ANSIBLE_ROLES_PATH с поддиректориями, аналогичными этим:

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

По умолчанию большинство ролей Galaxy создаются в git-репозитории, верхний уровень которого содержит вышеуказанные подпапки для роли, таким образом, директория, созданная при клонировании репозитория git, становится именем роли. Используя приведенный выше пример, репозиторий git будет назван my_role. Однако большинство git-репозиториев не названы идентично именам их ролей Galaxy. Если вы попытаетесь запустить molecule test на верхнем уровне клонированного git-дерева с именем по умолчанию репозитория, вы получите ошибку role not found, похожую на эту:

ERROR! the role 'nkinder.keycloak' was not found in /home/$USER/src/ansible-keycloak/molecule/default/roles:/tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src:/home/$USER/src/ansible-keycloak/molecule/default

The error appears to have been in '/home/$USER/src/ansible-keycloak/molecule/default/playbook.yml': line 6, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:

  roles:
    - role: nkinder.keycloak
      ^ here

Решение этой проблемы простое: при клонировании репозитория git укажите имя директории, которое соответствует имени роли в файле molecule/default/playbook.yml.

Чтобы определить имя роли, Molecule будет использовать, найдите его определение в molecule/default/playbook.yml:

  roles:
    - role: nkinder.keycloak

Следовательно, роль с именем nkinder.keycloak.

Таким образом, чтобы клонировать этот репозиторий, сделайте следующее:

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

Конечно, если вы клонируете из форка на GitHub, вам нужно будет соответствующим образом настроить URL репозитория.

Вам нужно перейти в клонированный git-репозиторий:

$ cd nkinder.keycloak

Когда вы запустите molecule test из верхней директории git-репозитория, Molecule получит путь к текущей рабочей директории и от этого найдет путь к родительской директории, затем установит ANSIBLE_ROLES_PATH, чтобы включить родительскую директорию репозитория роли. Таким образом, когда ansible будет выполнять поиск, он найдет вашу роль по имени директории вашего git-репозитория. Например:

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

Поскольку ansible ищет роль с именем nkinder.keycloak, он будет искать директории, указанные в ANSIBLE_ROLES_PATH, и использовать файлы, найденные в /home/$USER/src/nkinder.keycloak.

ПРИМЕЧАНИЕ: Molecule помещает некоторые файлы во временную директорию на время исполнения теста, это MOLECULE_EPHEMERAL_DIRECTORY, и в наших примерах это /tmp/molecule/ansible-keycloak/default, поэтому первый путь в приведенном выше ANSIBLE_ROLES_PATH.

ПРИМЕЧАНИЕ: Git не требует, чтобы имя директории верхнего уровня совпадало с именем репозитория. Хотя имя директории клонированного репозитория будет отличаться от имени репозитория, все операции git будут работать, как ожидается, поскольку URL репозитория указан как remote в .git/config.

Тестировать лучше всего установив molecule в virtualenv:

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

ПРИМЕЧАНИЕ: Вы должны назвать директорию virtualenv .venv, потому что molecule ожидает это.

ПРЕДУПРЕЖДЕНИЕ: Если вы уже клонировали репозиторий под названием репозитория, а не именем роли, вы можете переименовать директорию репозитория, однако, если вы создали .venv до переименования, вы должны удалить .venv и создать его заново, потому что virtualenv внедрит старые пути.

По умолчанию molecule использует docker для сборки и запуска тестовых образов. Вам нужно установить docker и запустить демон docker:

# Для установки пакета docker
$ sudo dnf install docker

# Чтобы запустить службу Docker, используйте:
$ sudo systemctl start docker

# Проверьте, что Docker был корректно установлен и работает, запустив
# образ hello-world.

$ sudo docker run hello-world

# Чтобы по желанию запустить демон Docker при загрузке
$ sudo systemctl enable docker

Необходимо запускать тесты от пользователя, который имеет право запускать команду docker без использования sudo. Обычно это достигается добавлением вашего пользователя в группу 'docker' на вашей системе.

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

# Членство в группе оценивается при создании новой сессии входа.
# Если вы не выйдете и не войдете снова, вам нужно будет использовать `newgrp`
# чтобы добавить ваше членство в группу `docker` в текущей сессии входа.
$ newgrp docker

Кроме того, существует проблема с python-libselinux на платформах, использующих SELinux. Если вы используете virtualenv, вам нужно убедиться, что модуль python selinux доступен в virtualenv. Даже если он установлен на вашем контроллере Ansible и на целевом хосте, некоторые задачи, делегированные на localhost, будут использовать virtualenv. Модуль selinux не может быть установлен через pip. Обходным решением является копирование всей директории selinux из вашего системного каталога site-packages (/usr/lib64/$PY_VERSION/site-packages/selinux на x86_64) в каталог site-packages virtualenv. Вам также потребуется скопировать двоичный файл selinux.so из каталога site-packages (он не находится внутри директории selinux). Имя selinux.so варьируется между Python2 и Python3.

В Python2 базовое имя .so - _selinux.so, для Python 2.7 на x86_64 это будет:

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

В Python3 базовое имя .so добавляет cpython, версию python, архитектуру и ОС, для Python 3.7 на x86_64 это будет выглядеть так:

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

После правильной настройки вашего virtualenv, тесты можно запустить следующими командами:

$ cd nkinder.keycloak # Ваш репозиторий, директория которого соответствует имени роли Galaxy
$ molecule test

СОВЕТ: Добавление --debug к команде molecule может помочь в диагностике проблем, а также в сохранении вывода в файл журнала, вы можете сделать это так:

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

По умолчанию целевой тест будет последним образом centos из Docker Hub. Вы можете тестировать на другом образе/теге, сделав это:

$ MOLECULE_DISTRO="fedora:28" molecule test`

Задачи в плане

• Добавить пример плейбука, который использует ansible-freeipa для создания сервиса keycloak и получения сертификата
• Добавить пример плейбука, который создает realm/client с использованием модуля keycloak_client
• Добавить возможность конфигурации IdM как источника идентификации для keycloak через провайдер SSSD