AWS CodeDeploy appspec.yml 詳細設定・フック活用ガイド ​

appspec.yml（Application Specification File）は、CodeDeployにデプロイメントの詳細な手順を伝える「設計図」のような重要なファイルです。本記事では、appspec.ymlの基本概念から実践的な活用方法まで、初心者の方にも分かりやすく解説します。

appspec.yml とは何か？ ​

なぜ appspec.yml が必要なのか ​

アプリケーションのデプロイメントは、単純にファイルをコピーするだけではありません。以下のような複雑な作業が必要です：

  1. 古いアプリケーションの停止
  2. 新しいファイルの配置
  3. 設定ファイルの更新
  4. 依存関係のインストール
  5. アプリケーションの起動
  6. 動作確認

appspec.yml は、これらの作業を CodeDeploy に指示するための「作業指示書」です。

appspec.yml の基本的な役割 ​

appspec.yml は以下の3つの主要な役割を担います：

1. ファイル配置の指示
どのファイルをどこに配置するかを指定します。

2. 権限設定の管理
配置したファイルやディレクトリの権限（読み書き実行権限）を設定します。

3. ライフサイクルフックの実行
デプロイメントの各段階で実行するスクリプトを定義します。

プラットフォーム別の appspec.yml 構造 ​

CodeDeployは4つの異なるプラットフォームをサポートしており、それぞれ異なるappspec.yml構造を使用します。

EC2/オンプレミス環境での appspec.yml ​

最もシンプルな appspec.yml の構造 ​

appspec.ymlは非常にシンプルな構造から始めることができます。基本的な構成要素は以下の通りです：

yaml
version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/html

この例では、パッケージ内のすべてのファイルをWebサーバーの公開ディレクトリに配置しています。

ファイル配置の基本概念 ​

appspec.ymlでファイル配置を指定する際の重要な考え方：

source（コピー元）: デプロイパッケージ内のどの部分を取得するか destination（コピー先）: サーバー上のどこに配置するか overwrite（上書き設定）: 既存ファイルがある場合の処理方法

実際のWebアプリケーションでは、静的ファイル、アプリケーション本体、設定ファイルなどを異なる場所に配置することが一般的です。

権限設定の重要性と基本概念 ​

Linuxサーバーでは、ファイルやディレクトリの権限設定が非常に重要です。適切な権限を設定しないと、アプリケーションが動作しません。

権限設定の説明：

デプロイメントライフサイクルとフック ​

ここが appspec.yml の最も重要で強力な機能です。デプロイメントの各段階で自動的にスクリプトを実行できます。

ライフサイクルの流れ ​

フック設定の基本構造 ​

デプロイメントフックは、各段階で実行するスクリプトを指定します。基本的な設定方法：

yaml
hooks:
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 60
  BeforeInstall:
    - location: scripts/cleanup.sh
      timeout: 120
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 120

フックパラメータの重要ポイント：

パラメータ説明設定例
location実行するスクリプトファイルのパスscripts/start_server.sh
timeoutスクリプトの最大実行時間（秒）120 (2分間)
runasスクリプトを実行するユーザーapache, root

スクリプトの役割と責任 ​

各フェーズで実行されるスクリプトの基本的な役割：

ApplicationStop: 既存のアプリケーションやサービスを安全に停止 BeforeInstall: デプロイ準備（古いファイル削除、依存関係インストール） AfterInstall: アプリケーション設定（設定ファイル更新、データベース設定） ApplicationStart: 新しいバージョンのアプリケーションを起動 ValidateService: 動作確認とヘルスチェック

実際のスクリプトでは、ログ出力、エラーハンドリング、戻り値の設定などを適切に行うことが重要です。

Lambda 関数での appspec.yml ​

Lambda関数のデプロイでは、サーバーがないため構造が大きく異なります。

Lambda の基本概念 ​

Lambda appspec.yml の基本概念 ​

Lambda関数のappspec.ymlは、EC2の場合と大きく異なります。主な違いは：

EC2とLambdaの違い:

  • EC2: ファイル配置とスクリプト実行が中心
  • Lambda: バージョン管理とトラフィック制御が中心

