IBM TechXchange Japan Business Automation User Group

#JP​
#dba

Japan Business Automation User Groupとは、IBM Cloud Pak for Business Automationおよびそのコンポーネント製品に関して、技術情報を提供およびディスカッションするための日本語ユーザー・グループです。

このページは，以下のURLでもアクセスできます。
http://ibm.biz/JPBizAutomationUG

developerWorks日本で公開されていたBusiness Automation製品の技術文章をお探しの方はこちらから。
旧developerWorks Business Automation日本語版 転載文章一覧

※ 本コミュニティはメンバー同士が相互に情報交換を行う場です。発信は個人の見解であり企業を代表するものではありません。


#AsiaPacific
#IBMCloudPakforBusinessAutomation
#Japan
#CloudPakforBusinessAutomation
 View Only

CP4BA 21.x 導入時問題判別Tips

By Shuichi Saitoh posted Wed January 26, 2022 12:27 AM

  

CP4BA 21.0.x導入時問題判別Tips

この記事について

この記事は IBM Cloud Pak for Business Automation (CP4BA) 21.0.1.2 のEnterprise構成での導入を行った際に遭遇した導入時のエラーとその問題判別におけるTipsをまとめたものである。

内容は CP4BA 21.0.x の任意のバージョンにも同様に適用可能であるが、それ以前の 20.0.x バージョンや異なるバージョン (まだリリースされていない 22.x バージョンなど) には適用できない可能性がある。

Notice: この記事に含まれる情報は可能な限り正確を期しているが、日本アイ・ビー・エム株式会社の正式なレビューを受けておらず、当資料に記載された内容に関して日本アイ・ビー・エム株式会社は何ら保証するものではない。従って、この情報の利用またはこれらの技法の実施はひとえに使用者の責任において為されるものであり、資料の内容によって受けたいかなる被害に関しても一切の補償をするものではない。

 

はじめに：トラブルシューティングドキュメントの確認

CP4BAの導入を行う際、または導入に関するトラブルに遭遇した場合は、まず以下のドキュメントは最初に確認して、Operatorがどのように構成されているのか、そして問題判別において収集するべき要素を確認する。

またよくある失敗のケースに対する対応および問題判別のために収集すべき情報についての説明を確認する。

 

IBM Cloud Paks for Business Automation 21.0.x – Trouble Shooting

https://www.ibm.com/docs/en/cloud-paks/cp-biz-automation/21.0.x?topic=automation-troubleshooting

 

Enterprise構成における導入失敗の要因の理解と対応の確認

Enterprise導入がうまくいかない要因は様々なものがあるが、以下に一般的な要因を取り上げる。それぞれの状況において、問題の確認方法や対応方法が変わってくる。問題確認方法のなかで特にOperatorログの確認については上記のトラブルシューティング文書に加えて、追加のTipsを後述するため合わせて参照いただきたい。

 

ICP4ACluster CR(Custom Resource)定義における構成不足あるいは記述内容のエラー

必須項目が入っていないなど、YAMLの構文としては正しいが、必要な項目が不足しているといったような不備がある場合、ICP4AClusterカスタムリソースの適用は成功するもののOperatorのリコンサイルループの途中で失敗し、コンポーネントの k8s Deploymentのリソース適用やコンテナの起動までも行かないケースがある。

OpenShiftのコンソールなどでevent やPodの状況だけを見ていてもこの問題に該当しているかどうかはわからないため、Operatorのログを確認する必要がある。

 

例: FileNet CPEのデータソース設定においてssl_enable: オプションを true に指定しているにもかかわらずTLS証明書のシークレット名を指定しなかった場合、以下のようなエラーがOperatorのログに出力されて、コンポーネントの導入が中断される。

 

fatal: [localhost]: FAILED! => {"changed": false, "msg": "DB2 ssl secret name should not be blank when ssl enabled"}

fatal: [localhost]: FAILED! => {"msg": "The task includes an option with an undefined variable. The error was: 'db2_jdbc_name' is undefined\n\nThe error appears to be in '/opt/ansible/roles/common/tasks/fncm/fncm-db2-verify.yml': line 153, column 15, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n              when: op_datasource_configuration.dc_gcd_datasource.dc_hadr_standby_port is defined and op_datasource_configuration.dc_gcd_datasource.dc_hadr_standby_port is not none\n            - name: Verify DB2 standby server connection\n              ^ here\n"}

