EC2/オンプレミスデプロイの問題のトラブルシューティング

注記

多くのデプロイ失敗の原因は、デプロイプロセス中に作成されたログファイルを確認して特定できます。簡単にするために、インスタンスごとにログファイルを表示するのではなく、Amazon CloudWatch Logs を使用してログファイルを一元的にモニタリングすることをお勧めします。詳細については、 CodeDeploy 「ログコンソール で CloudWatch ログを表示する」を参照してください。

ヒント

EC2/オンプレミスデプロイに関連する多くのトラブルシューティングタスクを自動化するランブックについては、AWS Systems Manager Automation ランブックリファレンスのAWSSupport「-TroubleshootCodeDeploy」を参照してください。

CodeDeploy プラグインの CommandPoller認証情報不足エラー

InstanceAgent::Plugins::CodeDeployPlugin::CommandPoller: Missing credentials - please check if this instance was started with an IAM instance profile のようなエラーが表示された場合は、次のいずれがが原因の可能性があります。

• デプロイ先のインスタンスには、IAMインスタンスプロファイルが関連付けられていません。

• IAM インスタンスプロファイルに正しいアクセス許可が設定されていません。

IAM インスタンスプロファイルは、Amazon S3 と CodeDeploy通信し、リビジョンをダウンロードするアクセス許可を CodeDeploy エージェントに付与します。EC2 インスタンスについては、「」を参照してくださいAWS CodeDeployのためのアイデンティティおよびアクセス管理 。オンプレミスインスタンスの場合は、Working with On-Premises Instances を参照してください。

PKCS7 「署名付きメッセージの検証に失敗しました」というメッセージでデプロイが失敗する

このエラーメッセージは、インスタンスが SHA-1 ハッシュアルゴリズムのみをサポートする CodeDeploy エージェントのバージョンを実行していることを示します。SHA-2 ハッシュアルゴリズムのサポートは、2015 年 11 月にリリースされた CodeDeploy エージェントのバージョン 1.0.1.854 で導入されました。2016 年 10 月 17 日以降、1.0.1.854 より前のバージョンの CodeDeploy エージェントがインストールされると、デプロイは失敗します。詳細については、AWS SSL「 証明書のSHA256ハッシュアルゴリズムに切り替えるには」、NOTICE「: バージョン 1.0.1.85 より古い CodeDeploy ホストエージェントの廃止」、および「」を参照してください CodeDeploy エージェントを更新する。

同じデプロイ先のインスタンスに対する同じファイルのデプロイや再デプロイは失敗し、「指定したファイルはこの場所に既に存在するため、デプロイに失敗しました」というエラーが返されます。

がファイルをインスタンスにデプロイ CodeDeploy しようとしても、指定したターゲット場所に同じ名前のファイルがすでに存在する場合、そのインスタンスへのデプロイが失敗する可能性があります。「指定されたファイルがこの場所に既に存在するため、デプロイが失敗しました」というエラーメッセージが表示される場合があります。location-name.「」 これは、各デプロイ中に、 CodeDeploy 最初にクリーンアップログファイルにリストされている以前のデプロイからすべてのファイルを削除するためです。このクリーンアップファイルにリストされていないファイルがターゲットインストールフォルダにある場合、 CodeDeploy エージェントはデフォルトでこれをエラーとして解釈し、デプロイに失敗します。

注記

Amazon Linux、RHEL、および Ubuntu Server インスタンスでは、クリーンアップファイルは にあります/opt/codedeploy-agent/deployment-root/deployment-instructions/。Windows Server インスタンスでは、場所は C:\ProgramData\Amazon\CodeDeploy\deployment-instructions\ です。

このエラーを最も簡単に回避するには、デプロイを失敗させるデフォルト動作とは別のオプションを指定します。デプロイごとに、デプロイを失敗させるか、クリーンアップファイルにリストされていないファイルを上書きするか、インスタンスの既存ファイルを保持するかを選択できます。

上書きオプションは、最後のデプロイ後に手動でインスタンスに追加した同じ名前のファイルを、次回のアプリケーションリビジョンにも追加する場合などに便利です。

