https://blog.cybozu.io/entry/2026/03/12/173000

この記事は kintone の生成 AI チームで連載中の kintone AIリレーブログ 2026 の 9 本目の記事です。リレーブログでは、生成 AI チームのメンバーが AI トピックに限らずさまざまなことについて発信していきます。

こんにちは！

kintone 生成 AI チームの 386jp です。

前回の記事「cdk8s をもっと使いこなす - kintone AI チームの活用 Tips」では、 cdk8s を使う上で工夫している実践パターンを紹介しました。

今回は、 cdk8s で生成したマニフェストをどのようにデプロイしているか、デプロイ戦略について紹介します。

前回のおさらい

前回の記事では、 cdk8s を使う上での実践パターンとして、以下の内容を紹介しました:

core/apps の分離: インフラコンポーネントとアプリケーションを分けて管理
YAML による設定管理: 環境ごとの差異を柔軟に管理
CRD の型安全な扱い: TypeScript の型定義として取り込み、型安全に記述
再利用可能な Construct: 共通パターンをまとめて開発速度を向上

cdk8s をプロダクション運用する上での 3 つの課題

cdk8s を使って Kubernetes マニフェストを TypeScript で柔軟に生成できるようになった一方で、それを実際のプロダクション環境へ安全かつ確実にデプロイするためには、いくつかの運用上で考えるべき課題がありました。

実際にデプロイされるマニフェストが不透明になりがち Argo CD のプラグインなどで動的にマニフェストを生成させた場合、「結局何がデプロイされるのか」が直前まで分かりにくく、事前の差分レビューが困難になります。
コードと生成物が混在し管理が複雑化する cdk8s のソースコードと、生成された YAML マニフェストを同じリポジトリで管理すると、コミットログが混ざり合い、ブランチ戦略も複雑になってしまいます。
複数環境への段階的デプロイをどう安全に行うか dev、staging、prod と複数の環境がある中で、どうやって安全にマニフェストを昇格（プロモート）させていくかというフローの確立が必要です。

これらの課題に対して、kintone 生成 AI チームがどのようにアプローチしたのか、具体的なデプロイ戦略と工夫を紹介します。

課題1へのアプローチ：マニフェストの事前生成と書き出しの工夫

「実際にデプロイされるものが不透明になる」という課題に対し、私たちは マニフェストを事前に生成して Git で管理する方式 を採用し、さらに 書き出し方にも工夫 を凝らしています。

マニフェストを事前に生成するメリット

cdk8s のマニフェストの生成方法、そして Argo CD と sync させる方法は、いくつかの選択肢があります。例えば、 cdk8s のマニフェストを直接 Argo CD で読ませるプラグインを開発し、都度 Argo CD 側でマニフェストを生成させる方法も考えられます。しかし、 EKS Capabilities として提供されている AWS マネージドの Argo CD を採用していることや、プラグイン開発のコストを考慮し、この方式は採用しませんでした。

結果として、マニフェストを事前にすべて生成することで、 Git 上で事前に確実な差分レビューが可能になり、デプロイの透明性が保てる運用を構築することができました。

マニフェストの書き出し方の工夫

では、どのようにマニフェストを書き出しているかについて紹介します。私たちは、 1 つのコードベースで、設定用の yaml ファイルなどを活用しながら、複数の環境のマニフェストを同時に出力するようにしています。

マニフェストが自動生成されているため、きちんと差分を確認しながらマニフェストをリリースしていきたいものです。そこで、私たちは、 cdk8s App を定義する際に、以下のような設定にしています。

new App({
    outdir: `dist/${env}/${category}`,
    yamlOutputType: YamlOutputType.FOLDER_PER_CHART_FILE_PER_RESOURCE,
});

ここでの env は dev, staging, prod のような環境名を、 category は core, apps のようなスタックの種類を指しています。

core, apps に関する説明は前回の記事「cdk8s をもっと使いこなす - kintone AI チームの活用 Tips」をご覧ください。

FOLDER_PER_CHART_FILE_PER_RESOURCE の効果

私たちは、 yamlOutputType をデフォルトの FILE_PER_CHART から FOLDER_PER_CHART_FILE_PER_RESOURCE に変更しています。これにより、各リソースが個別のファイルに出力されるため、差分表示を行う際にどのリソースに変更があるのか、一目でわかるようになります。

FILE_PER_CHART では、大量のリソースが一つのファイルに格納されてしまうため、 diff コマンドで見るときに、どの Kubernetes リソース (リソース名やリソースの種類)に差分があるのか一目で把握しづらく、差分を見落とすリスクがあります。

課題2へのアプローチ：GitOps 用リポジトリとの分離

「コードと生成物が混在し管理が複雑化する」という課題に対しては、cdk8s のコードと生成されたマニフェストをそれぞれ 2 つの別々のリポジトリ で管理することで解決しています。

2 つのリポジトリ構成

cdk8s コードリポジトリの役割:

