今こそ始める、CDKコンストラクトライブラリ開発 ― 入門から実践まで

Slide 1

Slide 1 text

Slide 2

Slide 2 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 話すこと • AWS CDKコンストラクトライブラリを開発する上で知っていれば得することを時間の許す限り列挙します • コンストラクトライブラリを開発する際のお供に、この資料を捧げます • 話さないこと • AWS CDK⾃体に関する基礎知識は前提とします • Black belt を履修しましょう︕︕ • CDKに特化しないライブラリ開発⼀般の話 • AWS Summit Japan 2024での発表もご覧ください (後述)︕ 内容について

Slide 3

Slide 3 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 友岡雅志 Sr. Prototyping Engineer @AWS Japan CDK経験前職のオンプレ→AWS移⾏で採⽤ (2019/12 - 2020/10) AWS社内サービスの運⽤開発 (2021/7 - 2022/3) プロトタイプ開発に利⽤ (2020/11 – 現在) 最近作ったCDKコンストラクト opensearch-rest-resources: OpenSearch Service内の諸リソースをCFn管理 deploy-time-build: コンテナイメージをデプロイ時ビルドする機能を追加 CallAwsServiceCrossRegion: Step FunctionsでクロスリージョンAWS APIコール 3 ⾃⼰紹介 𝕏: @tmokmss

Slide 4

Slide 4 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. CDKライブラリ開発には CDKアプリケーション開発とも CDKコントリビューションとも異なる側⾯があります Let’s dive deep! 👉 ⾃作コンストラクトをライブラリ化するメリット • 🤝 より広い範囲での再利⽤が促進される § npm install など1コマンドで導⼊できるのは楽︕ § OSSなら全世界のCDKユーザーにお届け︕エコシステムにも貢献 • 🔐 パッケージマネージャーの仕組みでセキュアに § 古いバージョンのdeprecationをユーザーに通知したり § セキュリティ的にマズいバージョンは更新を促したり • 📝 ⼀開発者としての学びが多い § OSSやライブラリのメンテナンスには、特有の知識が必要 § PdMやマーケティング的な思考が要求される側⾯もある 4 コンストラクトライブラリをつくる理由コンストラクトライブラリの例 • cdk-nag • cdk-ecr-deployment • cdk-remote-stack • AWS PDK

Slide 5

Slide 5 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 5 ライブラリの配布⽅法 aws-cdk-lib open-constructs GitHub self-publish 概要 CDK公式ライブラリコミュニティ主導のライブラリ⾃分⾃⾝でパッケージを公開メリット • 最も有名で利⽤されやすい • 実績ある管理構成を利⽤可能 • 既存コンストラクトに対する機能追加の提案は結構通る • よく検討された管理構成を利⽤可能 • 拡⼤フェーズのため、提案は通りやすい様⼦ (レビューも速い) • ユーザ視点、ある程度の信頼感 • 宣伝は他の開発者と協⼒可能 • 完全なオーナーシップを得る (⼀国⼀城の主) • リリースまでの時間は最速 • パッケージごとの利⽤数を把握しやすいデメリット • 全く新規の機能は提案を通すのが困難かもしれない • PR作成からマージまでの時間は⻑め (要レビューのため) • 新しい機能は古いCDKからは利⽤不可 • 今は黎明期のため、今後の変化幅は⼤きいかもしれない • L3の提案に対しては消極的か • 管理構成を⾃分でセットアップする必要がある • メンテナンスの全責任を負う • 宣伝も⾃分で頑張るしかないフォルダ構成やリンターの設定、テスト・セキュリティのポリシー、コーディング規約など、あるパッケージを管理するうえで決める必要がある諸々の事項をここでは指す ※管理構成 : 既存機能の拡張はこれ︕ 新規のL2はこれ︕ オールマイティ︕ 今⽇はここ向けの話が多いです

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 2020年初稿のhayao_kさんによる記事から⼤きな変化はなし︕ § projen ではじめる快適 AWS CDK Construct Library 開発⽣活 § Projenの詳細はこちらも: AWS Blog - Projen と AWS CDK のはじめ⽅ • 始め⽅: 空のディレクトリで npx projen new awscdk-construct を実⾏する § 必要なプロジェクト構成が⾃動的に構築される § デフォルトの構成: GitHub ActionsでCI/CD, npmにpublish, yarn v1を利⽤など § .projenrc.ts でプロジェクトの構成を管理できる – IaCで例えるなら CDKコード : 実際のAWSリソース = .projenrc.ts : 実際のプロジェクト構成 8 CDKコンストラクトライブラリ開発の始め⽅ ※ それ以外に、npmへpublishするため、NPM_TOKEN環境変数の設定だけ必要 (doc)

Slide 9

