cdk8s を使ってみた！ - TypeScript で Kubernetes マニフェストを管理する - Cybozu Inside Out

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

こんにちは！

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

突然ですが、みなさんは Kubernetes のマニフェストをどのように生成・管理していますでしょうか?

ArgoCD で GitOps を実践されている方であれば、Kustomize や Helm、Jsonnet などのツールで管理されているかと思います。サイボウズでも、これらのツールを活用してマニフェストを生成していることが多いです。

これらのツールは非常に強力ですが、それぞれ独自の記法が採用されており、構文でつまづくことがあるという共通の課題があります。Helm は Go テンプレートの知識が必要で、Jsonnet も独自の記法を覚える必要があり、Kustomize も overlay の仕組みでつまづくケースがあります。そこで、 kintone 生成 AI チームでは、 cdk8s を導入することで、これらの課題を解決しました。

本記事では、 kintone 生成 AI チームが cdk8s を導入した背景と、実際に使ってみて感じたメリットを紹介します。 Kubernetes マニフェストを管理する上で、 TypeScript で管理するという選択肢もあります。これから cdk8s を使ってみたい方の参考になれば幸いです。

kintone 生成 AI チームでの課題
cdk8s とは
cdk8s を選んで良かったこと
cdk8s の基本的な使い方
- 基本概念
- 簡単なコード例
まとめ
We are hiring !!

kintone 生成 AI チームでの課題

さて、私たちのチームは、 AI という変化の激しい領域に対応するため、チーム独自で AWS 基盤を構築し、 kintone の AI 機能を提供しています。

「kintone AI でも Kubernetes はじめました」という記事で紹介した通り、 EKS を用いた Kubernetes 基盤を最近構築しました。

この基盤の立ち上げにあたり、マニフェストの生成・管理方法をどうするか、という課題に直面しました。候補となったツールを検討した際、いくつかの課題が見えてきました。

Kustomize は社内での利用実績はあるものの、私たちが求めるような柔軟性に欠けること、 Jsonnet も社内実績はありましたが、新たに学習するコストが高いことがネックとなりました。

一方、私たちのチームでは既に AWS の構成管理に CDK (Cloud Development Kit) を利用しており、TypeScript でインフラを記述することに慣れていました。そこで、TypeScript さえ知っていれば、新たな構文を覚えることなく Kubernetes マニフェストを操作できる cdk8s に着目しました。また、共通のスタックを定義して再利用できることで、開発効率を大幅に向上できると考え、 cdk8s を採用することにしました。

cdk8s とは

cdk8s は、 AWS CDK のように、 TypeScript や Python などの一般的なプログラミング言語で Kubernetes マニフェストを定義できるツールです。これにより、専用の構文を学習することなく、既存のプログラミング知識を活かしつつ、柔軟にマニフェストを生成できます。

元々は、 AWS によって開発されており、現在は Cloud Native Computing Foundation (CNCF) の Sandbox Project となっています。

cdk8s.io

cdk8s を選んで良かったこと

実際に cdk8s を使ってみて、いくつかの大きなメリットを実感しています。

TypeScript の恩恵を受けられる

最大のメリットは、やはり TypeScript でインフラを記述できることです。

例えば、 Deployment を定義する場合、以下のように TypeScript で書けます:

new Deployment(this, "my-app", {
    replicas: 3,
    containers: [
        {
            image: "nginx:latest",
            port: 80,
        },
    ],
});

YAML で書くと何十行にもなる Deployment の定義が、 TypeScript ならこれだけで済みます。そして、エディタの補完機能がフルに使えるため、どんなプロパティが設定できるか、すぐにわかります。

型安全性: エディタ上でリアルタイムに型チェックが行われ、設定ミスを事前に防げます
自動補完: IDE の補完機能がフルに使え、どんなプロパティが設定できるかすぐにわかります
リファクタリング: 変数名の一括変更や、関数の抽出など、プログラミング言語ならではのリファクタリングが可能です

再利用可能なコンポーネント化

Construct として共通パターンをまとめることで、マニフェストの記述がシンプルになり、開発速度が大幅に向上しました。

例えば、 Network Policy の設定は従来なら Egress と Ingress の 2 つのマニフェストを書く必要がありましたが、カスタム Construct を作ることで、数行のコードで設定できるようになりました。

今後は、 LangChain や Mastra などの AI フレームワークごとに共通のマニフェストパターンを Construct として定義し、新しい AI Agent のデプロイも簡単に行えるようにする予定です。

柔軟な設定管理

YAML ファイルでの設定管理と TypeScript コードを組み合わせることで、環境ごとの差異を柔軟に管理できます。共通の設定は common.yaml で一元管理し、環境固有の設定だけを各環境の YAML で上書きする、という運用方法を採用しています。

例えば、以下のような設定を考えてみましょう:

config/apps/some-app/common.yaml

somePodConfig:
  replicas: 1
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

config/apps/some-app/prod.yaml

somePodConfig:
  replicas: 3

この場合、 dev 環境や staging 環境では common.yaml の設定がそのまま使われ、 replicas は 1 となります。一方、 prod 環境では common.yaml の設定に prod.yaml の設定がマージされ、 replicas だけが 3 に上書きされます。リソース要求などの他の設定は common.yaml の値がそのまま使われるため、設定の重複を避けつつ、環境ごとの差分を明確に管理できます。

cdk8s の基本的な使い方

cdk8s では、いくつかの重要な概念を理解することで、すぐに使い始めることができます。

基本概念

Construct: Kubernetes リソースを表すビルディングブロック。 Deployment や Service などの K8s リソースを TypeScript のクラスとして扱います
Chart: 関連する複数の Construct をグループ化したもの。アプリケーション単位でまとめることが多いです
App: Chart のコンテナ。複数の Chart をまとめて、最終的に YAML マニフェストを生成します

簡単なコード例

例えば、簡単な Deployment を作成する場合、以下のように書けます:

import { App, Chart } from "cdk8s";
import { Deployment, Container } from "cdk8s-plus-33";

export class MyAppChart extends Chart {
    constructor(scope: App, id: string) {
        super(scope, id);

        new Deployment(this, "my-app", {
            replicas: 3,
            containers: [
                new Container({
                    image: "nginx:latest",
                    port: 80,
                }),
            ],
        });
    }
}

const app = new App();
new MyAppChart(app, "my-app");
app.synth();

このコードを実行すると、 Deployment の YAML マニフェストが自動生成されます。ここで使用している cdk8s-plus は Kubernetes リソースを高レベルで抽象化したライブラリで、生の YAML や低レベル API を直接扱うよりも簡潔にマニフェストを記述できます。

まとめ

本記事では、 kintone 生成 AI チームが cdk8s を導入した背景と、実際に使ってみて感じたメリットを紹介しました。

TypeScript で Kubernetes マニフェストを管理することで、型安全性、再利用性、柔軟な設定管理といった恩恵を受けられています。既に TypeScript を使っているチームであれば、学習コストも低く、すぐに導入できるのも大きな魅力です。

次回以降の記事では、より実践的な内容をお届けします:

core/apps によるコンポーネント管理の工夫
複数環境に対応した設定ファイルの管理方法
CRD を型安全に扱う方法
再利用可能な Construct の実装例
マニフェストのデプロイと差分管理の工夫

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

We are hiring !!

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

この記事で紹介した cdk8s のように、私たちのチームでは新しいツールも積極的に取り入れながら、最適な技術スタックを模索しています。 技術選定から設計、実装まで、チームで議論しながら進めています。そして構築した基盤を通じて、 kintone の AI 機能でユーザーに最高の価値を届けることに挑戦し続けています。

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