保持オプションは、次回のデプロイでインスタンスに追加するファイルを、アプリケーションリビジョンパッケージには追加する必要がない場合に選択できます。保持オプションは、アプリケーションファイルが既に本番環境にあり、 CodeDeploy を使用して初めてデプロイする場合にも役立ちます。詳細については、「EC2/オンプレミスコンピューティングプラットフォームデプロイを作成する (コンソール）」および「既存のコンテンツでのロールバック動作」を参照してください。

The deployment failed because a specified file already exists at this location デプロイメント失敗のトラブルシューティング

ターゲットデプロイロケーションで が検出した CodeDeployコンテンツを上書きまたは保持するオプションを指定しない場合 (またはプログラムコマンドで既存のコンテンツを処理するためのデプロイオプションを指定しない場合）、エラーのトラブルシューティングを選択できます。

次の情報は、コンテンツを保持または上書きしないことを選択した場合にのみ該当します。

同じ名前と場所のファイルを再デプロイしようとすると、アプリケーション名と、以前に使用したのと同じ基盤となるデプロイグループ ID を持つデプロイグループを指定した場合、再デプロイが成功する可能性が高くなります。 は、基盤となるデプロイグループ ID CodeDeploy を使用して、再デプロイ前に削除するファイルを識別します。

新しいファイルのデプロイや、インスタンスの同じ場所への同じファイルの再デプロイは、次の理由により失敗することがあります。

• 同じリビジョンの同じインスタンスへの再デプロイのため、別のアプリケーション名を指定した。デプロイグループ名が同じでも、別のアプリケーション名を使用すると、基になる別のデプロイグループ ID が使用されるため、再デプロイは失敗します。

• アプリケーションのデプロイグループを削除して再作成し、同じリビジョンをデプロイグループに対して再デプロイしようとした。デプロイグループ名が同じであっても、 は別の基盤となるデプロイグループ ID CodeDeploy を参照するため、再デプロイは失敗します。

• でアプリケーションとデプロイグループを削除し CodeDeploy、削除したアプリケーションとデプロイグループと同じ名前の新しいアプリケーションとデプロイグループを作成しました。その後、以前のデプロイグループにデプロイされていたリビジョンを、同じ名前の新しいデプロイグループに再デプロイしようとした。アプリケーションとデプロイグループ名が同じであっても、削除したデプロイグループの ID は CodeDeploy 引き続き参照されるため、再デプロイは失敗します。

• リビジョンをデプロイグループにデプロイし、同じリビジョンを同じインスタンスの別のデプロイグループにデプロイした。は別の基盤となるデプロイグループ ID CodeDeploy を参照するため、2 番目のデプロイは失敗します。

• リビジョンを 1 つのデプロイグループにデプロイし、別のリビジョンを同じインスタンスの別のデプロイグループにデプロイした。2 番目のデプロイグループがデプロイを試みる同じ名前と場所のファイルが、少なくとも 1 つある。 CodeDeploy は、2 番目のデプロイを開始する前に既存のファイルを削除しないため、2 番目のデプロイは失敗します。両方のデプロイ >異なるデプロイグループを参照しますIDs。

• リビジョンを にデプロイしましたが CodeDeploy、同じ名前で同じ場所に少なくとも 1 つのファイルがあります。デフォルトでは、デプロイが開始される前に既存のファイルは削除 CodeDeploy されないため、デプロイは失敗します。

これらの状況に対応するには、次のいずれかを実行します。

• 以前のデプロイされた場所とインスタンスからファイルを削除してから、もう一度デプロイを試みます。

• リビジョンの AppSpec ファイルで、 ApplicationStop または BeforeInstallデプロイライフサイクルイベントのいずれかで、リビジョンのインストール先のファイルと一致する任意の場所にあるファイルを削除するカスタムスクリプトを指定します。

• 以前のデプロイの一部ではない場所またはインスタンスにファイルをデプロイまたは再デプロイします。

• アプリケーションまたはデプロイグループを削除する前に、インスタンスにコピーするファイルを指定しない AppSpec ファイルを含むリビジョンをデプロイします。デプロイでは、IDs削除するアプリケーション名とデプロイグループと同じ基盤となるアプリケーションとデプロイグループを使用するデプロイグループ名を指定します。( get-deployment-group コマンドを使用してデプロイグループ ID を取得できます。） CodeDeploy は、基盤となるデプロイグループ ID と AppSpec ファイルを使用して、以前の正常なデプロイでインストールされたすべてのファイルを削除します。

ファイルパスが長いと、「そのようなファイルまたはディレクトリはありません」というエラーが発生します

Windows インスタンスへのデプロイでは、appspec.yml ファイルのファイルセクションに 260 文字を超えるファイルパスがあると、デプロイが次のようなエラーで失敗することがあります。

No such file or directory @ dir_s_mkdir - C:\your-long-file-path

このエラーは、Microsoft のドキュメントに詳述されているように、Windows ではデフォルトで 260 文字を超えるファイルパスが許可されていないために発生します。

CodeDeploy エージェントバージョン 1.4.0 以降では、エージェントのインストールプロセスに応じて、次の 2 つの方法で長いファイルパスを有効にすることができます。

CodeDeploy エージェントがまだインストールされていない場合：

1. CodeDeploy エージェントをインストールするマシンで、次のコマンドを使用して LongPathsEnabled Windows レジストリキーを有効にします。

   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem"
             -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

2. CodeDeploy エージェントをインストールします。詳細については、「 CodeDeploy エージェントをインストールする」を参照してください。

CodeDeploy エージェントがすでにインストールされている場合：

1. CodeDeploy エージェントマシンで、次のコマンドを使用して LongPathsEnabled Windows レジストリキーを有効にします。

   New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" 
   -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
   

2. レジストリキーの変更を有効にするには、 CodeDeploy エージェントを再起動します。エージェントを再起動するには、次のコマンドを使用します。

   powershell.exe -Command Restart-Service -Name codedeployagent

長時間実行されているプロセスにより、デプロイが失敗することがある

Amazon Linux、Ubuntu Server、およびRHELインスタンスへのデプロイの場合、長時間実行されるプロセスを開始するデプロイスクリプトがある場合、デプロイライフサイクルイベントで待機してからデプロイに失敗するまでに時間がかかる CodeDeploy ことがあります。これは、そのイベントでプロセスがフォアグラウンドプロセスとバックグラウンドプロセスよりも長く実行されると、プロセスが想定どおりに実行されていても、 はデプロイ CodeDeploy を停止して失敗するためです。

たとえば、アプリケーションリビジョンのルートに 2 つのファイル (after-install.sh および sleep.sh) が含まれているとします。その AppSpec ファイルには、以下の手順が含まれています。

version: 0.0
os: linux
files:
  - source: ./sleep.sh
    destination: /tmp
hooks:
  AfterInstall:
    - location: after-install.sh
      timeout: 60

after-install.sh ファイルは、 AfterInstall アプリケーションのライフサイクルイベント中に実行されます。そのコンテンツは次のとおりです。

#!/bin/bash
/tmp/sleep.sh

sleep.sh ファイルには以下が含まれます。これはプログラムの実行を 3 分 (180 秒) 停止し、長時間実行されるプロセスをシミュレートします。

#!/bin/bash
sleep 180

が をafter-install.sh呼び出すとsleep.sh、 は 3 分 (180 秒) sleep.shにわたって起動して実行されます。これはsleep.sh、 (およびリレーションにより、) が実行を停止するのを CodeDeploy 待つ時間を 2 分 (120 秒after-install.sh) 超えた時間です。1 分 (60 秒) のタイムアウト後、 は想定どおりに実行sleep.shされ続けているにもかかわらず、 AfterInstall アプリケーションのライフサイクルイベントでのデプロイ CodeDeploy を停止して失敗します。次のエラーが表示されます。

Script at specified location: after-install.sh failed to complete in 60 seconds.

単純に & でアンパサンド (after-install.sh) を追加して、バックグラウンドで sleep.sh を実行することはできません。

#!/bin/bash
# Do not do this.
/tmp/sleep.sh &

これにより、デプロイはデフォルトの 1 時間のデプロイライフサイクルイベントタイムアウト期間まで保留状態のままになり、その後、アプリケーション AfterInstall ライフサイクルイベントでのデプロイ CodeDeploy が停止して失敗します。

でafter-install.sh、sleep.sh次のように呼び出します。これにより、プロセスの実行が開始された後も CodeDeploy が続行できます。

#!/bin/bash
/tmp/sleep.sh > /dev/null 2> /dev/null < /dev/null &

前の呼び出しで、sleep.sh はバックグラウンドで実行を開始し、stdout、stderr、および stdin を /dev/null にリダイレクトするプロセスの名前です。

デプロイログにエラーが報告されていない AllowTraffic ライフサイクルイベントのトラブルシューティング

場合によっては、ブルー/グリーンデプロイは AllowTraffic ライフサイクルイベント中に失敗しますが、デプロイログは失敗の原因を示しません。

通常、この障害は、デプロイグループへのトラフィック管理に使用される Classic Load Balancer、Application Load Balancer、または Network Load Balancer の Elastic Load Balancing のヘルスチェックが間違って設定されていることが原因です。

この問題を解決するには、ロードバランサーのヘルスチェックの設定エラーを確認して修正します。

Classic Load Balancer については、Classic Load Balancer ユーザーガイドの「Configure Health Checks」および ConfigureHealthCheck Elastic Load Balancing APIリファレンスバージョン 2012-06-01 を参照してください。

Application Load Balancer については、「Application Load Balancer のユーザーガイド」の「ターゲットグループのヘルスチェック」を参照してください。

Network Load Balancer については、Network Load Balancer ユーザーガイド の「ターゲットグループのヘルスチェック」を参照してください。

障害が発生した ApplicationStop、 BeforeBlockTraffic、または AfterBlockTraffic デプロイライフサイクルイベントのトラブルシューティング

デプロイ中、 CodeDeploy エージェントは、以前に正常にデプロイされた AfterBlockTraffic AppSpec ファイルの ApplicationStop、 BeforeBlockTraffic、および に指定されたスクリプトを実行します。（他のすべてのスクリプトは、現在のデプロイの AppSpec ファイルから実行されます。） これらのスクリプトのいずれかにエラーがあって正常に実行されない場合、デプロイに失敗することがあります。

これらの失敗の原因としては以下のようなことが考えられます。

• CodeDeploy エージェントは正しい場所にdeployment-group-id_last_successful_installファイルを見つけますが、deployment-group-id_last_successful_installファイルに記載されている場所は存在しません。

  Amazon Linux、Ubuntu Server、RHELインスタンス では、このファイルは に存在する必要があります/opt/codedeploy-agent/deployment-root/deployment-instructions。

  Windows Server インスタンスでは、このファイルは C:\ProgramData\Amazon\CodeDeploy\deployment-instructions フォルダに保存されている必要があります。

• deployment-group-id_last_successful_install ファイルに記載されている場所で、 AppSpec ファイルが無効であるか、スクリプトが正常に実行されません。

• スクリプトに修正できないエラーがあるため、正常に実行されることはありません。

CodeDeploy コンソールを使用して、これらのイベントのいずれか中にデプロイが失敗した理由を調べます。デプロイの詳細ページで、[View events] を選択します。インスタンスの詳細ページで、ApplicationStop、BeforeBlockTraffic、または AfterBlockTraffic行で、ログの表示 を選択します。または AWS CLI 、 を使用して get-deployment-instance コマンドを呼び出します。

障害の原因が、最後に成功したデプロイのスクリプトで、正常に実行されなかった場合は、デプロイを作成し BeforeBlockTraffic、 ApplicationStop、、、および の AfterBlockTraffic 障害を無視するように指定します。これには、以下の 2 つの方法があります。

• CodeDeploy コンソールを使用してデプロイを作成します。デプロイの作成ページで、ApplicationStop ライフサイクルイベント障害 で、インスタンス上のこのライフサイクルイベントが失敗した場合にインスタンスへのデプロイを失敗させない を選択します。

• AWS CLI を使用して create-deployment コマンドを呼び出し、 --ignore-application-stop-failuresオプションを含めます。

アプリケーションリビジョンを再度デプロイすると、これら 3 つのライフサイクルイベントのいずれが失敗してもデプロイは続行されます。これらのライフサイクルイベントの修正済みスクリプトが新しいリビジョンに含まれている場合は、この修正を適用しなくても以降のデプロイは正常に実行されます。

で失敗した DownloadBundle デプロイライフサイクルイベントのトラブルシューティング UnknownError: 読み取り用に開かれていない

Amazon S3 からアプリケーションリビジョンをデプロイしようとしたときに、デプロイライフサイクルイベント中にUnknownError: not opened for readingエラーが発生して DownloadBundle デプロイが失敗した場合：

• Amazon S3 の内部サーバーエラーが発生しました。アプリケーションリビジョンをもう一度デプロイします。

• IAM インスタンスのEC2インスタンスプロファイルには、Amazon S3 のアプリケーションリビジョンにアクセスするアクセス許可がありません。Amazon S3 バケットポリシーの詳細については、「のリビジョンを Amazon S3 CodeDeploy にプッシュする (EC2/オンプレミスデプロイのみ）」と「デプロイの前提条件」 を参照してください。

• デプロイ先のインスタンスは 1 つの AWS リージョン (米国西部 (オレゴン) など) に関連付けられていますが、アプリケーションリビジョンを含む Amazon S3 バケットは別の AWS リージョン (米国東部 (バージニア北部) など) に関連付けられています。アプリケーションリビジョンがインスタンスと同じ AWS リージョンに関連付けられている Amazon S3 バケットにあることを確認します。

デプロイのイベント詳細ページの [Download bundle (バンドルのダウンロード)] 行で、[ログを表示する] を選択します。または AWS CLI 、 を使用して get-deployment-instance コマンドを呼び出します。このエラーが発生した場合、エラーコード「UnknownError」とエラーメッセージ「not opened for reading」のエラーが出力に表示されます。

このエラーの原因を特定するには:

1. インスタンスの少なくとも 1 つでワイヤログを有効にして、もう一度アプリケーションリビジョンをデプロイします。

2. ワイヤログファイルを調べてエラーを見つけます。この問題の一般的なエラーメッセージには、「access denied」という語句が含まれます。

3. ログファイルを確認した後、ワイヤログを無効にして、ログファイルサイズと、今後インスタンスでプレーンテキストで出力に表示される可能性がある機密情報の量を減らすことをお勧めします。

ワイヤログファイルを検索し、ワイヤログを有効または無効にする方法については、 :log_aws_wire: CodeDeploy エージェント設定リファレンスの「」を参照してください。

スキップされたすべてのライフサイクルイベントのエラーをトラブルシューティングする

EC2 またはオンプレミスデプロイのすべてのライフサイクルイベントがスキップされると、 のようなエラーが表示されることがありますThe overall deployment failed because too many individual instances failed deployment, too few healthy instances are available for deployment, or some instances in your deployment group are experiencing problems. (Error code: HEALTH_CONSTRAINTS)。考えられる原因と解決策は次のとおりです。

• CodeDeploy エージェントはインスタンスにインストールまたは実行されていない可能性があります。 CodeDeploy エージェントが実行されているかどうかを判断するには：

  • Amazon Linux RHELまたは Ubuntu サーバーの場合は、以下を実行します。

    systemctl status codedeploy-agent

  • Windows の場合は、以下を実行します。

    powershell.exe -Command Get-Service -Name CodeDeployagent

  CodeDeploy エージェントがインストールされていないか、実行されていない場合は、「」を参照してください CodeDeploy エージェントが実行されていることを確認します。。

  インスタンスは、ポート 443 を使用して CodeDeploy または Amazon S3 パブリックエンドポイントに到達できない場合があります。 Amazon S3 以下のいずれかを行ってください。

  • インスタンスにパブリック IP アドレスを割り当て、そのルートテーブルを使用してインターネットアクセスを許可します。インスタンスに関連付けられたセキュリティグループが、ポート 443 () を介したアウトバウンドアクセスを許可していることを確認しますHTTPS。詳細については、「 CodeDeploy エージェント用の通信プロトコルとポート」を参照してください。

  • インスタンスがプライベートサブネットにプロビジョニングされている場合は、ルートテーブルでインターネットNATゲートウェイの代わりにゲートウェイを使用します。詳細については、NAT「ゲートウェイ」を参照してください。

• のサービスロールには、必要なアクセス許可がない CodeDeploy 場合があります。 CodeDeploy サービスロールを設定するには、ステップ 2: のサービスロールを作成する CodeDeploy を参照してください。

• HTTP プロキシを使用する場合は、 CodeDeploy エージェント設定ファイルの :proxy_uri:設定で指定されていることを確認してください。詳細については、「CodeDeploy エージェント設定リファレンス」を参照してください。

• デプロイメントインスタンスの日時が、デプロイメントリクエストの日時と一致しない場合があります。 CodeDeploy エージェントログファイルCannot reach InstanceService: Aws::CodeDeployCommand::Errors::InvalidSignatureException - Signature expiredで のようなエラーを探します。このエラーが表示されている場合は、InvalidSignatureException 「- 署名の有効期限が切れた: [time] が [time]」 デプロイエラーのトラブルシューティング のステップに従います。詳細については、「 CodeDeploy EC2/オンプレミスデプロイのログデータを表示する」を参照してください。

• インスタンスのメモリ容量またはハードディスク容量が少ないため、 CodeDeploy エージェントの実行が停止することがあります。 CodeDeploy エージェント設定の max_revisions設定を更新して、インスタンスのアーカイブされたデプロイの数を減らしてみてください。EC2 インスタンスに対してこれを実行しても問題が解決しない場合は、より大きなインスタンスの使用を検討してください。たとえば、インスタンスタイプが t2.small の場合は、t2.medium の使用を検討します。詳細については、「 CodeDeploy エージェントによってインストールされたファイル 」、「CodeDeploy エージェント設定リファレンス」、「 インスタンスタイプ」を参照してください。

• デプロイ先のインスタンスにはIAMインスタンスプロファイルがアタッチされていないか、必要なアクセス許可がないIAMインスタンスプロファイルがアタッチされている可能性があります。

  • IAM インスタンスプロファイルがインスタンスにアタッチされていない場合は、必要なアクセス許可を持つプロファイルを作成し、アタッチします。

  • IAM インスタンスプロファイルが既にインスタンスにアタッチされている場合は、必要なアクセス許可があることを確認してください。

  必要なアクセス許可が付与されているインスタンスプロファイルがアタッチされていることを確認したら、インスタンスを再起動します。詳細については、IAM「Amazon ユーザーガイド」の「Amazon のロールEC2ステップ 4: Amazon IAMインスタンスのEC2インスタンスプロファイルを作成する」および「ロール」を参照してください。 EC2

Windows PowerShell スクリプトが PowerShell デフォルトで Windows の 64 ビットバージョンを使用できない

デプロイの一部として実行されている Windows PowerShell スクリプトが 64 ビット機能に依存している場合 (例えば、32 ビットアプリケーションが 64 ビットバージョンでのみ提供されるライブラリを許可または呼び出すよりも多くのメモリを消費するため）、スクリプトがクラッシュしたり、期待どおりに実行されないことがあります。これは、デフォルトで、 が 32 ビットバージョンの Windows CodeDeploy を使用して PowerShell 、アプリケーションリビジョンの一部である Windows PowerShell スクリプトを実行するためです。

Windows の 64 ビットバージョンで実行する必要があるスクリプトの先頭に、次のようなコードを追加します PowerShell。

# Are you running in 32-bit mode?
#   (\SysWOW64\ = 32-bit mode)

if ($PSHOME -like "*SysWOW64*")
{
  Write-Warning "Restarting this script under 64-bit Windows PowerShell."

  # Restart this script under 64-bit Windows PowerShell.
  #   (\SysNative\ redirects to \System32\ for 64-bit mode)

  & (Join-Path ($PSHOME -replace "SysWOW64", "SysNative") powershell.exe) -File `
    (Join-Path $PSScriptRoot $MyInvocation.MyCommand) @args

  # Exit 32-bit script.

  Exit $LastExitCode
}

# Was restart successful?
Write-Warning "Hello from $PSHOME"
Write-Warning "  (\SysWOW64\ = 32-bit mode, \System32\ = 64-bit mode)"
Write-Warning "Original arguments (if any): $args"

# Your 64-bit script code follows here...
# ...

このコードのファイルパス情報は直感的ではないように見えるかもしれませんが、32 ビット Windows は次のようなパス PowerShell を使用します。

c:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe

64 ビット Windows は、次のようなパス PowerShell を使用します。

c:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe