Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

AWS CDKの重要な利点の一つは、コンストラクトプログラミングモデルによる高い再利用性です。自作のCDKコンストラクトをライブラリ化することにより、開発者間での再利用をさらに促進することができます。最近特に注目を集めている開発組織効率化の観点からも、強力な手段となるでしょう。このセッションを聞けば、コンストラクトライブラリ開発に際して必要な最新の情報が整理され今すぐライブラリ開発を始められるようになります。また、自身でも複数のコンストラクトを開発・公開する筆者の視点から、よりライブラリの価値を高めるために意識したいことや、開発・メンテナンスに関するTipsを紹介します。

Masashi Tomooka

July 04, 2024
Tweet

More Decks by Masashi Tomooka

Other Decks in Programming

Transcript

  1. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. 今こそ始める、CDKコンストラクト ライブラリ開発 ― ⼊⾨から実践まで 友岡 雅志 Sr. Prototyping Engineer, AWS Japan AWS CDK Conference Japan 2024
  2. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

    rights reserved. • コンストラクトライブラリ開発に際して知っておくと良いこと 怒涛のN連発 § 初級編 § 中級編 § 上級編 6 お品書き ※ 階級はざっくりな分類です
  7. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. 初級編 7 開発を始める際にはマストで抑えておきたい知識
  8. © 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)
  9. © 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の⽣成/管理 するファイル群
  10. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

    rights reserved. 13 jsii準拠に関するTypeScriptコードの例
  14. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

    rights reserved. 中級編 15 実際開発を始めてから必要になることの多い知識
  16. © 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が書かれる
  17. © 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つの慣例 バージョン番号は開発者からユーザーへの 意思表⽰︕慣例に従うことで誤解を防ぐ
  18. © 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関数のコードをライブラリに含める
  19. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. 19 ライブラリ内におけるLambda関数の定義例 コード例 ※ LambdaAutoDiscover というprojenの機能もあるが、 SingletonFunctionが使えないなどの⽋点もあったので、筆者は使っていない
  20. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

    rights reserved. Inline codeならcfn-responseモジュールも利⽤できる 21 CDKにおけるカスタムリソースの実装例 CloudFormationにハンドラーの結果をコールバックする Node.jsならfetch APIを使うと楽 (追加の依存関係不要なため) ↑ CDK側のコード Lambda側のコード ↓
  22. © 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 アプリケーションのためのインテグレーションテストの作成と実⾏
  23. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. IntegrationTestというinteg-runnerを導⼊するための機能もprojenにあるが、 筆者は使ったことなし。試した⽅はぜひ教えて下さい︕ 23 integ-runner導⼊の例
  24. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. 上級編 24 知っているとより良いものを開発できる (かもしれない) 知識
  25. © 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
  26. © 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 会場アンケート どこまでターゲットにすべきでしょうか︖
  27. © 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はどうする︖
  28. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

    rights reserved. 開発してみて気づいたことやコツなどが⾒つかれば、ぜひ発信してください︕ 29 必要な知識はさらに発⾒される…
  30. © 2024, Amazon Web Services, Inc. or its affiliates. All

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

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

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

    rights reserved. まとめ • CDKコンストラクトライブラリ開発において考えたいことを紹介しました • このような資料があることだけでも覚えておいていただければ幸いです • ライブラリ開発には新鮮な学びと喜びがあるので、ぜひトライしてみてください 本資料のURLはこちら︕
  35. © 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 参考情報
  36. © 2024, Amazon Web Services, Inc. or its affiliates. All

    rights reserved. Thank you! Masashi Tomooka [email protected] GitHub / 𝕏: @tmokmss 36
  37. © 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