AWS ParallelCluster クラスター作成時のトラブルシューティング基礎知識
AWS ParallelCluster でクラスター作成に失敗したときのエラー切り分けで個人的によく確認する箇所をまとめました。
前提となる AWS ParallelCluster の基本的な知識がある程度必要になります。前半にクラスター作成の基礎知識をまとめ、後半で Tips を載せています。
対象の AWS ParallelCluster のバージョン
AWS ParallelCluster 3.0.0 〜 3.2.0（現時点の最新）を対象としています。
クラスター作成の基礎知識
クラスターを作成するには YAML 形式のクラスターのコンフィグを作成しpclsuter create-clusterコマンドを実行することでクラスター環境が作成されます。
クラスターが作成されるまでの過程
クラスターのインフラ部分は CloudFormation からデプロイされています。EC2（ヘッドノード、コンピュートノード）、セキュリティグループなどの AWS 上のリソースは CloudFormation から作成されています。正確には AWS CDK を利用しており、pcluster create-clusterを実行すると AWS CDK が CloudFormation テンプレートを生成し、生成された CloudFormation をテンプレートを実行し各種リソースを作成しています。
ヘッドノード、コンピュートノードの EC2 の OS、ミドルウェアのセットアップ方法は2パターンあります。 ParallelCluster の AMI として Slurm, OpenMPI, CUDA などがインストール・セットアップ済みとなっているものと、構成管理ツールの Chef で C2 起動時に各種セットアップ作業が行われています。
Chef の Recipe を我々ユーザーが直接書き換えることはありません。YAML 形式のクラスターのコンフィグファイルで定義した内容をよしなに解釈し Chef で実行してくれています。たとえばクラスターのコンフィグで指定した EFS, FSx シリーズなどの外部ストレージをマウントのため、/etc/fstabに設定追加処理が行われています。
EC2 起動時 Chef を実行するために EC2 の UserData を利用しており、UserData で実行する一連の内容（スクリプト）は CloudFormation のテンプレートで定義されています。クラスターのインフラも、ミドルウェアのセットアップのどちらも CloudFormation で管理されていると言えるかもしれません。
ログの保存先
EC2（ヘッドノード、コンピュートノード）のログで ParallelCluster の処理に関するログも/var/log配下に保存されています。ログファイル名と、ログの内容についてはKey logsを参照ください。
デフォルトで CloudWatch Logs にも同じログを保存されています。EC2 にログインしなくても、AWS のマネージメントコンソールからログの確認ができます。また AWS ParallelCluster Manager からもログを確認できます。ヘッドノードのログと、コンピュートノードのログを明確に分けて表示してくれるため、個人的には確認しやすく調査ときに重宝しています。
トラブルシューティングガイド
有用なドキュメント類を紹介します。
AWS ParallelCluster のトラブルシューティングガイドです。
GitHub の Issue で同事象の報告がないかをよく確認しています。
GitHub の Wiki の Known Issue には既知のエラーに対するワークアラウンドが記載されています。アップデートで改修されいく傾向がありますが改修までの暫定対処として有効です。
AWS re:Post もたまに確認しています。投稿数は少ないです。
Tips
pcluster create-clusterコマンドで新規クラスターを作成したけど、クラスターの作成に失敗した ≒ ヘッドノード（EC2）が起動できないときの切り分けの勘所です。
pcluster create-cluster -n [ClusterName] -c [ConfigName]
バリデーションと DryRun
コンフィグの書式のミスであれば多くのケースはpcluster create-clusterコマンド実行時のバリデーションチェックで気付けます。
先にまとめ
--dryrun trueオプションを有効化して実行し、バリデーションの結果を事前確認するのがオススメです。
pcluster create-cluster -n [ClusterName] -c [ClusterConfig] --dryrun true
存在しない OS を指定した
OS の指定を ParallelCluster 3.2 では非対応の Ubuntu 22.04 LTS を指定したときの出力例です。
レベルがERRORですとクラスターの作成処理は実行されません。対応している OS に修正して再度作成コマンドを実行することになります。
{
"configurationValidationErrors": [
{
"level": "ERROR",
"type": "ConfigSchemaValidator",
"message": "[('Image', {'Os': ['Must be one of: alinux2, centos7, ubuntu1804, ubuntu2004.']})]"
}
],
"message": "Invalid cluster configuration."
}
EFA をサポートしているインスタンスで EFA を有効化しなかった
コンピュートノードにc5n.18xlargeインスタンスを指定しました。
EFA を有効化するオプションを明示的に有効化しなかったためWARNINGで検出されました。デフォルト動作としてはERROR以外のレベル（WARNING,INFO）の検出はクラスターの作成処理を中止せずにクラスター作成処理に入ります。
{
"validationMessages": [
{
"level": "WARNING",
"type": "EfaValidator",
"message": "The EC2 instance selected (c5n.18xlarge) supports enhanced networking capabilities using Elastic Fabric Adapter (EFA). EFA enables you to run applications requiring high levels of inter-node communications at scale on AWS at no additional charge. You can update the cluster's configuration to enable EFA (https://docs.aws.amazon.com/parallelcluster/latest/ug/efa-v3.html)"
}
],
"message": "Request would have succeeded, but DryRun flag is set."
}
エラーレベルによるクラスター作成、中止の判定は--validation-failure-levelオプションで変更できます。
--validation-failure-level {INFO,WARNING,ERROR} Specifies the minimum validation level that will cause the creation to fail. (Defaults to ERROR.) pcluster create-cluster - AWS ParallelCluster
だけど、オススメは DryRun オプションを有効化（--dryrun true）して事前に結果を確認することです。こちらの指定の方がお手軽だと思っています。
pcluster create-cluster -n [ClusterName] -c [ClusterConfig] --dryrun true
CloudFormation のスタックを確認
pcluster create-clusterコマンド実行後は CloudFormation のスタックを確認することで進行状況や詳細を確認できます。
先にまとめ
原因調査のためスタックのロールバックを無効化するためには--rollback-on-failure falseを付与してクラスターを作成します。
pcluster create-cluster -n [ClusterName] -c [ClusterConfig] --rollback-on-failure false
--rollback-on-failure falseを付与したクラスター作成のスタックのステータスはCREATE_FAILEDで止まり、オプションを付与していないスタックはROLLEBACK_COMPLITEとなります。
CREATE_FAILEDのあとにロールバックが走らず、エラーのあったところまで進行した状態のまま残り、残されたリソースを確認し原因調査ができます。
CloudFormation のロールバック動作については以下のリンクを参照ください。
スタックを確認する
マネージメントコンソールから CloudFormation を開き、スタックを確認するとリソース作成の進行状況を確認できます。
イベントタブからデプロイ中のどの段階でリソース失敗したのか確認できます。被疑リソースの切り分けに利用できます。
クラスター作成時に失敗した
デプロイの失敗するとデフォルトの動作はロールバックです。作成していた、作成中だったリソースをすべて削除します。
ステータスCREATE_FAILEDの箇所はヘッドノードに関することだと読み取れます。直後、ステータスROLLBACK_IN_PROGRESSになりロールバックがはじまっています。
最終的にROLLEBACK_COMPLITEとなり、作成していたリソースがすべて削除されました。
疑わしいヘッドノード（EC2）が削除されています。OS 上でなにがあったか調査したいときに残された情報が限られています。今回のケースですと CloudWatch Logs にログは保存されていませんでした。EC2 が起動すらできなかったのか、EC2 上で問題があったのかもわかりません。
そこで、原因調査のためにロールバックを無効化したクラスターを作成方法があります。
ロールバック無効化オプションを有効化
--rollback-on-failure falseを付与してクラスターを作成します。すると、CREATE_FAILEDのあとにロールバックが走らず待機します。
pcluster create-cluster -n UbuntuDemoClusterTest2 -c ubuntu-demo-20220913-NG.yaml --rollback-on-failure false
CloudWatch Logs を確認しました。ログストリームは生成されておらずログは保存されていません。
EC2 は起動までできていたようで起動したまま削除されずに残っています。これで EC2 にログインして原因調査を行えます。
ヘッドノードのログ確認
ParallelCluster の処理に関するログは/var/log配下に保存されています。ログファイル名と、ログの内容についてはKey logsを参照ください。
よく確認するログファイル
クラスター作成時にヘッドノードの起因のケースは以下のログファイルを確認しています。
/var/log/cfn-init.log/var/log/cloud-init-output.log/var/log/chef-client.log
よくありがちなトラブル
ヘッドノードの設定を流し込むための Post Install 処理（postinstal.sh）で失敗しています。/var/log/cfn-init.log,/var/log/cloud-init-output.logを確認するとスクリプトの実行処理時の標準出力が記録されており内容を確認して切り分けます。
スクリプト内でyum install hoge -yと記す必要があるところ-yを抜かしてしまい、インタラクティブに実行され返答待ちのままタイムアウトしてクラスター作成の失敗することがあります。
おわりに
クラスター作成時のトラブルシューティングだけでもなかなかの文量になりました。他にも有効な切り分け方法、フィードバックあれば直接ご連絡いただけると嬉しいです。