Slide 9 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 初期状態のprojenrc.ts (v0.82.6時点) • Projenは⼀部のコードや構成ファイルを .projenrc.ts で中央管理する § package.json や .prettierrc など。ファイル内の注釈やパーミッション (-r--r--r--) で識別可。 • 直接編集やnpm installなどのコマンドは利⽤禁⽌ (c.f. IaCのドリフト) 9 .projenrc.ts Projenの⽣成/管理するファイル群

Slide 10

Slide 10 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • CDK⾃体と書き⽅や体験は似ている § 出⾃は同じでもあるので • API Referenceを⾒ながら書くと良い Tips • PyPIへのリリースはこちらも参照 § ⾃作コンストラクトをPython向けに公開する • depsはゼロにするのがオススメ § 開発者・ユーザーともにメンテが楽になる § パッケージに付随する依存関係となるため § ※ devDepsは(ユーザー⽬線では)無関係 10 逆引き .projenrc.ts のカスタマイズ例

Slide 11

Slide 11 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • コンストラクトライブラリのカタログとなるWebサービス GitHub • パブリックなインスタンスは https://constructs.dev/ からアクセス可能 § 通常はConstruct Hubといえば、このパブリック版のことを指すことが多い § 規定の条件に準拠するライブラリは、⾃動的にカタログに掲載される 11 Construct Hubについて 2024年7⽉現在、1000を超えるAWS CDK向けライブラリが掲載されている

Slide 12

Slide 12 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • jsii: TSで書かれたライブラリをPython, Javaなど他⾔語で利⽤するための仕組み § Construct Hubに登録するにはTSコードをjsii仕様に準拠する必要がある (制約付きのTS) • メジャーな制約の例 (ただしexportされたAPIに限る。内部実装では特に制約なし) § 名前の種類ごとにcamelCase, PascalCaseなど遵守が必要。 § Union型の利⽤は推奨されていない (Javaなどで不都合なため)。代わりにenumを使う。 § 関数は直接引数に取れない。Behavioral interface (IConnectableなど) が代替⼿段となりうる。 § interface内でプロパティをネストする場合は、⼦プロパティを別interfaceに切り出す必要あり § Partial/OmitなどGenericsも使⽤不可。jsii-struct-builder (コード⽣成) という代替⼿段はある。 § その他、違反したらビルド時にエラーが出るので、それに従えば良い 12 jsii-compliantなTypeScriptを書く詳細はこちらも参照: The jsii type system

Slide 13

Slide 13 text

Slide 14

Slide 14 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 前述の制約を避けるために、TypeScript専⽤の道を⾏くライブラリもある § AmplifyAuth, CDK decorators など。APIの使いやすさ <-> 対象ユーザーを狭めるリスク • とはいえPythonユーザーは無視できる数ではない (下図) と筆者は考えている 14 jsiiに準拠しない選択も⼀応可能だが… CDK Community Survey 2023よりよほどの事情がないかぎりは jsii準拠がオススメ

Slide 15

Slide 15 text

Slide 16

Slide 16 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 筆者がユーザーなら必須で抑えられてほしい項⽬ 1. そのライブラリがどのようなユーザーの問題を解決するものか、1〜2⾏で 2. 代表的なユースケースにおける利⽤⽅法 (コピペ可能なCDKコード) – Tip: TypeScriptで書けば、jsiiがビルド時に他⾔語へ翻訳してくれる 3. 他の⽅法との⽐較、そのライブラリの優位性 4. (L3なら) AWSアーキテクチャ図 5. Construct Hubへのリンク (API Referenceとして機能する) • 書き⽅はCDK API Reference 各モジュールのOverviewも参考にすると良い § 例: aws_s3 module 16 README.mdの書き⽅開発する前に書くのも有効 (PR/FAQ⾵) aws-cdk-libでも実装前にRFCが書かれる

Slide 17

Slide 17 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • Semantic versioning: MAJOR.MINOR.PATCH のバージョン番号表記 (例 2.144.0) § MAJOR: メジャーバージョン番号。これのbumpは破壊的変更を意味する。 § MINOR: マイナーバージョン番号。これのbumpは機能追加を意味する。 § PATCH: パッチバージョン番号。上記以外の変更ではこれをbumpする。 • Conventional commits: コミットメッセージにルールを与え、バージョン番号の採番を楽に § コミットメッセージに内容を⽰す接頭辞をつける例: feat=機能追加 fix=バグ修正など § 接頭辞に “!” を付加すると、破壊的変更を意味する例: feat! / fix! § GitHub上のリリースノートも、コミットメッセージから⾃動的に⽣成される 17 Semantic versioningとconventional commits ←は超ざっくりの理解正確な仕様はこちら ※ projenではメジャーバージョン番号だけ特別に扱われる。詳細はこちらのドキュメントを参照: Releases and Versioning 正確な仕様はこちら Projenで従う2つの慣例バージョン番号は開発者からユーザーへの意思表⽰︕慣例に従うことで誤解を防ぐ

