Image Builder の問題のトラブルシューティング

EC2 Image Builder はと統合して、イメージビルドの問題 AWS のサービスのトラブルシューティングに役立つモニタリングとトラブルシューティングを行います。Image Builder は、イメージ構築プロセスの各ステップの進行状況を追跡して表示します。さらに、Image Builder は、指定した Amazon S3 の場所にログをエクスポートできます。

高度なトラブルシューティングを行う場合は、「AWS Systems Manager コマンドを実行」を使用して定義済みのコマンドとスクリプトを実行できます。

内容

パイプラインビルドのトラブルシューティング
トラブルシューティングシナリオ

パイプラインビルドのトラブルシューティング

Image Builder パイプラインのビルドが失敗した場合、Image Builder は失敗を説明するエラーメッセージを返します。Image Builder は、次の出力例のような workflow execution ID を含む失敗メッセージでもを返します。


Workflow Execution ID: wf-12345abc-6789-0123-abc4-567890123abc failed with reason: …

Image Builder は、標準のイメージ作成プロセスのランタイムステージ用に定義された一連のステップを通じて、イメージビルドアクションを整理、指示します。プロセスのビルド段階とテスト段階にはそれぞれワークフローが関連付けられています。Image Builder がワークフローを実行して新しいイメージを構築またはテストすると、ランタイムの詳細を追跡するワークフローメタデータリソースが生成されます。

コンテナイメージには、配信中に実行される追加のワークフローがあります。

ワークフローのランタイムインスタンス障害の詳細を調べる

ワークフローのランタイム障害をトラブルシューティングするには、workflow execution ID を使用して GetWorkflowExecution と ListWorkflowStepExecutions API アクションを呼び出すことができます。

ワークフローのランタイムログを確認する

Amazon CloudWatch Logs

Image Builder は、詳細なワークフロー実行ログを以下の Image Builder CloudWatch Logs グループとストリームに公開します。

LogGroup:
```
/aws/imagebuilder/ImageName
```
LogStream (x.x.x/x):
```
ImageVersion/ImageBuildVersion
```
CloudWatch Logs では、フィルタパターンを使用してログデータを検索できます。詳細については、Amazon CloudWatch Logs ユーザーガイドのフィルターパターンを使用したログデータの検索を参照してください。
AWS CloudTrail

アカウントで有効化されている場合、すべてのビルドアクティビティは CloudTrail にも記録されます。CloudTrail イベントは imagebuilder.amazonaws.com ソースでフィルタリングできます。または、実行ログで返される Amazon EC2 インスタンス ID を検索して、パイプライン実行に関する詳細を確認することもできます。
Amazon Simple Storage Service (S3)

インフラストラクチャ設定で S3 バケット名とキー接頭辞を指定した場合、ワークフローステップのランタイムログパスは次のパターンに従います。
```
S3://S3BucketName/KeyPrefix/ImageName/ImageVersion/ImageBuildVersion/WorkflowExecutionId/StepName
```
S3 バケットに送信するログには、イメージビルドプロセス中の EC2 インスタンスでのアクティビティのステップとエラーメッセージが表示されます。ログには、コンポーネントマネージャーからのログ出力、実行されたコンポーネントの定義、インスタンスで実行されたすべてのステップの詳細な出力 (JSON) が含まれます。問題が発生した場合は、application.log から始めてこれらのファイルを確認し、インスタンスの問題の原因を診断する必要があります。

デフォルトでは、パイプラインに障害が発生すると、Image Builder は実行中の Amazon EC2 ビルドまたはテストインスタンスをシャットダウンします。パイプラインが使用するインフラストラクチャ設定リソースのインスタンス設定を変更して、ビルドインスタンスまたはテストインスタンスをトラブルシューティングのために保持することができます。

コンソールでインスタンス設定を変更するには、インフラストラクチャー設定リソースの「トラブルシューティング設定」セクションにある「Terminate instance on failure」チェックボックスをオフにする必要があります。

