albertshih.net は Astro で生成した静的サイトで、Amazon S3 に置き、前段に CloudFront を置いています。この記事では、構成全体と各選択の理由を記録します。
構成の全体像
GitHub に push すると、GitHub Actions が OIDC で一時的なロールを取得し、ビルド結果を S3 にアップロードします。訪問者は CloudFront 経由で配信を受け、ドメインと証明書は Route 53 と ACM が担当します。
| コンポーネント | 用途 | 選んだ理由 |
|---|---|---|
| Astro | 静的ページの生成 | コンテンツは Markdown が中心で、ビルド結果はそのまま HTML になる |
| S3(非公開) | サイトファイルの保管 | 静的ウェブサイトホスティングは使わず、OAC 経由で CloudFront だけが読める |
| CloudFront | CDN と HTTPS | 世界規模のキャッシュ。CloudFront Function で index.html と www のリダイレクトを処理 |
| ACM(us-east-1) | TLS 証明書 | CloudFront は us-east-1 の証明書しか受け付けない |
| Route 53 | DNS | ドメインも Route 53 で取得し、Alias レコードで CloudFront に直接向ける |
| GitHub Actions + OIDC | 自動デプロイ | GitHub に長期のアクセスキーを置かない |
| Lambda Function URL | 執筆用管理画面の GitHub ログイン | ログイン時だけ実行されるので、コストはほぼゼロ |
デプロイの流れ
mainに push する- GitHub Actions が OIDC で一時的な IAM ロールを取得する
astro buildのあとaws s3 syncでアップロードする。HTML はキャッシュせず、それ以外は長期間キャッシュする- CloudFront のキャッシュ無効化を作成する
学んだこと
ゼロから公開までに本当に時間がかかったのは、ページを書くことではなく、「初回デプロイで初めて起きる」次のような落とし穴でした。
1. GitHub の OIDC subject は、もう repo:owner/repo だけではない
最初の push のあと、GitHub Actions が Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity で止まりました。IAM ロールの信頼ポリシーも、OIDC プロバイダーの audience も正しいのに、です。最後にリポジトリの OIDC 設定を調べて分かりました。新しいアカウントでは既定で「不変 subject」が使われ、形式が repo:owner@<オーナー ID>/repo@<リポジトリ ID>:ref:refs/heads/main になります。固定で書いていた repo:owner/repo:ref:refs/heads/main では、当然一致しません。
対応として、信頼ポリシーを StringLike に変え、従来の形式と ID 付きの形式の両方を許可しました(ID の部分はワイルドカード)。これでテンプレートに数字を固定で書かずに済み、リポジトリの名前変更や作り直しでも壊れません。それでいて、デプロイ用ロールを取得できるのは、このリポジトリの main ブランチだけに限定されます。
2. 最小権限は「実行して、足して、を繰り返す」もの
まず自分の IAM ユーザーに、リソース名で絞った最小権限のポリシーを書きました。ところが初回のデプロイで、CloudFront ディストリビューションの作成中に cloudfront:ListTagsForResource が足りず失敗しました。CloudFormation はリソース作成中に、思いもよらない API を呼びます。テンプレートを読むだけでは、全部は洗い出せません。
知っておくべき副作用が二つあります。
- 失敗するとスタックは
ROLLBACK_COMPLETEで止まり、この状態は更新できません。削除して作り直す必要があります。 Retainを付けた S3 バケットはロールバックでも残るため、次のデプロイで空のバケットが一つ増えます。
私の結論は、最小権限は一発で正しく書けるものではない、ということです。デプロイを失敗させ、エラーを読み、権限を足す。これを何度か繰り返してポリシーを固め、デプロイが終わったらその権限は外します。
3. NoEcho パラメータが空でも、CloudFormation は教えてくれない
GitHub OAuth のクライアントシークレットは、NoEcho パラメータで Lambda に渡しています。最初に read -s でシークレットを読み込みましたが、キーボード入力のない環境で実行したため、シークレットが空文字になりました。それでもスタックは成功と表示されました。気づいたのは管理画面にログインしたときで、GitHub が The client_id and/or client_secret passed are incorrect を返しました。
確認には Lambda の環境変数を読みましたが、見たのは長さと形式(GitHub のシークレットは 16 進数 40 文字)だけで、値は出力していません。教訓は二つです。
- デプロイの成功は、リソースができたことを意味するだけで、設定が正しいことは意味しません。検証できるチェックが必要です。
- 機密情報は、記録されない自分のターミナルで入力します。
4. デプロイの順序で、訪問者が見るのが新しいサイトか、スタイルのないページかが決まる
Astro の CSS と JS のファイル名にはハッシュが付きます。最初のフローは、先に _astro/ を --delete 付きで同期し、そのあと HTML をアップロードする順でした。そのため、しばらくの間、古い HTML が CloudFront のキャッシュに残ったまま、すでに削除された古いファイルを取りに行き、404 になってページ全体のスタイルが消えました。
修正後の順序は、新しいアセットを先にアップロード(削除しない)、次にページをアップロード、キャッシュ無効化を作成して完了を待ち、そのあとで古いアセットを削除する、というものです。無効化の完了を待つには、デプロイ用ロールに cloudfront:GetInvalidation 権限を追加する必要があります。
5. 公開の Lambda Function URL には権限が二つ必要
執筆用管理画面の GitHub ログインには、Lambda Function URL(AuthType: NONE)を使っています。lambda:InvokeFunctionUrl に加えて、「Function URL 経由」の呼び出しだけに限定した lambda:InvokeFunction を追加しました。両方をテンプレートに入れたところ、ログインのエンドポイントは最初から正常に 302 を返し、Forbidden は出ませんでした。この制限を付けない lambda:InvokeFunction は、誰でも関数を直接呼べる状態になるので、そう書いてはいけません。
6. 公開後に気づく、小さな落とし穴
- リダイレクトでクエリ文字列が消える:CloudFront Function で www のリダイレクトや末尾スラッシュの補完をするとき、
uriだけで URL を組み立てると?utm_source=...が消えます。querystringオブジェクトから組み立て直し、同じ名前のパラメータが複数ある場合も処理します。 - OAuth のスコープ:管理画面は最初
repo,userを要求していました。これはアカウントのすべての非公開リポジトリへの読み書きにあたります。使わないuserは外しました。リポジトリが非公開ならrepoが必須で、public_repoに下げられるのは公開リポジトリだけです。 - サードパーティのスクリプトはバージョンを固定する:管理画面は書き込み権限のあるトークンに触れられるのに、CMS を CDN から浮動バージョンで読み込んでいました。バージョンを固定して SRI を付けました。アップグレードのときは、ハッシュを自分で計算し直します。
- 未完成のコンテンツは公開しない:CI で
dist/を走査し、角括弧で囲んだ記入待ちの文字や、空のソーシャルリンクが残っていればデプロイを失敗させます。記憶に頼るより確実です。 - CloudFormation テンプレートはなるべく ASCII だけにする:インラインの Lambda コードに「…」を一つ入れたところ、Windows の AWS CLI が cp950 でファイルを読み、デコードエラーになりました。
もう一度やるなら
先に「何をもってデプロイ完了とするか」を決めます。スタックが緑になるだけでなく、トップページ、/admin、OAuth のエンドポイント、www のリダイレクト、パラメータ付きのリンクを、一つのコマンドで検証できるようにします。今回はこれらのチェックを、問題が起きてから一つずつ足していきました。