Ansible Keycloak 角色

此角色旨在在系统管理的systemd系统上部署Keycloak，以进行测试和开发。该角色将在目标系统上从官方下载的Keycloak zip文件安装Keycloak。

Keycloak服务器将配置为名为keycloak的systemd服务，运行为keycloak系统用户。该角色将处理系统用户和服务的创建。

此角色还处理一些初始Keycloak服务器配置，包括配置监听的端口、创建初始管理员用户以及通过自签名或提供的证书配置TLS。防火墙配置也会被处理。

使用方法

选择一个您感兴趣的TLS场景的剧本。此存储库中包含以下示例剧本：

• tls-self-signed.yml - 使用自动生成的自签名证书的TLS
• tls-cert-key.yml - 使用提供的证书/密钥文件的TLS
• tls-pkcs12.yml - 使用提供的PKCS12捆绑包的TLS

所有示例剧本使用ansible-vault来处理安全敏感的变量。示例中使用password作为所有密钥，包括保管库密码本身。新的密钥应生成并更新到剧本中，以避免使用硬编码示例。相关说明在示例剧本的评论中。

要执行选择的剧本，请确保添加--ask-vault-pass选项，如下所示：

ansible-playbook --ask-vault-pass -i <inventory/host list> <playbook>

如果目标系统上已存在相同版本的Keycloak部署，则剧本将失败，以防止丢失Keycloak数据库中的数据。可以设置强制变量来覆盖现有部署。此变量可以在剧本中设置，也可以在命令行以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版本。此变量将用于确定从https://www.keycloak.org/downloads.html使用的下载URL：

• 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）

对于使用PKCS12捆绑包的TLS，必须提供以下附加变量：

• 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服务器密钥文件路径）

注意：用于创建Keycloak密钥库的源TLS文件（keycloak_tls_pkcs12、keycloak_tls_cert、keycloak_tls_key）可以位于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会期望在ANSIBLE_ROLES_PATH中找到名为my_role的目录，里面具有类似于以下的子目录结构：

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

按照惯例，大多数Galaxy角色都创建在其顶层目录包含上述角色子目录的git存储库中，因此克隆git存储时创建的目录名称就是角色名称。使用上述示例，git存储库将名为my_role。然而，大多数git存储库并不以与其Galaxy角色名称相同的名称命名。如果您尝试在默认存储库名称的git树顶层运行molecule test命令，将会出现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

因此，molecule将使用的角色名称是nkinder.keycloak。

所以，要克隆此存储库，请执行以下操作：

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

当然，如果你是从github的分支克隆，将需要相应地调整存储库URL。

您需要进入克隆的git存储库：

$ cd nkinder.keycloak

当你从git存储库的顶层目录运行molecule test时，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不需要repo的顶层目录名称与其git存储库名称匹配。即使克隆的存储库的目录名称会与存储库名称不同，所有git操作仍将如预期正常工作，因为已在.git/config中将repo URL指定为remote。

通过在虚拟环境中安装molecule进行最佳测试：

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

注意：您必须将虚拟环境目录命名为.venv，因为molecule期望如此。

警告：如果您已经将存储库克隆为存储库名称而非角色名称，您可以重命名存储库目录，但是如果在重命名之前创建了.venv，您必须删除.venv并重新创建它，因为虚拟环境将嵌入旧的路径名称。

默认情况下，molecule使用docker构建和运行测试镜像。您需要安装docker并运行docker守护进程：

# 安装docker包
$ sudo dnf install docker

# 启动Docker服务：
$ sudo systemctl start docker

# 验证Docker是否正确安装并运行，方法是运行Docker hello-world镜像。

$ sudo docker run hello-world

# 可选的在启动时启动Docker守护进程
$ sudo systemctl enable docker

必须以可以在不使用sudo的情况下运行docker命令的用户身份运行测试。通常通过将您的用户添加到系统的'docker'组来实现这一点。

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

# 组成员资格在您创建新登录会话时被评估。除非您重新登录，否则需要使用`newgrp`
# 来在当前登录会话中添加您的`docker`组成员资格。
$ newgrp docker

此外，对于使用SELinux的平台，python-libselinux存在一些挑战。如果您使用虚拟环境，您需要确保SELinux python模块在虚拟环境中可用。即使它已安装在您的ansible控制主机和目标主机上，一些委派给localhost的任务将使用虚拟环境。SELinux模块不能通过pip安装。一个解决方法是将系统site-packages位置中的整个selinux目录（在x86_64上的路径为/usr/lib64/$PY_VERSION/site-packages/selinux）复制到虚拟环境的site-packages目录中。还需要从site-packages目录中复制selinux.so二进制文件（它不在selinux目录内部）。selinux.so的名称在Python2和Python3之间不同。

在Python2中，.so文件的基本名称为_selinux.so，对于基于x86_64的Python 2.7，它将是：

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

在Python3中，.so文件的基本名称附加了cpython，python版本，架构和操作系统，对于基于x86_64的Python 3.7，它看起来像这样：

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

一旦您的虚拟环境设置正确，可以运行测试的命令如下：

$ cd nkinder.keycloak # 您的存储库，其目录名称与Galaxy角色名称匹配
$ molecule test

提示：在molecule命令中添加--debug可以帮助诊断问题，并捕获输出到日志文件中，您可能想这样做：

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

默认情况下，测试目标将是来自Docker Hub的最新centos镜像。您可以测试其他镜像/标签，如下所示：

$ MOLECULE_DISTRO="fedora:28" molecule test

待办事项

• 添加示例剧本，使用ansible-freeipa创建Keycloak服务并获取证书
• 添加示例剧本，使用keycloak_client模块创建领域/客户端
• 添加通过SSSD提供程序将IdM配置为Keycloak的身份后端的能力