fatal: [localhost]: FAILED! => {"changed": false, "msg": "DB2 ssl secret name should not be blank when ssl enabled"}

…

 

確認方法

  • Operator ログの確認

コンポーネント設定のシークレットの登録不備、名前指定エラー

登録すべきシークレットが登録されていない。あるいはICP4AClusterリソースに指定したシークレット名と、実際にクラスターに適用されたシークレットの名前が一致していないといったような要因で正しく動作しない。

リコンサイルループの中ではクラスターに実際にシークレットが存在するかをチェックしている場合もあれば、その存在をチェックしていない場合もある。

前者のケースの場合は k8s deployment 構成はクラスターに適用されないため、Operatorのログを確認する必要がある。

後者のケースではコンポーネントを起動するための k8s deployment の定義などはクラスターに適用されるが、シークレットが見つからないことによる構文エラーか、シークレットをPodへマウントできないマウントエラーとしてPod が起動できない形になることが多い。

この問題にあてはまる場合は Pod の数が 0 のまま起動しない、といった振る舞いをすることが多いため Deployment や Pod の状況を随時確認していくことが必要となる。

 

確認方法

  • Operator ログの確認
  • 導入途中の Deployment / Pod の状況の確認

 

コンポーネント設定のシークレットの登録不備、不正文字

シークレットに指定したパスワードの中には利用不能な文字が含まれているというようなケースで正しく動作しない。

たとえば ibm-fncm-secret に ltpaPassword を指定できるが、この値として ";" や "=" などを使用すると正しく構成ができず起動エラーになり動作しない。

インストール・ドキュメントにもこのような制約については必ずしも明記されていない場合があるため、指定するパスワードについては安全のためには数値、大文字小文字、"-" ハイフン くらいにしておくことが無難 (スペースも避けたほうがよい)である。

この問題にあてはまる場合はPodの起動そのものは行われている。ステータスが Ready にならずに再起動を続けるか、起動はしても実際にアクセスすると正常に動作しないという振る舞いになる。

 

確認方法

  • 導入途中の Deployment / Pod の状況の確認
  • コンポーネントのPodのログの確認

 

ICP4ACluster CR定義において指定した前提条件システム(LDAPやDB)への接続エラー (ネットワーク不備)

ネットワーク接続の不備 (例: 名前解決ができない、ファイアーウォールによってクラスター内のPodからのアクセスが遮断されている)によってコンポーネントが前提条件のシステムへと接続できずにエラーとなる。

システムそのものは稼働していても、導入を行っているPCから接続できたとしても、OpenShiftクラスターの中で稼働しているコンテナから接続できるとは限らないため、ファイアーウォールなどを正しく構成する必要があるためこのような問題に遭遇した場合には、デバッグ用のPodをOpenShiftクラスター上で稼働させてネットワークの名前解決や該当するポートへのTCP/IP接続ができるかどうかといったテストを実施する必要がある。

 

確認方法

  • コンポーネントのPodのログの確認

 

ICP4ACluster CR定義において指定した前提条件システム(LDAPやDB)への接続エラー (TLS接続の不備)

TLS接続の不備 (TLSが構成されていない、証明書不足、誤った証明書を使用している、証明書の設定方法が正しくない)によって導入時の構成が正しくできない場合がある。LDAPやDatabaseなどへの接続にTLSが必要となる場合、通常はコンポーネント側に信頼できるサーバー証明書、CAルート証明書などをシークレットを使用して正しく登録しないと接続できない。

 

確認方法

  • コンポーネントのPodのログの確認

 

ICP4ACluster CR定義において指定した前提条件システム(LDAPやDB)への接続エラー (認証情報の不備)

認証情報の不備 (例: LDAPへの接続のためのユーザー、パスワードの誤り、DBへの接続ユーザーの不備) などによって導入時の構成が正しくできない。

認証情報がどのタイミングで使用されるかによって振る舞いが異なる。

例えば、コンポーネントのPodは起動するが、起動の途中でエラーが発生するといったケースや、あるいは実際にアプリケーションへアクセスして利用を開始しようとするときにエラーが発生するといった現象として判明する場合がある。

前者のケースであれば導入自体の失敗として検知されることになるため Operator のログを確認すればよいが、後者の場合は導入自体は正常に完了するものの正常には動作しないという振る舞いをすることになり実際の操作後にコンポーネントのログを確認する必要がある。

 

