AWS CodeDeploy
ユーザーガイド (API バージョン 2014-10-06)

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

注記

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

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

このエラーメッセージは、SHA-1 ハッシュアルゴリズムのみをサポートするバージョンの CodeDeploy エージェントをインスタンスが実行していることを示します。SHA-2 ハッシュアルゴリズムのサポートは、2015 年 11 月にリリースされたバージョン 1.0.1.854 の CodeDeploy エージェントで導入されました。2016 年 10 月 17 日から、バージョン 1.0.1.854 以前の CodeDeploy エージェントがインストールされている場合、デプロイは失敗します。詳細については、「AWS to Switch to SHA256 Hash Algorithm for SSL Certificates」、「NOTICE: Retiring CodeDeploy Host Agents Older Than Version 1.0.1.85」、および「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 file で、ApplicationStop または BeforeInstall デプロイライフサイクルイベントのいずれかにおいて、リビジョンでインストールするファイルと一致するファイルがいずれかの場所にある場合、これらを削除するためのカスタムスクリプトを指定します。

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

  • アプリケーションまたはデプロイグループを削除する前に、インスタンスにコピーするファイルを指定しない AppSpec file を含むリビジョンをデプロイします。このデプロイの場合、削除しようとしているものと同じ、基になるアプリケーションおよびデプロイグループ ID を使用するアプリケーション名とデプロイグループ名を指定します(get-deployment-group コマンドを使用してデプロイグループ ID を取得できます)。CodeDeploy は基になるデプロイグループ ID と AppSpec file を使用して、前の成功したデプロイでインストールしたすべてのファイルを削除します。

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

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

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

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

クラシックロードバランサー の場合は、クラシックロードバランサー 用ユーザーガイドの「ヘルスチェックを設定する」および Elastic Load Balancing API Reference version 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 Server、RHEL の各インスタンスの場合、このファイルは /opt/codedeploy-agent/deployment-root/deployment-instructions に存在する必要があります。

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

  • deployment-group-id_last_successful_install ファイルに示された場所で、AppSpec file が無効であるか、スクリプトが正常に実行されない。

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

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

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

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

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

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

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

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

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

  • Amazon EC2 インスタンスの IAM インスタンスプロファイルに、Amazon S3 のアプリケーションリビジョンにアクセスするアクセス許可がありません。Amazon S3 バケットポリシーの詳細については、「CodeDeploy 用にリビジョンを Amazon S3 にプッシュする (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:」を参照してください。

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

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

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

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

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.shsleep.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 にリダイレクトするプロセスの名前です。

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

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

      sudo service codedeploy-agent status
    • Windows の場合は、以下を実行します。

      powershell.exe -Command Get-Service -Name codedeployagent

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

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

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

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

  • CodeDeploy のサービスロールに、必要なアクセス許可が付与されていない可能性があります。CodeDeploy サービスロールを設定するには、ステップ 3: 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 設定を更新してください。Amazon EC2 インスタンスにこのプロセスを行っても問題が解決しない場合は、インスタンスのサイズを大きくすることを検討してください。たとえば、インスタンスタイプが t2.small の場合は、t2.medium の使用を検討します。詳細については、CodeDeploy エージェントがインストールしたファイル CodeDeploy エージェント設定リファレンス、および「Amazon EC2 インスタンスタイプ」を参照してください。

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

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

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

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

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 エージェントに付与されている。Amazon EC2 インスタンスについては、AWS CodeDeploy に対する認証とアクセスコントロール を参照してください。オンプレミスインスタンスの場合は、オンプレミスインスタンスの使用 を参照してください。