EC2Image 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 がワークフローを実行して新しいイメージを構築またはテストすると、ランタイムの詳細を追跡するワークフローメタデータリソースが生成されます。

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

ワークフローのランタイムインスタンス障害の詳細を調べてください。

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

ワークフローのランタイムログを確認してください。

Amazon CloudWatch ログ

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

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 バケット名とkey prefix 指定した場合、ワークフローステップのランタイムログパスは次のパターンに従います。
```
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 で強化されたベースイメージではビルドが失敗します。
AssertInventoryCollection 失敗 (Systems Manager 自動化)

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

説明

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

原因

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

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

ソリューション

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

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

説明

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

原因

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

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

ソリューション

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

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

説明

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 User Guide for Windows InstancesのNitroシステム上に構築されたインスタンスを参照してください。

説明

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 を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ベストプラクティス

ドキュメント履歴