Ansible Keycloak ロール

このロールは、システム管理されたシステムに Keycloak をデプロイするために設計されており、テストや開発の目的で使用されます。このロールは、ターゲットシステムに公式の Keycloak ZIP アーカイブをダウンロードしてインストールします。

Keycloak サーバーは keycloak という名前の systemd サービスとして設定され、keycloak システムユーザーとして実行されます。このロールは、システムユーザーおよびサービスの作成を処理します。

このロールは、初期の Keycloak サーバー構成のいくつかも処理します。これには、リッスンするポートの設定、初期管理ユーザーの作成、および自己署名または提供された証明書を介した TLS の設定が含まれます。ファイアウォールの設定も処理されます。

使用方法

興味のある TLS シナリオのプレイブックを選択してください。このリポジトリには、以下の例のプレイブックが含まれています：

• tls-self-signed.yml - 自動生成された自己署名証明書による TLS
• tls-cert-key.yml - 提供された cert/key ファイルによる TLS
• tls-pkcs12.yml - 提供された PKCS12 バンドルによる TLS

すべての例のプレイブックは、セキュリティに敏感な変数のために ansible-vault を使用しています。例では、すべての秘密に password を使用しています。新しい秘密は生成し、プレイブックに更新してハードコードされた例を使用しないようにしてください。この手順は、例のプレイブックのコメントに記載されています。

選択したプレイブックを実行するには、次のように --ask-vault-pass オプションを追加してください：

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

ターゲットシステムに同じバージョンの 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 のバージョンは、次の変数を設定することで選択できます。これは 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: 構成ファイルで実行される各コマンドが完了するまで待つ秒数。

上記以外の他の変数デフォルトのリストは 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/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 は、リポジトリのトップレベルディレクトリの名前が git リポジトリの名前と一致する必要はありません。クローンしたリポジトリのディレクトリ名がリポジトリ名と異なっていても、すべての git 操作は予想通りに機能します。なぜなら、リポジトリ URL が .git/config に remote として指定されているからです。

テストは、virtualenv に molecule をインストールすることで最適に行うことができます：

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

注意: virtualenv ディレクトリを .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

テストを実行するためには、docker コマンドを使用して sudo なしで実行するための権限が必要です。通常は、システムの 'docker' グループにユーザーを追加することで行います。

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

# グループメンバーシップは新しいログインセッションを作成するときに評価されます。
# ログアウトして再度ログインしない限り、現在のログインセッションで `newgrp` を使用して `docker` グループのメンバーシップを追加する必要があります。
$ newgrp docker

さらに、SELinux を使用するプラットフォームでは python-libselinux に関する課題があります。virtualenv を使用している場合、SELinux の Python モジュールが virtualenv に存在することを確認する必要があります。これは、Ansible コントローラーホストとターゲットホストでインストールされていても、ローカルホストに委任されるタスクの一部は virtualenv を使用します。SELinux モジュールは pip でインストールできません。これに対する回避策は、システムの site-packages ディレクトリから selinux ディレクトリ全体を virtualenv の site-packages ディレクトリにコピーすることです。また、site-packages ディレクトリから selinux.so バイナリファイルをコピーする必要があります（selinux ディレクトリの中にはありません）。selinux.so の名前は Python2 と Python3 で異なります。

Python2 では .so のベース名は _selinux.so であり、Python 2.7 の x86_64 では次のようになります：

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

Python3 では、ベース名に cpython、Python バージョン、アーキテクチャ、OS を追加され、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

ヒント: molecule コマンドに --debug を追加すると、問題の診断に役立つことがあります。また、ログファイルに出力をキャプチャすることもできます。これを行う場合は、次のようにすることをお勧めします：

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

デフォルトでは、テストターゲットは Docker Hub からの最新の centos イメージになります。異なるイメージ/タグでテストするには、次のようにします：

$ MOLECULE_DISTRO="fedora:28" molecule test

TODO

• ansible-freeipa を使用して Keycloak サービスを作成し、証明書を取得する例プレイブックを追加する
• keycloak_client モジュールを使用してレルム/クライアントを作成する例プレイブックを追加する
• SSSD プロバイダーを介して Keycloak 用のアイデンティティバックエンドとして IdM を構成する機能を追加する