update-infrastructure-configurationのコマンドを使用して AWS CLIでインスタンス設定を変更することもできます。コマンドが--cli-input-jsonパラメータで参照する JSON ファイルのterminateInstanceOnFailureの値をfalseに設定する。詳細については、「インフラストラクチャ設定を更新する」を参照してください。

トラブルシューティングシナリオ

このセクションには、以下の詳細なトラブルシューティングシナリオが記載されています。

アクセス拒否 — ステータスコード 403
ビルドインスタンスで Systems Manager エージェントの可用性を確認中にビルドがタイムアウトする
Windows セカンダリディスクが起動時にオフライン
CIS で強化されたベースイメージではビルドが失敗する
アサートインベントリ収集が失敗する (Systems Manager 自動化)

シナリオの詳細を表示するには、シナリオのタイトルを選択して展開します。複数のタイトルを同時に展開できます。

説明

パイプラインのビルドが「AccessDenied: アクセス拒否ステータスコード:403」で失敗します。

原因

エラーの原因として以下が考えられます。

インスタンスプロファイルには API やコンポーネントリソースにアクセスするのに必要な権限がありません。
インスタンスプロファイルロールには、Amazon S3 へのロギングに必要な権限がありません。最も一般的には、インスタンスプロファイルロールに S3 バケットの PutObject 権限がない場合に発生します。

ソリューション

原因に応じて、この問題は次のように解決できます。

インスタンスプロファイルに管理ポリシーがない — 不足しているポリシーをインスタンスプロファイルロールに追加してください。次に、パイプラインを再度実行します。
インスタンスプロファイルに S3 バケットの書き込み権限がありません — S3 バケットに書き込むための PutObject 権限を付与するポリシーをインスタンスプロファイルロールに追加します。次に、パイプラインを再度実行します。

説明

パイプラインのビルドは、「status = 'TimedOut'」および「失敗メッセージ = 'ステップがターゲットインスタンス上の Systems Manager エージェントの可用性を確認している間にステップがタイムアウトしました」で失敗します。

原因

エラーの原因として以下が考えられます。

ビルド操作を実行し、コンポーネントを実行するために起動されたインスタンスは、Systems Manager エンドポイントにアクセスできませんでした。
インスタンスプロファイルに必要な権限がありません。

ソリューション

考えられる原因に応じて、この問題は次のように解決できます。

アクセスの問題、プライベートサブネット — プライベートサブネットで構築する場合は、Systems Manager、Image Builder、およびロギングが必要な場合は Amazon S3/CloudWatch 用の PrivateLink エンドポイントをセットアップしていることを確認してください。PrivateLink エンドポイントの設定の詳細については、「を通じて AWS のサービスにアクセスする AWS PrivateLink」を参照してください。
権限がない — 以下の管理ポリシーを Image Builder の IAM サービスリンクロールに追加します。
- EC2InstanceProfileForImageBuilder
- EC2InstanceProfileForImageBuilderECRContainerBuilds
- AmazonSSMManagedInstanceCore
Image Builder サービスリンクロールの詳細については、Image Builder での IAM サービスリンクロールの使用を参照してください。

説明

Image Builder Windows AMI の構築に使用されるインスタンスタイプが AMI からの起動に使用されるインスタンスタイプと一致しない場合、起動時にルート以外のボリュームがオフラインになるという問題が発生する可能性があります。これは主に、ビルドインスタンスが起動インスタンスよりも新しいアーキテクチャを使用している場合に発生します。

次の例は、Image Builder AMI が EC2 Nitro インスタンスタイプで構築され、EC2 Xen インスタンスで起動された場合に何が起こるかを示しています。

ビルドインスタンスタイプ:m5.large (ニトロ)

起動インスタンスタイプ:t2.medium (Xen)