Slide 18

Slide 18 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • NodejsFunctionなどsynth時にビルド処理が⾛る⽅法はオススメしない § ユーザーにとって無駄な計算リソースだから。インストール時点でビルド済みである⽅が良い • ⽅法: Projenのビルド中に関数のコードもビルドする § prependExecで任意の処理を挿⼊可能 § 右図はlambda/some~ 内のコードを projen build時にビルドする例 • Tip1: カスタムリソースのハンドラーはSingletonFunctionを利⽤すると良い § 何度定義しても、同⼀スタック内に実体は⼀つだけになるLambda関数のコンストラクト • Tip 2: Inline code (ZipFile) なら、コードのデプロイにS3アセットが不要になる § StandaloneなCFnテンプレートになる利点。バンドル・minifyできるNode.jsなら有効な選択肢 18 Lambda関数のコードをライブラリに含める

Slide 19

Slide 19 text

Slide 20

Slide 20 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 3種のイベント処理を実装するだけで、CFnから任意のリソースを管理できる機能 § CREATE: リソースの新規作成時に呼ばれる § UPDATE: プロパティに変更があったときに呼ばれる § DELETE: リソース削除時と物理リソースIDが変更されたときに呼ばれる • 下図はカスタムリソースデプロイ時の挙動 (左: 新規作成時右: 更新時) 20 CloudFormationカスタムリソースに関する知識コンストラクトライブラリではよく使うネタ︕(⾃作は⼤変なので) その他詳細はこちらのドキュメントを参照

Slide 21

Slide 21 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. Inline codeならcfn-responseモジュールも利⽤できる 21 CDKにおけるカスタムリソースの実装例 CloudFormationにハンドラーの結果をコールバックする Node.jsならfetch APIを使うと楽 (追加の依存関係不要なため) ↑ CDK側のコード Lambda側のコード ↓

Slide 22

Slide 22 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • ライブラリ開発では、CDK integ-runnerの導⼊を強くおすすめする § aws-cdk-libのために開発された、CDKコードのintegration testフレームワーク • ライブラリ開発においてinteg-runnerを使うメリット § ✅ CFnレベルで破壊的変更がないことの⾃動検証が可能に (後⽅互換性・リソースの置換など) § ✅ スナップショットテストも兼ねる ✅ カスタムリソースハンドラーの動作検証 22 integ-runnerを導⼊する AWS Blog - AWS CDK アプリケーションのためのインテグレーションテストの作成と実⾏

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • そのライブラリがサポートする最⼩の CDKバージョンを表明する必要がある § 例: apigatewayv2に依存するので v2.112.0 以上が必須 • 最⼩バージョンでの動作は必ず検証する (integ-runnerを使うのが良い) § それ以上のバージョンで動作することは、CDKの後⽅互換性から保証される • バージョン選択に関するトレードオフ § 最⼩バージョンを上げるほど: ライブラリ内で使えるCDKの機能が豊富になる § 最⼩バージョンを下げるほど: ライブラリを使えるユーザーが増える (定量的データは不明) • 代表的なバージョン § 2.38.0: integ-runner v2系がnpmに登場 § 2.77.0: 多くのカスタムリソースでNode.js 14の利⽤を廃⽌ 2.87.0: 同Node.js 16を廃⽌ 25 最⼩CDKバージョンの選択 ※open-constructsにおける議論も参考になる: Issue #36

Slide 26

Slide 26 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • CDK (aws-cdk-lib) のバージョンはどれを利⽤していますか︖ 複数プロジェクトに関わる⽅は当てはまるものをすべて🙋︕ 1. v1.x.x 2. v2.0.0 – 2.37.x 3. v2.38.0 – 2.77.x 4. v2.78.0 – v2.120.x 5. v2.121.0 - latest 26 会場アンケートどこまでターゲットにすべきでしょうか︖

Slide 27

Slide 27 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • CDKでは破壊的変更の導⼊をユーザーに明⽰的に選択させるため、 Feature flagという機能がある (⼿元のcdk.jsonを⾒てみて︕詳細はこちら) § ある機能に対するフラグ切り替え前後では、その機能の後⽅互換性は保証されないので、厳密に動作を保証するためには両パターンで検証の必要がある • 2.141.0時点で40個以上のフラグが存在する § CDKの可能な動作パターンは、理論上2^40=10^12通り以上存在することになる • 全パターン網羅する検証は不可能だが、いくつかの代替⽅法は考えられる 1. ライブラリの機能に関連するフラグを調べ、そのフラグだけON/OFFして検証 – 注意: 検証にはフラグが導⼊された以降のCDKバージョンを使う必要あり︕ 2. 最⼩CDKバージョン(全フラグ無効)と最新CDKバージョン(全フラグ有効) の2パターンのみ検証 3. 気にしない。バグが潜んでいても、ユーザーに報告されてから直せば良い。 27 検証時、CDKのfeature flagはどうする︖

