【日本語訳】Configure AWS Credentials

GithubActionsにAWSアクセスキーを持たせるのは時代遅れ

GithubActions内のワークフローにベタ書きするのも、変数で持たせるのも、永続的なクレデンシャル情報をGithubに持たせるのも微妙でした...が

aws-actionsにその問題を解決するGithubActionsが追加されました。（2021/11/23正式リリース）

これによりGithubActionsにAWSアクセスキーを持たせなくてもAWS Credentialsの設定ができるようになりました。

なんて、半年前のものについての内容を今更ドヤ顔しながら掘り返してもあまり意味がないので
（やり方については調べればいくらでも出てくる。ココとか）

意外と見落としがちな公式ドキュメントをざっくりと自分の言葉で日本語訳してみたので、何かの参考にしていただければと思います。

Githubアクションの"Configure AWS Credentials"アクション

このGithubアクションを使用するためにはAWSクレデンシャルとリージョン環境変数を設定します。
この環境変数を設定することでGithubAction内でAWSSDKとAWSCLIコマンドを発行した際のAWSAPIのクレデンシャル情報を付与してくれます。

Tips. このGithubActionを使うことで、いちいち細かい設定する必要なく簡単にAWSクレデンシャルが設定できる

使用方法

- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v1
  with:
    role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role
    aws-region: us-east-2

例えば、Githubの仮想環境で利用可能なAWSCLIのアクションを使用できます。
さらに、このアクションを複数回実行することで同じGithubアクションワークフロー内で異なるAWSアカウント、リージョン、またはIAMロールを使用することもできます。

jobs:
  deploy:
    name: Upload to Amazon S3
    runs-on: ubuntu-latest
    # このpermissionはGithubのOIDCトークンエンドポイントとやりとりするために必要です。
    permissions:
      id-token: write
      contents: read
    steps:
    - name: Checkout
      uses: actions/checkout@v2

    # テストアカウントのCredentialsを設定
    - name: Configure AWS credentials from Test account
      uses: aws-actions/configure-aws-credentials@v1
      with:
        role-to-assume: arn:aws:iam::111111111111:role/my-github-actions-role-test
        aws-region: us-east-1

    # AWS CLIを使ってファイルをテストウェブサイトにコピーする
    - name: Copy files to the test website with the AWS CLI
      run: |
        aws s3 sync . s3://my-s3-test-website-bucket

    # プロダクションのCredentialsを設定
    - name: Configure AWS credentials from Production account
      uses: aws-actions/configure-aws-credentials@v1
      with:
        role-to-assume: arn:aws:iam::222222222222:role/my-github-actions-role-prod
        aws-region: us-west-2

    # AWS CLIを使ってファイルをプロダクションウェブサイトにコピーする
    - name: Copy files to the production website with the AWS CLI
      run: |
        aws s3 sync . s3://my-s3-prod-website-bucket

Tips. リージョンの変更もロールの変更も簡単に行える

アクションのIF定義（action.yml）

インプットプロパティ	説明	要否
aws-access-key-id	AWSアクセスキーID。従来のやり方で接続したいときなどに必要。基本的にAWSクレデンシャルを持っていればいらない。EC2インスタンスなどで使うかも	任意
aws-secret-access-key	AWSシークレットアクセスキー。AWSアクセスキーIDとセットで使う	任意
aws-session-token	AWSセッショントークン。認証する際に必要だが、基本的に設定することはないはず。	任意
aws-region	AWSリージョン。 es-east-2とか	必須
mask-aws-account-id	クレデンシャルのAWSアカウントIDをシークレット値として設定するかどうか。ログ上のAWSアカウントIDがマスクされるようになります。デフォルトは「true」	任意
role-to-assume	提供されたクレデンシャルを使用してIAMロールを引き受け、Githubアクションにクレデンシャルを付与します。	任意
web-identity-token-file	提供されたファイルパスのWebIDトークンファイルを使用して、WebIDによるIAMロールを引き受けます。例：Amazon EKS worker node内など	任意
role-duration-seconds	ロールの有効時間（デフォルト：６時間）	任意
role-session-name	ロールセッション名（デフォルト：GitHubActions）	任意
role-external-id	引き受けるロールの外部ID	任意
role-skip-session-tagging	ロールの引き受け中のセッションタグ付けをスキップするか	任意

アウトプットプロパティ	説明
aws-account-id	AWSアカウントID

クレデンシャル

GitHub Actionsワークフローで使用されるAWSクレデンシャルについては、AmazonIAMのベストプラクティクスに従うことをお勧めします。

• リポジトリ内コードにクレデンシャルを保存しないでください
• GithubActionsワークフローで使用される資格情報には最小限の特権を付与してください。
• GitHubActionsワークフローで使用されるクレデンシャルのアクティビティを管理してください。

Tips. 基本的にはAmazonIAMのベストプラクティスに則ったほうがいい

ロールを引き受ける

GitHubのOIDCプロバイダーを使用して、アクションに必要な短期間のクレデンシャルを取得することをお勧めします。
aws-access-key-idまたはweb-identity-token-fileを指定せずに引き受けるロールを指定すると、OIDCプロバイダーの利用がアクションに通知されます。
OIDCプロバイダーを使用してIAMロールを直接引き受ける場合、デフォルトのセッション期間は１時間です。
IAMユーザを使用してIAMロールを引き受ける場合のデフォルトのセッション期間は６時間です（aws-access-key-id、aws-secret-access-key、およびロールを指定することにより可能）
このセッション期間はrole-duration-secondsで変更できますが、IAMロールを作った時に定義した最大値を超えることはできません。
デフォルトのセッション名はGitHubActionsであり、role-session-nameで名前を指定することができます。

使用アイデンティティとプロパティの関係

使用するアイデンティティ	aws-access-key-id	role-to-assume	web-identity-token-file
（推奨） GithubOIDCプロバイダーを使用して直接ロールを引き受ける		✅
IAMユーザー	✅
IAMユーザークレデンシャルを使ってロールを引き受ける	✅	✅
WebIdentityトークンファイルのクレデンシャルを使用してロールを引き受ける		✅	✅

Tips. いろいろなやり方でアイデンティティを受け取れるけれど、GithubOIDCプロバイダーを使うのが推奨

Examples

- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-region: us-east-2
    role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role
    role-session-name: MySessionName

この例では、Githubが提供する環境変数からOIDCトークンをロードし、それを使ってセッション名がMySessionNameのロールarn:aws:iam::123456789100:role/my-github-actions-roleを引き受けます。

Tips. GithubOIDCプロバイダーを使用した例

- name: Configure AWS Credentials
  uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-2
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    role-external-id: ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
    role-duration-seconds: 1200
    role-session-name: MySessionName  

この例では、シークレット.AWS_ROLE_TO_ASSUMEにarn：aws：iam::123456789100：role/my-github-actions-roleのような文字列が含まれています。
静的クレデンシャルと同じアカウント内でロールを引き受けるには、role-to-assume：my-github-actions-roleのようにロール名を指定するだけです。

Tips. IAMユーザークレデンシャルを使ってロールを引き受ける例

IAM Role CloudFormation Template サンプル

Parameters:
  GitHubOrg:
    Type: String
  RepositoryName:
    Type: String
  OIDCProviderArn:
    Description: Arn for the GitHub OIDC Provider.
    Default: ""
    Type: String

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

Resources:
  Role:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Statement:
          - Effect: Allow
            Action: sts:AssumeRoleWithWebIdentity
            Principal:
              Federated: !If 
                - CreateOIDCProvider
                - !Ref GithubOidc
                - !Ref OIDCProviderArn
            Condition:
              StringLike:
                token.actions.githubusercontent.com:sub: !Sub repo:${GitHubOrg}/${RepositoryName}:*

  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 

GitHub OIDCプロバイダーはアカウントごとに１つ作成する必要があります。
（つまり、GitHubのOIDCが引き受けることができる複数のIAMロールは単一のOIDCプロバイダーを共有できます）

セッションのタグ付け

セッションの名前は「GitHubActions」で、次のタグが付けられます：（GITHUB_環境変数の定義はここ）

Key	Value
GitHub	"Actions"
Repository	GITHUB_REPOSITORY
Workflow	GITHUB_WORKFLOW
Action	GITHUB_ACTION
Actor	GITHUB_ACTOR
Branch	GITHUB_REF
Commit	GITHUB_SHA

注：すべてのタグ値は要件に準拠している必要があります。
特に、GITHUB_WORKFLOWが長すぎると、切り捨てられます。
GITHUB_ACTORまたはGITHUB_WORKFLOWに無効な文字が含まれている場合、文字は「*」に置き換えられます。

ロールの引き受け時にデフォルトでセッションのタグ付けを使用します。
WebIdentityの役割を引き受けるために、セッションタグはエンコードされたWebIdentityトークンに含まれている必要があることに注意してください。
つまり、タグはOIDCプロバイダーによってのみ提供され、アクション内のAssumeRoleWithWebIdentityAPI呼び出し中に設定することはできません。
アクションの入力でrole-skip-session-taggingをtrueとして指定することにより、このセッションのタグ付けをスキップできます。

Tips. 表のKeyを使うことでセッションタグに任意のGithub環境変数値を付けられる（Commit値とか）

Self-Hosted Runners

EC2インスタンスなどのAWSクレデンシャルにすでにアクセスできるセルフホストランナーでGitHubアクションを実行する場合、IAMユーザーアクセスキークレデンシャルを設定する必要はありません。

アクションの入力にアクセスキーのクレデンシャルが指定されていない場合、このアクションは、AWS SDKforJavascriptのデフォルトのメソッドを使用してランナー環境からのクレデンシャルを使用します。

このアクションを使用して、環境内のリージョンとアカウントIDを設定し、アクションワークフローによって行われるすべてのAWSAPI呼び出しにランナーのクレデンシャルを使用できます。

この場合、ランナーのクレデンシャルにアクションワークフローにより呼び出されるAWSAPIを呼び出すためのアクセス許可が必要です。

または、このアクションを使用してロールを引き受け、アクションワークフローによって行われるすべてのAWSAPIコールにロールクレデンシャルを使用できます。

uses: aws-actions/configure-aws-credentials@v1
with:
  aws-region: us-east-2
  role-to-assume: my-github-actions-role

この場合、ランナーの資格情報には、役割を引き受けるための権限が必要です。

また、Amazon EKS IRSAを使用する場合など、WebIDトークンファイルを使用してロールを引き受けることもできます。 ルートとして実行されないEKSワーカーノードで実行されているポッドは、このファイルを使用してWebIDを持つロールを引き受けることができます。

このファイルを使用するには、ワークフローを次のように構成できます。

uses: aws-actions/configure-aws-credentials@v1
with:
  aws-region: us-east-2
  role-to-assume: my-github-actions-role
  web-identity-token-file: /var/run/secrets/eks.amazonaws.com/serviceaccount/token

Tips. GithubActionのホストランナーを自分でやっているときは、ランナーのクレデンシャルにAWSAPIを呼び出すアクセス権限が必要

AWSCLIで使用

このワークフローでは、AWSCLIを環境にインストールしません。
なのでawsコマンドを実行す流場合、AWSCLIがまだ存在しない場合はインストールする必要があります。
ですが、ほとんどのGitHubホストランナー環境には、デフォルトでAWSCLIが含まれています。

Tips. GithubActionを自分でホストランナーしている場合は、AWSCLIを入れる

終わり

「GithubActionsで簡単にクレデンシャル情報が取れるらしいよ」
「へーやってみよ」
と言って公式ドキュメントを読まず、リリース当時にあがっていたリリース前の情報を見ながら「できない...泣」となっていたのですが、リリース後の公式ドキュメントをよく見たらやり方がバッチリ書いてあってショックだったので今回の記事を書いてみました。
英語なだけで少し敬遠しがちになってしまうのですが、今後は苦手意識を無くしてちゃんと読もうと思いました。（当たり前）
今回執筆するまではcredentialsを取得する最低限のプロパティぐらいしか知らなかったんですが、IFプロパティとかをきっちり理解できた気がしたので満足。