Lambdaのappspec.ymlの主要要素:

yaml
version: 0.0
Resources:
  - myLambdaFunction:
      Type: AWS::Lambda::Function
      Properties:
        Name: "my-function"
        Alias: "production"

重要な設定項目の意味:

  • Name: デプロイ対象のLambda関数名
  • Alias: トラフィック制御用のエイリアス（production, stagingなど）
  • CurrentVersion: 現在稼働中のバージョン番号
  • TargetVersion: デプロイする新しいバージョン番号

検証フック: Lambda特有の機能として、トラフィック移行前後に別のLambda関数を実行して検証を行うことができます。

ECS サービスでの appspec.yml ​

ECS（Elastic Container Service）は、Dockerコンテナを管理するサービスです。

ECS デプロイメントの仕組み ​

ECS appspec.yml の基本構造 ​

ECS環境でのappspec.ymlは、コンテナサービスの特性に合わせた構造になっています。

基本的な構成要素:

yaml
version: 0.0
Resources:
  - TargetService:
      Type: AWS::ECS::Service
      Properties:
        TaskDefinition: <TASK_DEFINITION>
        LoadBalancerInfo:
          ContainerName: "web"
          ContainerPort: 80

ECSならではの重要ポイント:

  • TaskDefinition: 新しいコンテナイメージが定義されたタスク定義
  • LoadBalancerInfo: ロードバランサーとの連携設定
  • Blue/Green デプロイメント: 旧環境と新環境を並行稼働させて切り替え

フックの特徴: ECSでは、トラフィック制御の各段階でLambda関数を実行して検証を行います。これにより、コンテナの正常動作を確認してから本格的にトラフィックを移行できます。

よくある問題と解決方法 ​

1. スクリプト実行権限エラー ​

問題症状: スクリプトが "Permission Denied" エラーで失敗する

根本原因: デプロイしたスクリプトファイルに実行権限が設定されていない

解決アプローチ: appspec.ymlのpermissionsセクションで、スクリプトファイルに適切な実行権限（755）を設定する

重要ポイント: Linuxでは、シェルスクリプトを実行するために明示的に実行権限を付与する必要があります。

2. スクリプトタイムアウトエラー ​

問題症状: 長時間実行されるスクリプトが途中で停止する

根本原因: timeout設定が処理時間よりも短く設定されている

解決アプローチ:

  • 処理時間に応じて適切なタイムアウト値を設定
  • 大容量ファイルのダウンロードや データベース初期化などは十分な時間を確保

タイムアウトの目安: 簡単な処理は60秒、データベース関連は300秒、大規模な初期化処理は1800秒程度

3. 環境変数・設定の問題 ​

問題症状: デプロイメント中にアプリケーション固有の設定や環境変数が取得できない

根本原因: CodeDeployエージェントの実行環境では、通常のユーザー環境変数が利用できない場合がある

解決アプローチ:

  • スクリプト内で明示的に環境変数を定義
  • 設定ファイルから値を読み込む
  • AWS Systems Manager Parameter Storeなど外部サービスから取得

まとめ ​

appspec.yml は CodeDeploy にとって非常に重要な設定ファイルです。

覚えておくべき重要ポイント ​

  1. プラットフォームごとに構造が異なる - EC2、Lambda、ECS、EKSそれぞれ専用の形式
  2. ライフサイクルフックが強力 - デプロイメントの各段階で自動処理を実行
  3. 権限設定が重要 - 特にLinux環境では適切な権限設定が必須
  4. テストとデバッグが重要 - 本番適用前に必ず検証環境で動作確認

学習の進め方 ​

  1. シンプルな例から始める - まずは基本的なファイル配置から
  2. 段階的に機能を追加 - 権限設定、フックスクリプトを順次追加
  3. 実際に動かしてみる - 検証環境で実際にデプロイしてみる
  4. ログを確認する - エラーが発生した場合はログで原因を特定

適切な appspec.yml の設定により、安全で効率的なデプロイメントが実現できます。最初は簡単な設定から始めて、徐々に高度な機能を活用していきましょう。