cue-kind-definition

CUE 种类定义

常见工作流

添加新种类

# 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 会打印出错的文件、行号以及未通过的约束
• 常见原因：缺少必填字段、类型不匹配（例如，将 int 赋给 string 字段）、版本文件之间的引用无法解析
• 修复 .cue 源文件，然后重新运行 grafana-app-sdk generate。切勿编辑 pkg/generated/ 下的文件——这些文件在每次运行时都会被覆盖。

为现有种类添加新版本

# 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）。

种类文件结构

CLI 会在 kinds/ 下生成扁平目录结构：

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

对于多版本种类，其他版本文件会放在同一目录下（如 mykind_v1.cue）。对于规模很大的种类集合（10 种以上），可考虑按种类划分子目录的布局——完整的种类结构参考请见 references/kind-layout.md。

CUE 种类结构

每个种类分为三个层：

1. 通用种类元数据

// 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 }
    }
}

代码生成配置

控制每个种类、每个版本要生成的内容：

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

对于仅包含前端的应用，禁用 go 可避免生成未使用的 Go 代码。对于仅包含后端的资源，禁用 ts 可减小包体积。省略时，两者默认均为 true。

参考资料

• references/kind-layout.md — 通用元数据字段完整参考、应用清单字段，以及按种类划分子目录的布局
• references/schema-types.md — CUE 架构字段类型（基本类型、约束、正则表达式、枚举、映射、列表），以及以 # 为前缀的命名类型定义
• references/custom-routes.md — 种类级和版本级自定义路由，以及在 app.go 中注册处理程序

外部资源

• grafana-app-sdk GitHub
• CUE 语言参考
• 种类布局示例