PS C:\Users\Administrator> get-disk
Number  Friendly Name  Serial Number         Health Status  Operational Status  Total Size  Partition Style
------  -------------  -------------         -------------  ------------------  ----------  ---------------
0       AWS PVDISK     vol0abc12d34e567f8a9  Healthy        Online                   30 GB  MBR
1       AWS PVDISK     vol1bcd23e45f678a9b0  Healthy        Offline                   8 GB  MBR

原因

Windows のデフォルト設定により、新しく検出されたディスクは自動的にオンラインになり、フォーマットされません。EC2 でインスタンスタイプが変更されると、Windows はこれを新しいディスクが検出されたものとして扱います。これは、基礎となるドライバーが変更されたためです。

ソリューション

Windows AMI を構築するときには、起動元と同じインスタンスタイプのシステムを使用することをお勧めします。異なるシステムで構築されたインスタンスタイプをインフラストラクチャ設定に含めないでください。指定するインスタンスタイプに Nitro システムを使用しているものがあれば、それらはすべて Nitro システムを使用する必要があります。

Nitro システムに構築されたインスタンスの詳細については、「Amazon EC2 ユーザーガイド」の「Nitro System 上に構築されたインスタンス」を参照してください。

説明

CIS 強化ベースイメージを使用していて、ビルドが失敗する。

原因

/tmpディレクトリがnoexecとして分類されると、Image Builder が失敗する可能性があります。

ソリューション

イメージレシピのworkingDirectoryフィールドで、作業ディレクトリの別の場所を選択してください。詳細については、ImageRecipe データ型の説明を参照してください。

説明

Systems Manager オートメーションでは、AssertInventoryCollectionオートメーションステップが失敗したと表示されます。

原因

あなたまたはあなたの組織は、EC2 インスタンスのインベントリ情報を収集する Systems Manager ステートマネージャーアソシエーションを作成したかもしれません。Image Builder パイプラインで拡張イメージメタデータ収集が有効になっている場合 (これがデフォルト)、Image Builder はビルドインスタンスの新しいインベントリ関連付けを作成しようとします。ただし、Systems Manager では、管理対象インスタンスに複数のインベントリを関連付けることはできません。また、関連付けが既に存在する場合も、新しい関連付けは許可されません。これにより操作は失敗し、パイプラインの構築も失敗します。

ソリューション

この問題を解決するには、次のいずれかのメソッドを使って、「拡張イメージメタデータ収集」をオフにします。

コンソールのイメージパイプラインを更新して、「拡張メタデータ収集を有効にする」チェックボックスをオフにします。変更を保存し、パイプラインビルドを実行します。

EC2 Image Builder コンソールを使用した AMI イメージパイプラインの更新の詳細については、コンソールでの AMI イメージパイプラインの更新を参照してください。EC2 Image Builder コンソールを使用してコンテナイメージパイプラインを更新する方法の詳細については、コンソールでのコンテナイメージパイプラインの更新を参照してください。

update-image-pipelineのコマンドを使用して AWS CLIでイメージパイプラインを更新することもできます。これを行うには、JSON ファイルに EnhancedImageMetadataEnabledプロパティを含めて、falseに設定します。以下の例では、プロパティがfalseに設定されている。


{
    "name": "MyWindows2019Pipeline",
    "description": "Builds Windows 2019 Images",
    "enhancedImageMetadataEnabled": false,
    "imageRecipeArn": "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03",
    "infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration",
    "distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration",
    "imageTestsConfiguration": {
        "imageTestsEnabled": true,
        "timeoutMinutes": 60
    },
    "schedule": {
        "scheduleExpression": "cron(0 0 * * SUN *)",
        "pipelineExecutionStartCondition": "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE"
    },
    "status": "ENABLED"
}

新しいパイプラインでこの現象が発生しないようにするには、EC2 Image Builder コンソールを使用して新しいパイプラインを作成するときに Enable enhanced metadata collection チェックボックスをオフにするか、 AWS CLIを使用してパイプラインを作成するときに JSON ファイルのEnhancedImageMetadataEnabledプロパティの値をfalseに設定します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ベストプラクティス

ドキュメント履歴