確認方法

  • Operator ログの確認
  • コンポーネントのPodのログの確認

 

 

ICP4ACluster CR定義において指定した前提条件システム(LDAPやDB)への接続エラー (接続ユーザーの認可/権限の不備/そのほか)

権限の不備 (例: DB接続ユーザーにテーブル作成の権限がない)により導入時の構成が正しくできないといった原因で導入が正常に完了せずにエラーとなるケースがある。

また特殊なケースとして、使用するべきでないユーザー名を使用してしまったというケースもある。実際にあったケースとしては、バックエンドデータベースとしてDB2 on Cloud のデータベースを使用した際に、DB2 on Cloud で自動生成したユーザー名が数値からユーザー名となっており (1123EFDなど)、ユーザー名に合わせたスキーマを生成するSQL文の実行時にエラーになり初期化処理が正常に完了できないといったケースがあった。

その他に前提条件となる設定の不足 (例: DB2のバッファー・プールが正しく設定されておらず、表が作成できない) で同様にエラーとなる場合がある。

このようなケースではCP4BAの導入やコンポーネントの振る舞いとしては認証情報の不備と同様の振る舞いをするが、問題の判別はより困難で、コンポーネントごとの専門知識が必要となる可能性が高い。

 

確認方法

  • Operator ログの確認
  • コンポーネントのPodのログの確認

 

Custom Resource 定義において指定した公開用のサーバー名やURL設定の誤り

外部から CP4BA のシステム環境へ接続するための External TLS接続のURLや設定方法における不備がありコンポーネントの導入や起動に失敗する可能性がある。

  • URLの記述ミス。ポート番号の不正、パスの不正。
  • クラスターの中からはアクセスできないホスト名の指定。

特にOAuth認証に使用するURLに誤りがある場合コンポーネントのセットアップの途中でエラーとなり復帰できなくなる可能性があるためより注意が必要である(OAuth クライアントとしての登録情報が中途半端に残ってしまい修正後の初期化に失敗するなど)

 

導入や導入時の構成に失敗した場合は Operatorのログを確認することでわかるが、導入自体は完了し、実際のコンポーネントへのアクセスの際にエラーとなるケースもある。後者の場合はコンポーネントの詳細ログを確認して問題判別を行う必要がある。

 

確認方法

  • Operator ログの確認
  • コンポーネントのPodのログの確認

 

CP4BAのコンポーネントの間での接続に使用するユーザーの認証情報の不備

コンポーネントの設定における管理ユーザーの情報は、コンポーネント間の連携を構成するために利用されることがあるが、そのIDやパスワードに誤りがあった場合や権限に不足があるような場合はコンポーネント間の連携が正しく構成されずに失敗してしまう可能性がある。特に権限の不足により接続ができないケースではコンポーネントの詳細ログを確認して対応を検討する必要がある。

 

確認方法

  • コンポーネントのPodのログの確認

 

初期化の途中でエラーで停止してしまった際の残骸による継続不能エラー

FileNet CPE (Content Platform Engine) 構成などではリポジトリの初期構成が中途半端に失敗することでどうにも進めなくなることもある。

例えば Global Configuration Database (GCD) の構成の途中で管理ユーザーとして指定したLDAPユーザーに適切な権限がないようなケースでは導入が中断された後もGCDデータベースの構成情報が残ってしまい、CPEのレポジトリへの管理ユーザーでのログインもできずに設定を修正することもできなくなるといったことが起きることがある。

この状況に陥ってしまうと一度対象のデータベーステーブルや構成ファイルを保持する Persistent Volume の内容をクリアして、再導入が必要となる。

 

確認方法

  • コンポーネントのPodのログの確認

 

クラスターのリソース不足による失敗

クラスターのリソースが不足している場合、コンポーネントのPodが正常に動作できない。

  • CPU/Memory不足による起動不能 (PODのスケジュール失敗)
  • CPU/Memory不足によるタイムアウト
  • ストレージの割り当て失敗による起動不能

これらの問題に該当しているかどうかはDeploymentの状況でわかる場合があるが、時にはリソースが全く不足していて deployment の適用も失敗する場合がありその場合はOperatorのログを確認する必要がある。

 

確認方法

  • 導入途中の Deployment / Pod の状況の確認
  • Operator ログの確認

 

Operator ログの確認

Operator のログは oc logs <operator_pod> -f で取得できるがそのままだと非常に大量のログが出力され見ていられるものではない。

また Operator によるリコンサイルループは継続的に動き続けるので、ループの開始時点や終了時点は不明瞭となる。

そのため効率よくOperatorログを確認するためにはいくつかの工夫が必要となる。

  • ログ出力のフィルタリング
  • 最後 (もしくは数回前) のリコンサイルループの取り出しとログ確認
  • 失敗したタスクの検出と確認

 

ログ出力のフィルタリング

oc コマンドラインでログ出力を確認している場合などは、Grepを適宜仕掛けて、不要なログの行を除去することで可視性はやや向上する。

特に問題となるエラーにおいては Ansible 側で表示色を赤に変更するようなログ出力構成となっているため、色表示が可能なコンソールであれば赤字のログが表示された際に中身を注意して確認することで多少は効率的にできる。

 

 

# set namespace (change as your configuration)

CP4BA_NS=cp4ba

# get operator pod name

operator_pod_name=$(oc get pod -n $CP4BA_NS |grep ibm-cp4a-operator | awk '{print $1}')

# watch log removing 

oc logs $operator_pod_name -n $CP4BA_NS -f --since=0s | grep -v "Skipping cache lookup" | grep -v "Ansible Task StdOut" | grep -v "logging_event_handler" | grep -v "Cache miss:" | grep -v "Read object from cache" | grep -v "^------------" | grep -v "no_log: true" | grep -v "^$"

 

最後 (もしくは数回前) のリコンサイルループの取り出しとログ確認

Operator はずっと動き続けており、ICP4ACluster リソースの変更を確認し続けているため、operator Pod のログも停止せずに動き続ける。

導入するコンポーネントの構成にもよるが、初回のリコンサイルループなどはかなりの時間がかかる (1時間以上) ため、ログを最初から最後を見続けるというよりも、何らか失敗が発生した場合に実際に失敗した リコンサイルループの1回分の出力を取り出して確認するほうが良い。

その際には最後に完了したリコンサイルループのログにエラーの原因が含まれているとは限らないことに注意する。

例えば以下のようなケースの場合、真の原因は初回のリコンサイルループのログに含まれているが、最新の完了ログ（3回目のリコンサイルループ）には別のエラーが記録されていることになり真の原因の判別が難しくなる。

  • 初回のループ：設定の不備により失敗。一部のコンポーネントの初期化が中途半端な状態で中断された。導入は完了していない。
  • 2回目のループ：設定の不備はそのままで再度実行される。初回のループの処理の過程で中途半端なデータが残っていることが原因で、初回のループとは異なるエラーが発生して中断。導入は完了しない。
  • 3回目のループ：設定の不備はそのままで再度実行される。2回目と同様のエラーが発生して中断。導入は完了しない。
  • 4回目のループ：実行中 ...

 

例: 最後に完了したリコンサイルループ (もしくは数回前の指定したリコンサイルループ)のログ(標準出力)をローカルの ./stdout ファイルに取り出す場合

# set namespace (change)

CP4BA_NS=cp4ba

# get operator pod name and deployment name

deployment_name=$(oc get icp4acluster -n $CP4BA_NS | awk '{print $1}' | grep -v "NAME")

operator_pod_name=$(oc get pod -n $CP4BA_NS |grep ibm-cp4a-operator | awk '{print $1}')

# copy standard output of the latest (completed) reconcile loop

oc cp -n $CP4BA_NS $operator_pod_name:/logs/$operator_pod_name/ansible-operator/runner/icp4a.ibm.com/v1/ICP4ACluster/${CP4BA_NS}/${deployment_name}/artifacts/latest/stdout ./stdout

 

# or find (saved) logs for 10 latest reconcile loops and pickup log for specific loop

oc exec -n $CP4BA_NS $operator_pod_name -- ls -la /logs/$operator_pod_name/ansible-operator/runner/icp4a.ibm.com/v1/ICP4ACluster/${CP4BA_NS}/${deployment_name}/artifacts/

oc cp -n $CP4BA_NS $operator_pod_name:/logs/$operator_pod_name/ansible-operator/runner/icp4a.ibm.com/v1/ICP4ACluster/${CP4BA_NS}/${deployment_name}/artifacts/<timestamp...>/stdout ./stdout

 

失敗したタスクの検出と確認

