AWS CDKソースコードにおけるREADMEの内容を考える #4.5
はじめに
現在、AWSCDKでCloudFrontによる静的ウェブサイトの配信を構築しています。
AWS CDK S3静的ウェブサイトホスティング構築 TypeScript #1
AWS CDK S3+CloudFrontウェブサイト構築 Typescript #2
AWS CDK S3＋CloudFront＋Route53+ACM ウェブサイト構築 TypeScript #3
AWS CDK CloudFront監視入門 TypeScript #4
各回で作成したコードをGitHubで管理しているのですが、
READMEファイルがcdkプロジェクト作成時のままになっていました。
AWSでリソースを構築する時にはマネジメントコンソールを使用したり
CDKやTerraformを使う時もハンズオンをやって終わりだったので
個人作成のREADMEを考えたことがありませんでした。
なので今回はAWS CDKのソースコードにおいてどんな内容をREADMEに書けばいいのか整理していきます。
READMEに書くべき内容
GitHubに公開されているAWSのソースコードを確認すると
構成図が載っていたり、デプロイの手順が書いてある印象です。
生成AIや記事などを参考にしつつ以下の内容をREADMEに書くことにしました。
-
概要：本ソースコードに記述している内容を説明します
-
構成図：AWSなのでデプロイされるリソースを視覚的にわかりやすく表現します
-
デプロイ手順：ソースコードを見た人がZennの記事を見なくてもリソースを展開できるような手順を記します。
概要
まずソースコードが何を記しているかなので
AWS CDKによるリソースデプロイを目的としていることを記載します。
CDKは複数の言語で記述できるのでTypescriptで書いてることにも言及。
そしてデプロイするリソースについても言及します。
AWS CDK(typescript)を用いて以下の構成要素をデプロイします。
- S3バケットをオリジンとするCloudFrontディストリビューション
- 独自ドメインのRoute 53連携
- Certificate Managerによる独自ドメインを使用したHTTPS対応
- CloudWatchメトリクスを使用した監視設定
- CloudTrailデータイベントログを利用したS3バケット操作検知
- CloudFrontアクセスログの取得
また、このコードは記事シリーズが続く限りアップデートされていくので
今後の展望もtodoとして残しておくことにしました。
構成図
AWSの構成図を作成できるツールはいくつかあります。
(AWS公式が出してるパワポ用素材を使うのも可)
私は無料で使用できるツールとしてdrawioを選択しました。
drawioファイルを表示させるのはひと手間必要だったので
pngファイルとしてエクスポートしてソースコード内に格納しました。
デプロイ手順
このソースコードをローカルに落として実際にリソースをデプロイするための手順を記述します。
CDKを利用する関係上、バージョンなどの要素が理由でデプロイができない可能性があるので
前提条件として当時私が使用していたCLIのバージョンなども記載します。
デプロイ手順の他、今回はSNSメール設定やドメイン名を参照するので
cdk.jsonの編集が必要な旨も記載。
おわり
今回はソースコードのREADMEを更新してみました。
個人学習のときは後回しになってしまいがちだったのですが、
考え方を整理しておけば業務にも生かせる知識なので
コード本体が優先されすぎない程度に今後もアップデートをしていきたい部分ですね。
それでは、最後までお読みいただきありがとうございました。
ソースコード
参考
Discussion