TypeScript でマニフェストのロジックを記述
環境別の設定ファイルを管理
テストやビルドを実行

GitOps 用リポジトリの役割:

生成済みのマニフェストを配置
dev/staging/prod のブランチで環境を分離
Argo CD がこのリポジトリ・ブランチを参照してデプロイ

なぜ 2 つのリポジトリに分けたのか

当初、 1 つのリポジトリで cdk8s のコードと生成されたマニフェストを管理することも検討しましたが、以下の理由から 2 つのリポジトリに分離する方式を採用しました:

1. ブランチ戦略とマニフェスト管理が明確になる

1 つのリポジトリで「コード用のブランチ」と「生成物用のブランチ」を並列管理すると、ブランチ戦略が複雑になります。リポジトリを分けることで、 GitOps 用リポジトリには常に生成済みのマニフェストだけが配置され、 Argo CD が参照するマニフェストの状態が明確になり、それぞれのリポジトリで独立したブランチ戦略を取ることができます。

2. コミットログがきれい

同一リポジトリで管理すると、コードの変更コミットと生成物の更新コミットが混在し、コミットログが見づらくなります。リポジトリを分離することで、各リポジトリの役割が明確になり、コミットログも整理されます。

課題3へのアプローチ：段階的デプロイを実現する CI/CD パイプライン

最後の課題「複数環境への段階的デプロイをどう安全に行うか」については、2つのリポジトリを連携させた直列の CI/CD パイプラインを構築しています。

デプロイフローの全体像

実際にどのようにデプロイが行われるのか、全体のフローを見ていきましょう。

cdk8s のコードを main ブランチにマージすると、 GitHub Actions が自動的にマニフェストを生成し、 GitOps 用リポジトリの dev ブランチにプッシュします。その後、 GitOps 用リポジトリ側の CI/CD パイプラインが起動します。

dev 環境で Argo CD Sync と smoke test が実行され、成功すると staging ブランチへの merge PR が自動作成されます。 PR をマージすると同様に staging 環境でテストが実行され、成功すれば prod ブランチへの PR が作成されます。このように、段階的に各環境へマニフェストが昇格していきます。

cdk8s コードの PR での変更確認

ここからは、この 2 つのリポジトリ構成において、 CI/CD パイプラインがどのように動くのか、具体的なステップを見ていきます。

cdk8s コードリポジトリで PR を作成すると、 GitHub Actions が自動的に以下の処理を実行します:

テストの実行: マニフェスト生成に使用するロジックの Jest ユニットテストを実行
マニフェストのビルド: 各環境用のマニフェストを生成
PR コメントへの投稿: 生成されたマニフェストのファイルリストを PR コメントに表示

現在は、生成されたファイルのリストを PR コメントに表示しています。今後はマニフェストの差分（diff）も PR コメントに表示できるようにする予定です。これにより、 cdk8s のコードを変更した際に、実際にどのマニフェストがどう変わるのかを PR 上で確認しやすくなります。

段階的デプロイと自動検証

PR がマージされ、 GitOps 用リポジトリの dev ブランチへマニフェストがプッシュされると、前述の図のように段階的に各環境へデプロイされます。各ステップは完全に直列化されており、前の環境での Argo CD デプロイと smoke test が成功しないと次の環境へは進まないようになっています。

まとめ

本記事では、 kintone 生成 AI チームが cdk8s で生成したマニフェストのデプロイ戦略について紹介しました。

運用上の課題に対し、以下のアプローチをとっています。

マニフェストの事前生成と書き出しの工夫 (FOLDER_PER_CHART_FILE_PER_RESOURCE) により、デプロイされるものを明確にし、差分を一目で確認できるようにしました。
2 つのリポジトリ構成 により、コードと生成物を明確に分離し、ブランチ戦略とコミットログを整理しました。
段階的なデプロイと自動検証 の CI/CD パイプラインにより、 dev → staging → prod と安全にマニフェストを昇格させるフローを構築しました。

cdk8s と GitOps を組み合わせることで、 Kubernetes マニフェストの管理とデプロイをより安全で効率的に行えるようになりました。

cdk8s の導入背景から実践パターン、デプロイ戦略まで、私たちの取り組みを紹介してきました。 TypeScript で Kubernetes マニフェストを管理するアプローチが、これから cdk8s を検討される方の参考になれば幸いです。

AI 機能をより素早く皆様のもとにお届けするため、新たなツールも活用しながら、 AI 機能の開発・運用をスケールさせていく試みを続けています！

We are hiring !!

kintone の AI 機能を支える基盤を、一緒に作りませんか？

この記事で紹介した cdk8s による Kubernetes マニフェスト管理も、私たちの取り組みの一つです。独自の AWS 基盤、 EKS クラスタ、 TypeScript で記述されるインフラコード――技術選定から設計、実装まで、チームで議論しながら進めています。そして構築した基盤を通じて、 kintone の AI 機能でユーザーに最高の価値を届けることに挑戦し続けています。

こんなことに挑戦できます: