cue-kind-definition

CUE Kind 定義

共通ワークフロー

新しい kind の追加

# 1. Scaffold the kind files
grafana-app-sdk project kind add MyKind --overwrite
# Produces kinds/mykind.cue + kinds/mykind_v1alpha1.cue + updates kinds/manifest.cue.

# 2. Edit the generated .cue files — fill in schema.spec / schema.status fields

# 3. Generate types and clients
grafana-app-sdk generate

# 4. Verify the generated artifacts exist
ls pkg/generated/    # should contain new types for MyKind

generate が CUE エラーで失敗した場合：

• エラーを確認します。CUE は問題のあるファイルと行、失敗した制約を出力します
• よくある原因：必須フィールドの不足、型の不一致（例：string フィールドに int を割り当てている）、バージョンファイル間の未解決の参照
• .cue ソースを修正し、grafana-app-sdk generate を再実行します。pkg/generated/ 以下のファイルは編集しないでください。実行するたびに上書きされます。

既存の kind への新しいバージョンの追加

# 1. Copy the existing version file
cp kinds/mykind_v1alpha1.cue kinds/mykind_v1.cue

# 2. Edit kinds/mykind_v1.cue — rename the top-level object (e.g. myKindv1) and adjust the schema

# 3. Register the new version in kinds/manifest.cue
#    Add a versions["v1"]: { schema: myKindv1 } entry

# 4. Re-generate
grafana-app-sdk generate

# 5. Verify both versions were generated — per-version Go types live under pkg/generated/<group>/<version>/
ls pkg/generated/             # should list both version directories (e.g. v1alpha1/ v1/)
# Optionally inspect the CRD spec under definitions/ to confirm both versions appear in `spec.versions[]`

破壊的変更（フィールドの削除、型の変更、必須フィールドの追加）は新しいバージョンに含める必要があります。安定版（v1、v2）をその場で変更しないでください。

Kind ファイルの構成

CLI は kinds/ 以下にフラットな構成を生成します：

kinds/
├── manifest.cue           # App manifest + version list declarations
├── mykind.cue             # Common (cross-version) kind metadata
└── mykind_v1alpha1.cue    # v1alpha1 schema + codegen config

複数バージョンがある kind では、追加のバージョンファイルが同じ場所に配置されます（mykind_v1.cue など）。kind が非常に多い場合（10 個以上）は、kind ごとのサブディレクトリ構成を検討してください。kind の構成の詳細はreferences/kind-layout.mdを参照してください。

CUE Kind の構成

kind ごとに 3 つのレイヤーがあります：

1. 共通の kind メタデータ

// kinds/mykind.cue
package kinds

myKind: {
    kind: "MyKind"               // Required: PascalCase kind name
    // other cross-version fields (scope, pluralName, validation, mutation, conversion, …)
    // Full field reference in references/kind-layout.md.
}

2. バージョンごとのスキーマ

// kinds/mykind_v1alpha1.cue
package kinds

myKindv1alpha1: myKind & {
    schema: {
        spec: {                       // desired state — user-set
            title:       string
            description: string | *""
            count:       int & >=0
            enabled:     bool | *true
        }
        status: {                     // observed state — operator-set
            lastObservedGeneration: int | *0
            state:                  string | *""
            message:                string | *""
        }
    }
    codegen: {
        ts: { enabled: true }
        go: { enabled: true }
    }
}

3. アプリマニフェスト

// kinds/manifest.cue
package kinds

App: {
    appName: "my-app"
    versions: {
        "v1alpha1": { schema: myKindv1alpha1 }
    }
}

コード生成の設定

kind とバージョンごとに生成するものを制御します：

codegen: {
    ts: { enabled: true | false }   // TypeScript types
    go: { enabled: true | false }   // Go types + client
}

フロントエンド専用アプリで go を無効にすると、未使用の Go コードを避けられます。バックエンド専用のリソースで ts を無効にすると、バンドルサイズを削減できます。省略した場合、どちらもデフォルトで true になります。

参考資料

• references/kind-layout.md — 共通メタデータの全フィールド、アプリマニフェストのフィールド、kind ごとのサブディレクトリ構成
• references/schema-types.md — CUE スキーマのフィールド型（基本型、制約、正規表現、列挙型、マップ、リスト）と # で始まる名前付き型定義
• references/custom-routes.md — kind レベルおよびバージョンレベルのカスタムルートと、app.go でのハンドラー登録

外部リソース

• grafana-app-sdk GitHub
• CUE 言語リファレンス
• kind 構成の例