1 post tagged with "KCL"

KCL 新版本功能解读系列 - Go SDK 功能速览！

2023年4月27日 · 阅读需要 1 分钟

KCL Team

KCL 是什么？

KCL 是一个开源的基于约束的记录及函数语言，期望通过成熟的编程语言技术和实践来改进对大量繁杂配置和策略的编写，致力于构建围绕配置的更好的模块化、扩展性和稳定性，更简单的逻辑编写，以及更快的自动化集成和良好的生态延展性。

`KCL Go SDK` 是什么？

kclvm 是一个 KCL 语言的运行时库，它提供了一个与 KCL 编译器交互的编程接口。它是一个客户端库，可用于对 KCL源代码执行各种操作，例如执行、格式化等。KCL Go SDK是 kclvm 的 Go 语言包装，提供了 Go 语言的 SDK，方便了在云原生环境下 KCL 语言的集成。

目前，KCL Go SDK 客户端构建在 kclvm json2 rpc API 之上，这意味着它使用和其他语言的 kclvm 客户端使用的相同 API 与 KCL 源代码交互，这与其他语言的 KCL SDK 工作方式类似，但提供了更加友好的 Go 语言风格的包装。

新版本 `KCL Go SDK` 解决了什么问题？

KCL 作为一门配置型语言，和云原生领域有着极其紧密的联系，而另一方面，Go 语言已经成为了云原生领域通用编程语言的事实标准。在这样的背景下，开发 KCL 的 Go SDK 来完成 KCL 编译器与 Go 语言的直接交互就有了必要，这也是KCL Go SDK诞生的原因。

最初版本的 KCL 编译器及运行时使用 python 编写，由于 python 语言本身的性能问题和其动态语言的特性，初版 KCL 语言的运行速度和安全性都有很大提升空间。出于安全与效率问题的考虑，后续版本 KCL 编译器又使用了 rust 语言编写，因此新版本的KCL Go SDK基于 Rust 实现的 KCL 核心进行包装，去除了 python 依赖，简化了安装，优化了使用体验。

新版本KCL Go SDK可以视为一个纯 Go 包使用，无需任何外置依赖，可以通过一键go install即可完成安装使用。

Go 代码如何集成 KCL

以上一节的 hello.k 为例，构建以下的 main.go 代码：

package main

import (
    "fmt"

    kcl "kcl-lang.io/kcl-go"
)

func main() {
    yaml := kcl.MustRun("kubernetes.k", kcl.WithCode(code)).GetRawYamlResult()
    fmt.Println(yaml)
}

const code = `
apiVersion = "apps/v1"
kind = "Deployment"
metadata = {
    name = "nginx"
    labels.app = "nginx"
}
spec = {
    replicas = 3
    selector.matchLabels = metadata.labels
    template.metadata.labels = metadata.labels
    template.spec.containers = [
        {
            name = metadata.name
            image = "${metadata.name}:1.14.2"
            ports = [{ containerPort = 80 }]
        }
    ]
}
`

kcl.MustRun("kubernetes.k", kcl.WithCode(code)).GetRawYamlResult()运行对应的kcl源文件
fmt.Println(yaml)打印运行结果

总结

通过这一次的 KCL Go SDK 的版本变更，我们去除了 python 依赖并切换至性能更加优秀的 rust 运行时。文章分别简单展示了如何使用 kcl-go 命令行工具执行 KCL 源代码, 以及如何将 KCL 集成至您的 Go 程序之中。

当然除了简单的编译并运行 KCL 源码之外，KCL Go SDK 还提供了丰富的功能以方便用户更好地在 Go 中集成 KCL ，包括：

KCL 静态错误分析（lint与格式化）
KCL 依赖分析、
Go 结构体和 KCL Schema 互相转换等等

其他资源

