GitLab CI/CDからAWSにデプロイする

GitLabでは、AWSへのデプロイに必要なライブラリとツールを含むDockerイメージを提供しています。CI/CDパイプラインでこれらのイメージを参照できます。

GitLab.comを使用して、Amazon Elastic Container Service （ECS）にデプロイする場合は、ECSへのデプロイについての説明をお読みください。

AWSでGitLabを認証する

GitLab CI/CDを使用してAWSに接続するには、認証する必要があります。認証を設定したら、CI/CDを設定してデプロイできます。

1. AWSアカウントにサインインします。

2. IAMユーザーを作成します。

3. ユーザーを選択して、その詳細にアクセスします。Security credentials（セキュリティ認証情報） > Create a new access key（新しいアクセスキーを作成）に移動します。

4. Access key ID（アクセスキーID）とSecret access key（シークレットアクセスキー）をメモしておきます。

5. GitLabプロジェクトで、設定 > CI/CDに移動します。次のCI/CD変数を設定します:

   環境変数名	値
   AWS_ACCESS_KEY_ID	アクセスキーID。
   AWS_SECRET_ACCESS_KEY	シークレットアクセスキー。
   AWS_DEFAULT_REGION	リージョンコード。使用する予定のAWSサービスが選択したリージョンで利用可能であることを確認することをお勧めします。

6. 変数はデフォルトで保護されています。保護されていないブランチまたはタグでGitLab CI/CDを使用するには、変数の保護チェックボックスをオフにします。

イメージを使用してAWSコマンドを実行する

イメージにAWS CLIが含まれている場合は、プロジェクトの.gitlab-ci.ymlファイルでイメージを参照できます。次に、CI/CDジョブでawsコマンドを実行できます。

例:

deploy:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
  script:
    - aws s3 ...
    - aws create-deployment ...
  environment: production

GitLabでは、AWS CLIを含むDockerイメージを提供しています:

• イメージは、GitLabコンテナレジストリでホスティングされています。最新のイメージはregistry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latestです。
• イメージはGitLabリポジトリに保存されます。

または、Amazon Elastic Container Registry（ECR）イメージを使用することもできます。ECRリポジトリにイメージをプッシュする方法を確認してください。

サードパーティ製レジストリのイメージも使用できます。

アプリケーションをECSにデプロイする

Amazon ECSクラスターへのアプリケーションのデプロイを自動化できます。

前提要件:

• GitLabでAWSを認証します。
• Amazon ECSでクラスターを作成します。
• ECSサービスやAmazon RDSのデータベースなど、関連コンポーネントを作成します。
• containerDefinitions[].name属性の値が、ターゲットのECSサービスで定義されているContainer nameと同じであるECSタスク定義を作成します。タスク定義としては、次のいずれかが可能です:
  • ECS内の既存のタスク定義。
  • GitLabプロジェクトのJSONファイル。AWSドキュメントのテンプレートを使用して、プロジェクトにファイルを保存します。たとえば、<project-root>/ci/aws/task-definition.jsonなどです。

ECSクラスターにデプロイするには、次のようにします:

1. GitLabプロジェクトで、設定 > CI/CDに移動します。次のCI/CD変数を設定します。これらの名前は、Amazon ECSダッシュボードでターゲットクラスターを選択すると確認できます。

   環境変数名	値
   CI_AWS_ECS_CLUSTER	デプロイのターゲットにしているAWS ECSクラスターの名前。
   CI_AWS_ECS_SERVICE	AWS ECSクラスターに紐付けられた、ターゲットサービスの名前。この変数のスコープが適切な環境（production、staging、review/*）に設定されていることを確認してください。
   CI_AWS_ECS_TASK_DEFINITION	タスク定義がECSにある場合、サービスに紐付けられたタスク定義の名前。
   CI_AWS_ECS_TASK_DEFINITION_FILE	タスク定義がGitLabのJSONファイルである場合、パスを含むファイル名。たとえばci/aws/my_task_definition.jsonなどです。JSONファイル内のタスク定義の名前が、ECS内の既存のタスク定義と同じ名前である場合、CI/CDの実行時に新しいリビジョンが作成されます。それ以外の場合は、完全に新しいタスク定義がリビジョン1から作成されます。

   CI_AWS_ECS_TASK_DEFINITION_FILEとCI_AWS_ECS_TASK_DEFINITIONの両方を定義した場合、CI_AWS_ECS_TASK_DEFINITION_FILEが優先されます。

2. このテンプレートを.gitlab-ci.ymlに含めます:

   include:
     - template: AWS/Deploy-ECS.gitlab-ci.yml

   AWS/Deploy-ECSテンプレートはGitLabに付属しており、GitLab.comで利用できます。

3. 更新した.gitlab-ci.ymlをコミットして、プロジェクトのリポジトリにプッシュします。

アプリケーションのDockerイメージが再ビルドされ、GitLabコンテナレジストリにプッシュされます。イメージがプライベートレジストリにある場合は、タスク定義の設定にrepositoryCredentials属性が含まれていることを確認してください。

ターゲットのタスク定義が新しいDockerイメージの場所で更新され、その結果、新しいリビジョンがECSで作成されます。

最後に、AWS ECSサービスがタスク定義の新しいリビジョンで更新され、クラスターがアプリケーションの最新バージョンをプルするようになります。

アプリケーションをEC2にデプロイする

GitLabは、Amazon EC2へのデプロイを支援するために、AWS/CF-Provision-and-Deploy-EC2というテンプレートを提供します。

関連するJSONオブジェクトを設定して、テンプレートを使用する場合、パイプラインは次のようになります:

1. Creates the stack（スタックを作成します）: インフラストラクチャは、AWS CloudFormation APIを使用してプロビジョニングされます。
2. Pushes to an S3 bucket（S3バケットにプッシュします）: ビルドを実行すると、アーティファクトが作成されます。そのアーティファクトがAWS S3バケットにプッシュされます。
3. Deploys to EC2（EC2にデプロイします）: 次の図に示すように、コンテンツがAWS EC2インスタンスにデプロイされます:

テンプレートとJSONを設定する

EC2にデプロイするには、次の手順を実行します。

1. スタックのJSONを作成します。AWSテンプレートを使用します。

2. S3にプッシュするJSONを作成します。次の詳細を含めます。

   {
     "applicationName": "string",
     "source": "string",
     "s3Location": "s3://your/bucket/project_built_file...]"
   }

   sourceは、buildジョブがアプリケーションをビルドした場所です。ビルドはartifacts:pathsに保存されます。

3. EC2にデプロイするJSONを作成します。AWSテンプレートを使用します。

4. JSONオブジェクトをパイプラインからアクセスできるようにします:

   • これらのJSONオブジェクトをリポジトリに保存する場合は、オブジェクトを3つの個別のファイルとして保存します。

     .gitlab-ci.ymlファイルで、プロジェクトルートからの相対ファイルパスを指すCI/CD変数を追加します。たとえば、JSONファイルが<project_root>/awsフォルダーにある場合は、次のようにします:

     variables:
       CI_AWS_CF_CREATE_STACK_FILE: 'aws/cf_create_stack.json'
       CI_AWS_S3_PUSH_FILE: 'aws/s3_push.json'
       CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json'

   • これらのJSONオブジェクトをリポジトリに保存しない場合は、プロジェクト設定で各オブジェクトを個別のファイルタイプCI/CD変数として追加します。前と同じ変数名を使用してください。

5. .gitlab-ci.ymlファイルで、スタックの名前のCI/CD変数を作成します。例:

   variables:
     CI_AWS_CF_STACK_NAME: 'YourStackName'

6. .gitlab-ci.ymlファイルで、CIテンプレートを追加します:

   include:
     - template: AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml

7. パイプラインを実行します。

   • AWS CloudFormationスタックは、CI_AWS_CF_CREATE_STACK_FILE変数の内容に基づいて作成されます。スタックが既に存在する場合、この手順はスキップされますが、それが属するprovisionジョブは引き続き実行されます。
   • ビルドされたアプリケーションはS3バケットにプッシュされ、関連するJSONオブジェクトの内容に基づいてEC2インスタンスにデプロイされます。EC2へのデプロイが完了または失敗すると、デプロイジョブが完了します。

トラブルシューティング

エラー'ascii' codec can't encode character '\uxxxx'

このエラーは、Cloud Deployイメージで使用されるaws-cliユーティリティからの応答にUnicode文字が含まれている場合に発生する可能性があります。Cloud Deployイメージには、定義されたロケールがなく、デフォルトではASCIIを使用します。このエラーを解決するには、次のCI/CD変数を追加します:

variables:
  LANG: "UTF-8"