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

注記

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

ヒント

EC2/オンプレミスデプロイに関連する多くのトラブルシューティングタスクを自動化するランブックについては、「AWS Systems Manager オートメーションランブックリファレンス」の「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 インスタンスプロファイルによって、CodeDeploy と通信し、リビジョンを Amazon S3 からダウンロードするためのアクセス許可が CodeDeploy エージェントに付与されている。EC2 インスタンスの場合は、「AWS CodeDeployのためのアイデンティティおよびアクセス管理 」を参照してください。オンプレミスインスタンスの場合は、Working with On-Premises Instances を参照してください。

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

このエラーメッセージは、SHA-1 ハッシュアルゴリズムのみをサポートするバージョンの CodeDeploy エージェントをインスタンスが実行していることを示します。SHA-2 ハッシュアルゴリズムのサポートは、2015 年 11 月にリリースされたバージョン 1.0.1.854 の CodeDeploy エージェントで導入されました。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 のアプリケーション名およびデプロイグループを指定すると、成功する可能性が高まります。CodeDeploy は、基になるデプロイグループ ID を使用して、再デプロイする前に削除するファイルを識別します。

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

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

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

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

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

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

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

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

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

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

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

• アプリケーションまたはデプロイグループを削除する前に、インスタンスにコピーするファイルを指定しない AppSpec ファイル を含むリビジョンをデプロイします。このデプロイの場合、削除しようとしているものと同じ、基になるアプリケーションおよびデプロイグループ ID を使用するアプリケーション名とデプロイグループ名を指定します (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 を呼び出すと、sleep.sh が起動し、3 分 (180 秒) 実行します。これは CodeDeploy が sleep.sh (および関連で after-install.sh) の実行を停止させると予期した時間を 2 分 (120 秒) 経過した時間です。1 分 (60 秒) のタイムアウト後、sleep.sh は予期どおり実行を継続しますが、CodeDeploy は停止し、AfterInstall アプリケーションライフサイクルイベントでデプロイに失敗します。次のエラーが表示されます。

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 時間のデプロイライフサイクルイベントのタイムアウト期間まで保留状態になり、その後 CodeDeploy は以前のように AfterInstall アプリケーションライフサイクルイベントでデプロイを停止し、失敗させます。

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 ライフサイクルイベント中に Blue/Green デプロイが失敗しても、デプロイログに失敗の原因が表示されない場合があります。

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

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

Classic Load Balancer については、「Classic Load Balancer のユーザーガイド」の 「Configure health checks for your Classic Load Balancer (Classic Load Balancer のヘルスチェックの設定)」、および「Elastic Load Balancing API リファレンスバージョン 2012-06-01」の「ConfigureHealthCheck」を参照してください。

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

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

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

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

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

• CodeDeploy エージェントは deployment-group-id_last_successful_install ファイルを正しい場所で見つけたが、deployment-group-id_last_successful_install ファイルにリストされている場所が存在しない。

  Amazon Linux、Ubuntu サーバー、および 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 コマンドを呼び出します。

前回の正常なデプロイのスクリプトが正常に実行されないために失敗した場合は、デプロイを作成して [ApplicationStop]、[BeforeBlockTraffic]、および [AfterBlockTraffic] のエラーを無視するように指定します。これには、以下の 2 つの方法があります。

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

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

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

「不明なエラー: 読み取り用に開いていません」で失敗した DownloadBundle デプロイライフサイクルイベントのトラブルシューティング

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

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

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

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

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

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 server の場合は、以下を実行します。

    systemctl status codedeploy-agent

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

    powershell.exe -Command Get-Service -Name CodeDeployagent

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

  インスタンスがポート 443 を使用して CodeDeploy または 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 – Signature expired: [time] is now earlier than [time]」デプロイエラーのトラブルシューティング のステップに従います。詳細については、「CodeDeploy EC2/オンプレミスデプロイのログデータの表示」を参照してください。

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

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

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

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

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

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

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

64 ビットバージョンの Windows 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