感谢所有 KCL 用户和社区小伙伴在此次版本更新过程中提出的宝贵反馈与建议。受限于文章篇幅，后续我们会撰写更多 KCL v0.4.6 新版本功能解读系列文章，敬请期待!

更多其他资源请参考：

欢迎加入我们的社区进行交流 👏👏👏：https://github.com/kcl-lang/community 👏👏👏

KCL v0.4.6 发布日志

2023年4月14日 · 阅读需要 1 分钟

KCL Team

简介

KCL 团队很高兴地宣布 KCL v0.4.6 新版本现在已经可用！本次发布为大家带来了三方面的重点更新：语言、工具链、社区集成 & 扩展支持。

使用 IDE 插件提升 KCL 代码编写体验和效率
Helm/Kustomize/KPT 云原生社区工具集成
完善 KCL 多语言 SDK，方便应用程序集成

进一步您可以在 KCL v0.4.6 发布页面或者 KCL 官方网站获得下载安装指南和详细发布信息。

本文重点介绍 KCL v0.4.6 版本的更新内容以及 KCL 社区的近期动态。

语言更新

内置函数更新

KCL 字符串新增 removeprefix 和 removesuffix 成员函数用于去除字符串的前缀和后缀子字符串

data1 = "prefix-string".removeprefix("prefix-") # "string"
data2 = "string-suffix".removesuffix("-suffix") # "string"

更多使用方式详见

编译器提示信息改进

在之前的 KCL 版本中，运行一次 KCL 命令行工具只会显示一个错误信息与警告，在 KCL v0.4.6 版本中，支持了一次编译显示多个错误与警告的能力并改善了错误提示信息，用于提升 KCL 代码错误排查效率，比如对于如下 KCL 代码 (main.k)