Slide 28

Slide 28 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 実際は深刻なfeature flagは多くないので、ライブラリ開発者が過敏になる必要はないと筆者は考えている「もしかしたら破壊的変更になるかもしれないから⼊れました」という程度のフラグも多いためただし、ごく⼀部のパターンでしか検証できていないことは認識しておくと良い 28 Integ runnerでfeature flagをON/OFFする⽅法 Appのcontextプロパティからフラグの値を渡すことができる (snapshot testでも使える⽅法)

Slide 29

Slide 29 text

Slide 30

Slide 30 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • 今回はCDKに特化した話をまとめました • ライブラリ開発⼀般の話は拙作のAWS Summitの発表をご覧ください 30 ライブラリ開発⼀般の話 AWS CDKコンストラクトの実例から⾒る開発組織効率化とライブラリ開発の妙資料動画ライブラリ開発というテーマについて、何をライブラリ化するか、設計の⽅針、広報の重要性という観点から、ライブラリ開発者が考えたいことをまとめました。次ページからダイジェスト版を少しお⾒せします

Slide 31

Slide 31 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. ライブラリの存在意義 = 何をなぜ作るか • コツ: 需要ベースで考える • 潜在的なユーザー数を探る: 社内やインターネット上に困っている⼈がいるか︖ • 既存の代替⼿段を探す: 何をどう解決しているかそれらの改善できる部分は何か • もし代替⼿段が存在しないなら、それはなぜか︖ • そもそも解決策＝ライブラリの開発とはならない問題もある • あまりにも単純な問題は、スニペットの提供で⼗分かもしれない • 解決策を共通化できるほど問題を絞り込めない • → 将来の複雑化が容易に予⾒できる 💡 Amazonでは存在意義を明⽂化する慣習もある Tenets: supercharging decision-making

Slide 32

Slide 32 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. UX指向のAPI設計 • API: (ここでは) どのようにライブラリを呼び出すかの決め事 • 例: 関数の名前、引数の与え⽅、戻り値の受け取り⽅などライブラリにおいてはユーザー体験 (UX) への影響が⼤きい • コツ: ユーザー体験を起点に考える • まずはUXを追求してAPIを設計する実装の詳細を考えるのはその後 • APIを実装の詳細に引きずらせない不要なことをユーザーに意識させない • 使いやすさの要因 • 単純さ : より単純なコードで⽬的を達成できれば、使いやすい • 慣れ : 従来の⽅法と似たような使い⽅ができれば、使いやすい 💡 Amazonではこの思考法が⽂化として根付いている Working Backwards

Slide 33

Slide 33 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. 広報活動の例 • 事例1: opensearch-rest-resources • 同僚に共有 → 確実な利⽤者を獲得 • 検索でヒットするGH Issueやre:Postに解決策を投稿した → 1000 downloads/week到達 • 事例2: cdk-lambda-llrt • LLRTのLambda関数を作るライブラリ • 𝕏でLLRTのバズりに便乗 • LLRT公式のREADMEにも掲載を依頼 • → 1500 downloads/week到達

Slide 34

Slide 34 text

Slide 35

Slide 35 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • aws-cdk/CONTRIBUTING.md § aws-cdk-libに機能追加したいときは、こちらを読みましょう • open-constructs/aws-cdk-library/CONTRIBUTING.md § open-constructsに機能追加したいときは、こちらを読みましょう • AWS CDKコントリビュートTIPS § 後藤HEROによるコンストラクト開発のTIPS。API設計やエラー処理に関する知⾒ (必読です) • mrgrain/cdk-esbuild § ProjenメンテナのMomoさんが開発するCDKコンストラクトライブラリ。projenrcの書き⽅や管理構成は参考になる。注) 結構複雑なので、最初からこれを真似るのが必ずしも良いわけではない 35 参考情報

Slide 36

Slide 36 text

Slide 37

Slide 37 text

© 2024, Amazon Web Services, Inc. or its affiliates. All rights reserved. • Q. npmに公開したけどConstruct Hubに掲載されない § A. 反映に数⼗分掛かることがある。keywordにaws-cdkを含む必要あり – その他具体的な条件はこちら: Why isn’t my package displayed on Construct Hub? 37 CDKコンストラクトライブラリ開発に関するFAQ