多くのケースでは、処理に失敗した場合 "fatal" や "FAILED" の文字列とともに stdout にエラーが出力されるため、どのタスクの処理に対するもの何のかを含めて grep 検索することで誤りのある要素を見つけることができる場合がある。

-B オプションで、fatal や FAILEDの文字列の前4, 5行程度を取り出すことで、関連する Ansible Task も出力されるため、どの定義に関連するものかのヒントとなりうる。

 

$ cat ./stdout | grep fatal -B 4

TASK [FNCM : Create CPE Deployment] ********************************************

task path: /opt/ansible/roles/FNCM/tasks/cpe/cpe-deploy.yml:18

Tuesday 13 July 2021  05:34:16 +0000 (0:00:00.209)       0:09:17.441 **********

redirecting (type: modules) ansible.builtin.k8s to community.kubernetes.k8s

fatal: [localhost]: FAILED! => {"changed": false, "error": 422, "msg": "Failed to patch object: b'{\"kind\":\"Status\",\"apiVersion\":\"v1\",\"metadata\":{},\"status\":\"Failure\",\"message\":\"Deployment.apps \\\\\"icp4adeploy-cpe-deploy\\\\\" is invalid: spec.template.spec.containers[0].volumeMounts[9].mountPath: Required value\",\"reason\":\"Invalid\",\"details\":{\"name\":\"icp4adeploy-cpe-deploy\",\"group\":\"apps\",\"kind\":\"Deployment\",\"causes\":[{\"reason\":\"FieldValueRequired\",\"message\":\"Required value\",\"field\":\"spec.template.spec.containers[0].volumeMounts[9].mountPath\"}]},\"code\":422}\\n'", "reason": "Unprocessable Entity", "status": 422}

--

TASK [FNCM : Create CMIS Deployment] *******************************************

task path: /opt/ansible/roles/FNCM/tasks/cmis/cmis-deploy.yml:18

Tuesday 13 July 2021  05:37:58 +0000 (0:00:00.123)       0:12:58.950 **********

redirecting (type: modules) ansible.builtin.k8s to community.kubernetes.k8s

fatal: [localhost]: FAILED! => {"changed": false, "error": 422, "msg": "Failed to patch object: b'{\"kind\":\"Status\",\"apiVersion\":\"v1\",\"metadata\":{},\"status\":\"Failure\",\"message\":\"Deployment.apps \\\\\"icp4adeploy-cmis-deploy\\\\\" is invalid: spec.template.spec.containers[0].volumeMounts[2].mountPath: Required value\",\"reason\":\"Invalid\",\"details\":{\"name\":\"icp4adeploy-cmis-deploy\",\"group\":\"apps\",\"kind\":\"Deployment\",\"causes\":[{\"reason\":\"FieldValueRequired\",\"message\":\"Required value\",\"field\":\"spec.template.spec.containers[0].volumeMounts[2].mountPath\"}]},\"code\":422}\\n'", "reason": "Unprocessable Entity", "status": 422}

--

 

.......省略......

 

 

導入途中の Deployment / Pod の状況の確認

OpenShift の Webコンソールで CP4BA 導入先のネームスペースのイベントを確認し、Pod の作成やエラーの通知などを確認する。

一部のPodについては数回エラーになることが正常動作である（依存コンポーネントが起動するまでループしている）ケースもあるため、起動しないPodやエラーになったPodがあるからといって構成にエラーがあるとは一概には言い切れない点には注意する。

 

コンポーネントのPodのログの確認

OpenShiftのコマンドで Pod のログ、コンテナのログ（標準出力/標準エラー出力）を確認することはできる。

ただし構成のエラーによって正常にPodやコンテナの起動が完了せずに、再起動を繰り返し続けるような場合は、 Pod が削除されそれにともなってログも削除されてしまう可能性がある。

OpenShiftクラスターに対して外部のログ集約ソリューションが構成されている場合はログ集約ソリューションにてログを確認することも一つの方法である。

 

おわりに

この記事ではCP4BAのEnterprise構成における導入時の注意点と問題判別のTipsを紹介した。

導入失敗の要因で取り上げた要因の大部分は、ICP4AClusterリソースを適用する前の事前チェックを強化することにより検知可能となると考えられるため、チェックの強化方法やチェックスクリプトの開発などを検討していきたい。


#CloudPakforBusinessAutomation
0 comments
32 views

Permalink