metadata = {
    labels = {key = "kcl
}

执行如下 KCL 命令行，可以看到会同时提示字符串编写错误和花括号未正确匹配错误的语法错误信息

$ kcl main.k
error[E1001]: InvalidSyntax
 --> main.k:2:21
  |
2 |     labels = {key = "kcl
  |                     ^ unterminated string
  |

error[E1001]: InvalidSyntax
 --> main.k:2:24
  |
2 |     labels = {key = "kcl
  |                        ^ expected "}"
  |

顶级 schema 语句合并运算符

在之前的 KCL 版本中，在编写如下 KCL 代码时，会将两个 schema 配置进行合并后输出，在 KCL v0.4.6 版本中，要求显式使用属性合并运算符而不是属性覆盖运算符

更新前

schema Config:
    id?: int
    value?: str

config = Config {
    id = 1
}
config = Config {
    value = "value"
}

更新后

schema Config:
    id?: int
    value?: str

# Use the union operator `:` instead of the override operator
config: Config {
    id = 1
}
# Use the union operator `:` instead of the override operator
config: Config {
    value = "value"
}

路径选择器参数简化

我们使用 path selector CLI 参数 (-S) 不必再填入包路径，并且可以直接筛选内部变量

对于如下的 KCL 代码 (main.k):

schema Person:
    name: str
    age: int

person = Person {
    name = "Alice"
    age = 18
}

我们可以执行如下命令

$ kcl main.k -S person
name: Alice
age: 18

错误修复

单行条件配置块语法解析错误

在之前的 KCL 版本中，在编写如下 KCL 代码时会出现非预期的语法错误，在 KCL v0.4.6 版本中，我们修复了此类类似的问题

env = "prod"
config = {if env == "prod": labels = {"kubernetes.io/env" = env}}

Schema 必选属性检查

在之前的 KCL 版本中，在编写如下 KCL 代码时，没有按预期提示 versions 属性没有赋值的错误，在 KCL v0.4.6 版本中，我们修复了此类类似的问题

schema App:
    data?: [int]
    version: Version

schema Version:
    versions: [str]

app = App {
    version = Version {}
}

工具链更新

KCL VS Code 插件

在此次更新中，我们发布了全新的 KCL VS Code 插件和使用 Rust 语言重写的语言服务服务器，相比于之前 KCL 版本性能约提升 20 倍，并支持了 KCL 错误警告在 IDE 中实时显示，以及 KCL 代码补全等新功能。

错误与告警实时显示

Diagnostics

跳转

Goto Definition

补全

Completion

悬停

Hover

更多 KCL VS Code 插件安装方式及详细更新内容详见

包管理工具

在 KCL v0.4.6 新版本中，我们提供了全新的 KCL 包管理工具 alpha 版本，用户可以通过几个命令即可获得社区中已经编写好的 KCL 模型。比如可以通过包管理工具一键导入 KCL Kubernetes 模型并使用

kpm init kubernetes_demo && kpm add -git https://github.com/awesome-kusion/konfig.git -tag v0.0.1

编写 KCL 代码 (main.k)

import konfig.base.pkg.kusion_kubernetes.api.apps.v1 as apps

apps.Deployment {
    metadata.name = "nginx-deployment"
    spec = {
        replicas = 3
        selector.matchLabels.app = "nginx"
        template.metadata.labels = selector.matchLabels
        template.spec.containers = [
            {
                name = selector.matchLabels.app
                image = "nginx:1.14.2"
                ports = [
                    {containerPort = 80}
                ]
            }
        ]
    }
}

执行如下 KCL 命令即可获得一个 Nginx Deployment YAML 输出

$ kpm run
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - image: "nginx:1.14.2"
          name: nginx
          ports:
            - containerPort: 80

更多 Konfig 模型库的内容和使用方式详见

社区集成 & 扩展更新

Kubernetes 配置管理工具扩展支持

在 KCL v0.4.6 中，我们以统一的编程界面方式为 Kubernetes 社区的 Helm, Kustomize, KPT 等配置管理工具提供了插件支持，编写几行 KCL 代码即可无侵入地完成对存量 Kustomize YAML，Helm Charts 的编辑和校验，比如编写少量 KCL 代码修改资源标签/注解, 注入 sidecar 容器配置，使用 KCL schema 校验资源等。

下面以 Kustomize 工具对 KCL 的集成为例进行详细说明。使用 Kustomize KCL 插件无需安装任何与 KCL 相关的二进制，仅需您本地安装有 Kustomize 工具即可。

首先执行如下命令获取一个 Kustomize YAML 配置示例:

git clone https://github.com/kcl-lang/kustomize-kcl.git &&cd ./kustomize-kcl/examples/set-annotation/

然后执行如下命令使用 KCL 代码仅为所有的 Deployment 资源添加一个 managed-by=kustomize-kcl 注解

sudo kustomize fn run ./local-resource/ --as-current-user --dry-run

可以得到如下 YAML 输出:

apiVersion: v1
kind: Service
metadata:
  name: test
  annotations:
    config.kubernetes.io/path: example-use.yaml
    internal.config.kubernetes.io/path: example-use.yaml
spec:
  selector:
    app: MyApp
  ports:
    - protocol: TCP
      port: 80
      targetPort: 9376
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
  annotations:
    config.kubernetes.io/path: example-use.yaml
    internal.config.kubernetes.io/path: example-use.yaml
    # This annotation is added through the kcl code.
    managed-by: kustomize-kcl
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
            - containerPort: 80

在上述 YAML 配置中，我们仅编写了一行 KCL 代码就完成为 Deployment 资源添加一个 managed-by=kustomize-kcl 注解

[resource | {if resource.kind == "Deployment": metadata.annotations: {"managed-by" = "kcl"}} for resource in option("resource_list").item]

此外我们为 Kustomize/Helm/KPT 三个工具均提供了常用的容器、服务配置修改校验 KCL 模型，并且会持续完善，欢迎社区小伙伴一起参与共建。

更多 Kustomize KCL 插件详细内容以及用例详见
更多 Helm KCL 插件详细内容以及用例详见
更多 KPT KCL 插件详细内容以及用例详见

多语言 SDK

在此次更新中，我们发布了全新的 KCL Go SDK 将 KCL 集成到您的 Go 应用程序中，并提供丰富的 API 与 KCL 进行交互。您可以在这里查询详细的 API 文档。此外我们还更新了如下特性和错误修复：

感谢 @jakezhu9 修复了 kcl-go 未预期的 KCL 格式化 API 在 CI Pipeline 中单元测试错误
感谢 @Ekko 贡献 Go struct 和 KCL schema 双向转换支持，详见:
- Go struct -> KCL schema
- KCL schema -> Go struct
KCL schema 到 protobuf message 的转换支持，详见
KCL 新增获取 schema 类型和实例 API，详见

其他更新与错误修复

KCL python plugin 功能默认不开启，如需开启可参考 KCL Plugin 文档
KCL playground 支持代码分享能力，您可以通过访问 KCL 官网并点击 Playground 按钮进行体验
更多更新与错误修复，详见

文档更新

KCL 网站新增 KCL v0.4.6 文档内容并支持版本化语义选项，目前支持 v0.4.3, v0.4.4, v0.4.5 和 v0.4.6 版本选择。同时欢迎社区同学进行文档共建。

下一步计划

预计 2023 年年中，我们将发布 KCL v0.5.0 版本，预期重点演进包括：

更多针对场景问题的 KCL 语言编写便利性改进，用户界面持续优化与体验提升，用户支持和痛点解决
更多 IDE 插件、包管理工具、Helm/Kustomize/KPT 场景集成、功能支持和用户体验提升
针对云原生场景提供更多开箱即用的 KCL 模型支持，主要包含容器、服务、计算、存储和网络等
支持 KCL Schema 直接生成 Kubernetes CRD
支持 kubectl 和 helmfile KCL plugin，通过 KCL 代码直接生成、编辑和校验 Kubernetes 原生资源
支持在 Kubernetes 运行时通过 Admission Controller 运行 KCL 代码对 YAML 进行编辑和校验
更多非 Kubernetes 场景支持，如通过 KCL Schema 对 AI 模型进行数据清理和数据库 Schema 集成支持

更多详情请参考 KCL v0.5.0 Milestone

如果您有更多的想法和需求，欢迎在 KCL Github 仓库发起 Issues，也欢迎加入我们的社区进行交流 🙌 🙌 🙌

常见问题及解答

详见 KCL 常见问题

其他资源

更多其他资源请参考：

欢迎加入我们的社区进行交流 👏👏👏：https://github.com/kcl-lang/community

KCL 是什么？​

KCL Go SDK 是什么？​

新版本 KCL Go SDK 解决了什么问题？​

Go 代码如何集成 KCL​

总结​

其他资源​

简介​

语言更新​

内置函数更新​

编译器提示信息改进​

顶级 schema 语句合并运算符​

路径选择器参数简化​

错误修复​

单行条件配置块语法解析错误​

Schema 必选属性检查​

工具链更新​

KCL VS Code 插件​

包管理工具​

社区集成 & 扩展更新​

Kubernetes 配置管理工具扩展支持​

多语言 SDK​

其他更新与错误修复​

文档更新​

下一步计划​

常见问题及解答​

其他资源​

KCL 是什么？

`KCL Go SDK` 是什么？

新版本 `KCL Go SDK` 解决了什么问题？

Go 代码如何集成 KCL

总结

其他资源

简介

语言更新

内置函数更新

编译器提示信息改进

顶级 schema 语句合并运算符

路径选择器参数简化

错误修复

单行条件配置块语法解析错误

Schema 必选属性检查

工具链更新

KCL VS Code 插件

包管理工具

社区集成 & 扩展更新

Kubernetes 配置管理工具扩展支持

多语言 SDK

其他更新与错误修复

文档更新

下一步计划

常见问题及解答

其他资源