はじめに

CDKアプリケーションの開発を行っていたプロジェクトにて、GitHub Actionsによりデプロイ自動化の仕組みを構築しました。
その際、エンタープライズでのチーム開発に最低限必要そうな機能を含めたのですが、その辺りがひと通りまとまっている記事があまり見当たらなかったため、簡単にまとめてみました。

想定読者
- チーム開発向けにデプロイ自動化の仕組みを構築したい。
- GitHub Actionsでワークフローを組んだことがある。
- AWSのCDK、CloudFormation(以降CFNと記載)、IAMなどについて基礎的な知識がある。
主な技術要素
- GitHub Actions
- AWS CDK

この記事のポイント

デプロイ自動化の実現に至るための要点に絞っています。(基礎的な説明は省略してます)
ブランチ毎に異なるAWS環境(アカウント)へデプロイします。
OICDプロバイダーを使用し、GitHub ActionsからAWSへのセキュアで効率的なアクセスを行います。

前提事項

構築時の環境情報は下記のとおりです。

OS・MW	Version
Ubuntu	20.04 LTS
Node.js	16.14.2
AWS CDK	2.17.0
AWS CLI	2.4.25

この記事でデプロイしているCDKアプリケーションは、cdk initコマンドを実行しただけの簡単なサンプルアプリケーションです。

# サンプルアプリケーション作成時のコマンド例
$ mkdir sample-cdk-app
$ cd sample-cdk-app/
$ cdk init sample-app --language=typescript

デプロイ先のAWS環境にはcdk bootstrapコマンドが実行済みで、CDKを扱うために必要なCDKToolkitスタックが作成済みであるものとします。

$ npm install -g aws-cdk
$ cdk bootstrap

本題

AWSへのOIDCプロバイダーとIAMロールの作成

デプロイ先のAWS環境へ、OIDCプロバイダーとIAMロール(GitHub Actionsが使用)を作成します。OIDCプロバイダーによる認証を採用することで、下記の様なメリットがあります。

GitHub ActionsがAWSへアクセスする際の専用IAMユーザーの作成が不要。
AWSのクレデンシャル情報(アクセスキーやシークレット)をGitHub側に持たせる必要がない。
上記により、シークレットのローテーションといった運用の考慮が必要ない。

ここでいうAWS側のOIDCプロバイダーは、厳密には「IDプロバイダーを信頼するための設定」です。実際にOpenID Connect認証用のIDトークンを発行するプロバイダは、GitHub側に存在します。そのあたりの説明は、下記の記事が分かりやすく、参考にさせて頂きました。

下記CFNテンプレートにより、前述のリソースを含むスタックを作成できます。

template.yaml

Parameters:
  RepoOwner:
    Description: Owner of repository.
    Type: String
  RepoName:
    Description: Name of repository where the GitHub Actions will be running.
    Type: String
  OIDCProviderArn: # ２回目以降に作成済みOIDC ProviderのARNを指定します
    Description: Arn for the GitHub OIDC Provider.
    Default: ''
    Type: String

Conditions:
  CreateOIDCProvider: !Equals
    - !Ref OIDCProviderArn
    - ''

Resources:
  Role:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Sub ${RepoName}-actions-role
      AssumeRolePolicyDocument:
        Statement:
          - Effect: Allow
            Action: sts:AssumeRoleWithWebIdentity
            Principal:
              Federated: !If
                - CreateOIDCProvider
                - !Ref GithubOidc
                - !Ref OIDCProviderArn
            Condition:
              StringLike:
                token.actions.githubusercontent.com:sub: !Sub repo:${RepoOwner}/${RepoName}:*
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AdministratorAccess # 権限の限定を推奨

  GithubOidc:
    Type: AWS::IAM::OIDCProvider
    Condition: CreateOIDCProvider
    Properties:
      Url: https://token.actions.githubusercontent.com
      ClientIdList:
        - sts.amazonaws.com
      ThumbprintList:
        - 6938fd4d98bab03faadb97b34396831e3780aea1 # サムプリントの更新箇所

Outputs:
  Role:
    Value: !GetAtt Role.Arn

OIDC ProviderはAWSアカウントにひとつのみしか存在できません。そのため、このCFNテンプレートで別スタックを作成する場合は、下記Parametersに作成済みOIDC ProviderのArnを渡してください。

template.yaml (抜粋)

Parameters:
  OIDCProviderArn: # ２回目以降に作成済みOIDC ProviderのARNを指定します

下記のポリシーを指定している箇所は、デプロイするCDKアプリケーションに応じて、必要最低限の権限とすることを推奨します。今回はサンプルのため、強い権限を与えています。

template.yaml (抜粋)

      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AdministratorAccess # 権限の限定を推奨

また、GitHubのIDプロバイダーでサムプリントが更新されていた場合、最新のものをCFNテンプレートに反映する必要があります。スタック作成前に、後述の更新手順を実施しておくのが確実と思います。

template.yaml (抜粋)

  GithubOidc:
    Type: AWS::IAM::OIDCProvider
    Condition: CreateOIDCProvider
    Properties:
      Url: https://token.actions.githubusercontent.com
      ClientIdList:
        - sts.amazonaws.com
      ThumbprintList:
        - 6938fd4d98bab03faadb97b34396831e3780aea1 # サムプリントの更新箇所

下記がAWSの公式ガイドで説明されているサムプリント取得方法です。

公式ガイドに記載の手順は少々複雑であるため、私はIAMコンソールを使用する下記の方法で取得しました。(公式ではガイドされていない方法のため、こちらは自己責任で実施されてください)

「プロバイダのタイプ」でOpenID Connectを選択します。
「プロバイダのURL」にhttps://token.actions.githubusercontent.comを指定することで取得できます。

下記のようなAWS CLIコマンドで、前述のCFNテンプレートでスタックを作成します。

aws cloudformation create-stack \
--stack-name actions-base \
--template-body file://template.yaml \
--capabilities CAPABILITY_NAMED_IAM \
--parameters ParameterKey=RepoOwner,ParameterValue=<Owner Name> ParameterKey=RepoName,ParameterValue=sample-cdk-app
# 名前指定のIAMロール作成があるため、`CAPABILITY_NAMED_IAM`オプションの指定が必要。

GitHubのSecretsへAWSアカウント情報を格納

GitHub Actionsがデプロイ先を判断するために必要なAWSアカウント情報(アカウントIDとリージョン)を、リポジトリのSecretsへ格納します。これは後述のワークフロー定義内で作り込みました仕様によるもので、Secretsへ格納することでアカウント情報が漏出するリスクを低減することが目的です。

開発環境(dev)用のSecret名
- AWS_ACCOUNT_DEV
- AWS_REGION_DEV
本番環境(prd)用のSecret名
- AWS_ACCOUNT_PRD
- AWS_REGION_PRD

GitHubリポジトリのコンソールSettings > Secrets > Actionsから追加できます。

GitHub Actionsワークフロー定義の配置

デプロイ対象のCDKアプリケーションに、.github/workflows/というディレクトリを作成し、ワークフロー定義ファイル(yaml)を配置します。ファイル名は任意です。

今回作成したワークフローの仕様はざっくり下記の通りです。

merge先/push先ブランチによってデプロイ先のAWS環境を切り替えます。
- developブランチ → 開発環境(dev)
- mainブランチ → 本番環境(prd)
プルリクエストの作成時、または、プルリクエストの更新時
- cdk diffを実行します。ワークフローの実行結果から、デプロイ済みスタックとの差分が確認できます。
プルリクエストのmerge時、または、ブランチへの直接push時
- cdk diffとcdk deployを実行します。

.github/workflows/cdk-deploy.yml

name: CDK Deploy

on:
  push:
    branches:
      - develop
      - main
  pull_request:
    branches:
      - develop
      - main
permissions:
  id-token: write
  contents: read

jobs:
  cdk-deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: 16
          registry-url: https://npm.pkg.github.com/
      - name: Install AWS CDK
        run: npm ci
      - name: Destination settings for dev enviroment
        if: (github.ref == 'refs/heads/develop') || (github.event.pull_request.base.ref == 'develop')
        run: |
          echo "Using dev environment settings."
          echo "AWS_ACCOUNT=${{secrets.AWS_ACCOUNT_DEV}}" >> $GITHUB_ENV
          echo "AWS_REGION=${{secrets.AWS_REGION_DEV}}" >> $GITHUB_ENV
      - name: Destination settings for prd enviroment
        if: (github.ref == 'refs/heads/main') || (github.event.pull_request.base.ref == 'main')
        run: |
          echo "Using prd environment settings."
          echo "AWS_ACCOUNT=${{secrets.AWS_ACCOUNT_PRD}}" >> $GITHUB_ENV
          echo "AWS_REGION=${{secrets.AWS_REGION_PRD}}" >> $GITHUB_ENV
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::${{env.AWS_ACCOUNT}}:role/${{github.event.repository.name}}-actions-role
          aws-region: ${{env.AWS_REGION}}
      - name: CDK Diff
        if: contains(github.event_name, 'pull_request') || contains(github.event_name, 'push')
        run: npm run cdk -- diff
      - name: CDK Deploy
        if: contains(github.event_name, 'push')
        run: npm run cdk -- deploy --require-approval never

ワークフロー定義は今回のキモとなる部分のため、工夫点など含め少し詳しく説明していきます。

下記ステップは、package.jsonに記載のaws-cdkなどをインストールすることが目的ですが、npm ciとすることで、package-lock.jsonの構成管理を強制しています。npm installを実行してしまうと、依存パッケージのバージョンが安定しないため、意図せぬ変更を防いでいます。