diff --git a/blog/2022-09-15-declarative-config-overview/index.md b/blog/2022-09-15-declarative-config-overview/index.md index 5a393a8b..edb8c365 100644 --- a/blog/2022-09-15-declarative-config-overview/index.md +++ b/blog/2022-09-15-declarative-config-overview/index.md @@ -70,12 +70,12 @@ The Templated KV has the capability of static configuration data and dynamic par Representative technologies of templated KV include: -- [Helm](https://helm.sh/): The package management tool of Kubernetesresources, which manages the configuration of Kubernetes resources through the configuration template. Fig. 3 shows a Helm Jekins Package ConfigMap configuration template. It can be seen that these templates are very short with simple logic. A series of resource configurations suitable forKubernetes basic components are installed through package management and additional configuration parameters. Compared with the simply templatedK-V, Helm provides template storage, reference and semantic version management capabilities. Compared with Kustomize, Helm is more suitable for managing external Charts but is not good at multi-environment and multi-tenant configuration management. +- [Helm](https://helm.sh/): The package management tool of Kubernetesresources, which manages the configuration of Kubernetes resources through the configuration template. Fig. 3 shows a Helm Jenkins Package ConfigMap configuration template. It can be seen that these templates are very short with simple logic. A series of resource configurations suitable forKubernetes basic components are installed through package management and additional configuration parameters. Compared with the simply templatedK-V, Helm provides template storage, reference and semantic version management capabilities. Compared with Kustomize, Helm is more suitable for managing external Charts but is not good at multi-environment and multi-tenant configuration management. - Other configuration templates: Java Velocity, Go Template and other text template engines are very suitable for HTML writing templates. However,when used in configuration scenarios, they are difficult for developers and tools to maintain and analyze. ![](/img/blog/2022-09-15-declarative-config-overview/03-helm.png) -Fig. 3: Helm Jekins Package ConfigMap configuration template. +Fig. 3: Helm Jenkins Package ConfigMap configuration template. #### 1.2.3 Programmable K-V diff --git a/blog/2023-07-14-kcl-0.5.0-release/index.md b/blog/2023-07-14-kcl-0.5.0-release/index.md new file mode 100644 index 00000000..6c238737 --- /dev/null +++ b/blog/2023-07-14-kcl-0.5.0-release/index.md @@ -0,0 +1,481 @@ +--- +slug: 2022-kcl-0.5.0-release-blog +title: KCL v0.5.0 Release Blog +authors: + name: KCL Team + title: KCL Team +tags: [Release Blog, KCL] +--- + + + +## Introduction + +The KCL team is pleased to announce that KCL v0.5.0 is now available! This release has brought three key updates to everyone: **Language**, **Tools**, and **Integrations**. + ++ *Use KCL language and IDE with more complete features and fewer errors to improve code writing experience and efficiency.* ++ *Use KPM, KCL OpenAPI, OCI Registry and other tools to directly use and share your cloud native domain models, reducing learning and hands-on costs.* ++ *Using community tools such as Github Action, ArgoCD, and Kubectl KCL plugins to integrate and extend support to improve automation efficiency.* + +You can visit the [KCL release page](https://github.com/kcl-lang/kcl/releases/tag/v0.5.0) or the [KCL website](https://kcl-lang.io/) to get KCL binary download link and more detailed release information. + +[KCL](https://github.com/kcl-lang/kcl) is an open-source, constraint-based record and functional language. KCL improves the writing of numerous complex configurations, such as cloud-native scenarios, through its mature programming language technology and practice. It is dedicated to building better modularity, scalability, and stability around configurations, simpler logic writing, faster automation, and great built-in or API-driven integrations. + +This blog will introduce the content of KCL v0.5.0 and recent developments in the KCL community to readers. + +## Language + +### Top-level Variable Output + +In previous versions of KCL, running the following KCL code will not output YAML. In KCL v0.5.0, we improved this and supported exporting top-level variables to YAML configuration to reduce additional KCL code and command-line parameters, such as for the following KCL code (main.k) + +```python +schema Nginx: + http: Http + +schema Http: + server: Server + +schema Server: + listen: int | str + location?: Location + +schema Location: + root: str + index: str + +Nginx { # Nginx will be output + http.server = { + listen = 80 + location = { + root = "/var/www/html" + index = "index.html" + } + } +} +``` + +In the new version, running KCL code can directly obtain the following output + +```yaml +$ kcl main.k +http: + server: + listen: 80 + location: + root: /var/www/html + index: index.html +``` + +See [here](https://github.com/kcl-lang/kcl/pull/556) for more. + +### Index Signature + +In previous versions of KCL, running the KCL command-line tool once only displayed one error message and warning. In KCL v0.5.0, it supported the ability to display multiple errors and warnings in one compilation and improved error information to improve the efficiency of KCL code error troubleshooting, such as for the following KCL code (main.k). + +```python +schema TeamSpec: + fullName: str + name = id + shortName: str = name + +schema TeamMap: + [n: str]: TeamSpec = TeamSpec { + name = n # n is the schema index signature key alias, we can use it directly + } + +teamMap = TeamMap { + a.fullName = "alpha" + b.fullName = "bravo" +} +``` + +In the new version, running KCL code can directly obtain the following output. + +```shell +$ kcl main.k +teamMap: + b: + fullName: bravo + name: b + shortName: b + a: + fullName: alpha + name: a + shortName: a +``` + +See [here](https://github.com/kcl-lang/kcl/pull/582) for more. + +### Runtime Backtrace Output + +In previous versions of KCL, when writing the following KCL code, the two schema configurations with the same name were merged and output. In KCL v0.5.0, it was required to explicitly use the attribute merge operator instead of the attribute overlay operator. + +```python +schema Fib: + n1 = n - 1 + n2 = n1 - 1 + n: int + value: int + + if n <= 1: + value = [][n] # There is a index overflow runtime error. + elif n == 2: + value = 1 + else: + value = Fib {n = n1}.value + Fib {n = n2}.value + +fib8 = Fib {n = 4}.value +``` + +After execution, we will receive the following error message + +```shell +$ kcl main.k -d +error[E3M38]: EvaluationError +EvaluationError + --> main.k:8 + | +8 | value = [][n] # There is a index overflow runtime error. + | list index out of range: 1 + | +note: backtrace: + 1: __main__.Fib + at main.k:8 + 2: __main__.Fib + at main.k:12 + 3: __main__.Fib + at main.k:12 + 4: main + at main.k:14 +``` + +See [here](https://github.com/kcl-lang/kcl/pull/528) for more. + +### Bugfix + +#### Type Error in Filter Expressions + +Before KCL v0.5.0, filter expressions returned incorrect types (should return the type of the iterator instead of the type of the iterated object). In KCL v0.5.0, we fixed similar issues. + +```python +schema Student: + name: str + grade: int + +students: [Student] = [ + {name = "Alice", grade = 85} + {name = "Bob", grade = 70} +] + +studentsGrade70: [Student] = filter s in students { + s.grade == 70 +} # Previously, we received a type mismatch error here. In KCL v0.5.0, we fixed similar issues. +``` + +See [here](https://github.com/kcl-lang/kcl/pull/546) for more. + +#### Lambda Closure Error + +In previous versions of KCL, for the following KCL code, there was an error where the `versions` attribute was not assigned as expected. In KCL v0.5.0, we fixed similar issues. + +```python +z = 1 +add = lambda x { lambda y { x + y + z} } # `x` is the closure of the inner lambda. +res = add(1)(1) # 3 +``` + +See [here](https://github.com/kcl-lang/kcl/pull/548) for more. + +#### String Literal Union Type Error Containing UTF-8 Characters + +In previous versions of KCL, using string literal union type that contains UTF-8 characters resulted in an unexpected type error. In KCL v0.5.0 version, we fixed similar issues like this. + +```python +msg: "无需容灾" | "标准型" | "流水型" = "流水型" +``` + +See [here](https://github.com/kcl-lang/kcl/pull/600) for more. + +## Tools & IDE + +### KCL OpenAPI Tool + +The kcl-openapi command-line tool supports conversion from OpenAPI Spec to KCL code. Installation can be obtained through `go install` or `curl`: + +```bash +# go install +go install kcl-lang.io/kcl-openapi@latest + +# curl install (MacOS & Linux) +curl -fsSL https://kcl-lang.io/script/install-kcl-openapi.sh | /bin/bash +``` + +#### Kubernetes KCL Package Conversion Optimization + +The v0.5.0 version optimizes the experience of using Kubernetes KCL packages: ++ Built-in Kubernetes package: KCL provides out of the box KCL packages for Kubernetes 1.14-1.27 versions, which can be obtained through the package management tool `kpm pull k8s:`. ++ If you need to convert other Kubernetes versions of the KCL model on your own, you can use the following preprocessing script to convert the `swagger.json` file downloaded from the Kubernetes repository into the KCL package. Change 1.27 of the following command to the desired Kubernetes version. + +```bash +version=1.27 +spec_path=swagger.json +script_path=main.py +wget https://raw.githubusercontent.com/kubernetes/kubernetes/release-${version}/api/openapi-spec/swagger.json -O swagger.json +wget https://raw.githubusercontent.com/kcl-lang/kcl-openapi/main/scripts/preprocess/main.py -O main.py +python3 ${script_path} ${spec_path} --omit-status --rename=io.k8s=k8s +kcl-openapi generate model -f processed-${spec_path} +``` + +The expected execution output of the script is the corresponding version of the KCL Kubernetes model, and the generated path is `/models/k8s`. + +```bash +$ tree models/k8s +models/k8s +├── api +│ ├── admissionregistration +│ │ ├── v1 +│ │ │ ├── match_condition.k +│ │ │ ├── mutating_webhook.k +│ │ │ ├── mutating_webhook_configuration.k +│ │ │ ├── mutating_webhook_configuration_list.k +│ │ │ ├── rule_with_operations.k +│ │ │ ├── service_reference.k +│ │ │ ├── validating_webhook.k +... +``` + +#### Bugfix + ++ Escape attribute names with the `-` character as `_` to comply with KCL v0.5.0 syntax, [see details](https://github.com/kcl-lang/kcl-openapi/pull/43) ++ Automatically recognize and set import as reference aliases to avoid reference conflicts, [see details](https://github.com/kcl-lang/kcl-openapi/pull/45) ++ Fix the issue of attribute description indentation in docstring, and automatically indent the internal line breaks of attribute descriptions. [See details](https://github.com/kcl-lang/kcl-openapi/pull/46) ++ Fix the generated reference path to be the full reference path based on the root directory of the package, [see details](https://github.com/kcl-lang/kcl-openapi/pull/51) + +### Package Management Tool + +In the new version of KCL v0.5.0, we have provided a new KCL package management tool, which allows users to access the KCL modules in the community with a few commands. + +#### Managing KCL Programs through the kpm Tool + +Before using kpm, it is necessary to ensure that you are currently working in a KCL package. You can use the command kpm init to create a standard KCL package. + +```shell +kpm init kubernetes_demo && cd kubernetes_demo && kpm add k8s +``` + +Write a KCL code to import the Kubernetes models (main.k). + +```python +import k8s.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} + ] + } + ] + } +} +``` + +By combining the `kpm run` and `kubectl` command lines, we can directly distribute resource configurations to the cluster. + +```bash +$ kpm run | kubectl apply -f - + +deployment.apps/nginx-deployment configured +``` + +#### OCI Registry + +The kpm tool supports pushing KCL packages through OCI Registry. The default OCI Registry currently provided by kpm is [https://github.com/orgs/kcl-lang/packages](https://github.com/orgs/kcl-lang/packages). + +You can browse the KCL package you need here. We currently provide the KCL package for k8s, which supports all versions of k8s from 1.14 to 1.27. Welcome to open [Issues](https://github.com/kcl-lang/kpm/issues) to co build KCL models. + +See [here](https://kcl-lang.io/docs/user_docs/guides/package-management/overview) for more information about the **kpm** tool. + +## Integrations + +### CI Integrations + +In the new version of KCL, we have provided an example scheme of **Github Actions as the CI integration**. We hope to implement the end-to-end application development process by using containers, Continuous Integration (CI) for configuration generation, and GitOps for Continuous Deployment (CD). The overall workflow is as follows: + ++ Develop application code and submit it to the GitHub repository to trigger CI (using Python Flask web application as an example). + +![app](/img/blog/2023-07-14-kcl-0.5.0-release/app.png) + ++ GitHub Actions generate container images from application code and push them to the `docker.io` container registry. + +![app-ci](/img/blog/2023-07-14-kcl-0.5.0-release/app-ci.png) + ++ GitHub Actions automatically synchronizes and updates the KCL manifest deployment file based on the version of the container image in the docker.io container registry. + +![auto-update](/img/blog/2023-07-14-kcl-0.5.0-release/auto-update.png) + +We can obtain the deployment manifest source code for compilation and verification, and the following YAML output will be obtained + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: flask_demo + labels: + app: flask_demo +spec: + replicas: 1 + selector: + matchLabels: + app: flask_demo + template: + metadata: + labels: + app: flask_demo + spec: + containers: + - name: flask_demo + image: "kcllang/flask_demo:6428cff4309afc8c1c40ad180bb9cfd82546be3e" + ports: + - protocol: TCP + containerPort: 5000 +--- +apiVersion: v1 +kind: Service +metadata: + name: flask_demo + labels: + app: flask_demo +spec: + type: NodePort + selector: + app: flask_demo + ports: + - port: 5000 + protocol: TCP + targetPort: 5000 +``` + +From the above configuration, it can be seen that the image of the resource is indeed automatically updated to the newly constructed image content. In addition, we can also use the Argo CD KCL plugin to automatically synchronize data from the Git repository and deploy the application to the Kubernetes cluster. + +For more details, please refer to [here](https://kcl-lang.io/docs/user_docs/guides/ci-integration/github-actions) + +### CD Integrations + +In addition, we also provide **ArgoCD as an example solution for CD integration**. Through Github Action CI integration and ArgoCD KCL plugin, we can complete end-to-end GitOps workflow, improve application configuration automatic change and deployment efficiency. The following is an overview and synchronization of Kubernetes configuration using ArgoCD application. By using ArgoCD's ability, when application code changes, it is automatically updated and deployed synchronously. + ++ **Application Overview** + +![argocd-app](/img/blog/2023-07-14-kcl-0.5.0-release/argocd-app.png) + ++ **Configuration Synchronization** + +![argocd-sync](/img/blog/2023-07-14-kcl-0.5.0-release/argocd-sync.png) + +For more details, please refer to [here](https://kcl-lang.io/docs/user_docs/guides/gitops/gitops-quick-start) + +### Kubernetes Configuration Management Tool Plugin + +In KCL v0.5.0, we provide KCL plugin support for configuration management tools such as Kubectl, Helm, Kustomize, and KPT in the Kubernetes community through a unified programming interface. By writing a few lines of configuration code, we can non-invasive edit and validate existing Kustomize YAML and Helm Charts, such as modifying resource labels/annotations, injecting sidecar containers, and validate resources using KCL schema, defining your own abstract models and share them, etc. + +Below is a detailed explanation of the integration of Kubectl tool with KCL as an example. You can click [here](https://github.com/kcl-lang/kubectl-kcl) to obtain the installation of Kubectl KCL plugin. + +First, execute the following command to obtain a configuration example + +```shell +git clone https://github.com/kcl-lang/kubectl-kcl.git && cd ./kubectl-kcl/examples/ +``` + +Then execute the following command to show the configuration + +```shell +$ cat krm-kcl-abstration.yaml +apiVersion: krm.kcl.dev/v1alpha1 +kind: KCLRun +metadata: + name: web-service-abtraction +spec: + params: + name: app + containers: + ngnix: + image: ngnix + ports: + - containerPort: 80 + service: + ports: + - port: 80 + labels: + name: app + source: oci://ghcr.io/kcl-lang/web-service +``` + +In the above configuration, we used a Kubernetes web service application abstract model that has been predetermined on OCI `oci://ghcr.io/kcl-lang/web-service` and configured the required configuration fields for the model through the `params` field. The original Kubernetes YAML output can be obtained and applied by executing the following command: + +```bash +$ kubectl kcl apply -f krm-kcl-abstration.yaml + +deployment.apps/app created +service/app created +``` + +More detailed introductions and use cases of Kubernetes configuration management tools can be found [here](https://github.com/kcl-lang/krm-kcl/tree/main/examples) + +At present, the integration of Kubernetes configuration management tools supported by KCL is still in its early stages. If you have more ideas and requirements, welcome to open issues to discuss. + +## Other Updates and Bug Fixes + +See [here](https://github.com/kcl-lang/kcl/compare/v0.4.6...v0.5.0) for more updates and bug fixes. + +## Documents + +The versioning semantic option is added to the [KCL website](https://kcl-lang.io/). Currently, v0.4.3, v0.4.4, v0.4.5, v0.4.6 and v0.5.0 versions are supported. + +## Community + ++ Thank @harri2012 for his first contribution to the KCL IDE plugin 🙌 ++ Thank @niconical for his contribution to the KCL command line basic code and CI/CD scripts 🙌 ++ Thank @Ekko for his contribution to the integration of KCL cloud native tools 🙌 ++ Congratulations to Junxing Zhu his successful selection into the GitLink Programming Summer Camp (GLCC) "Terraform/JsonSchema to KCL Schema" project 🎉 ++ Congratulations to Yiming Ren on her successful selection of the topic "IDE plug-in enhancement and language server integration" in the summer of open source 🎉 ++ We have relocated KCL 30+ repos as a whole to the new Github **kcl-lang** organization, keeping the project address in mind [https://github.com/kcl-lang](https://github.com/kcl-lang) ❤️ ++ KCL's joining CNCF Landscape is a small encouragement and recognition from the cloud native community. The next step is to strive to join CNCF Sadbox and make more contributions to the cloud native community 💪 + +## Next + +It is expected that in September 2023, we will release **KCL v0.6.0**. The expected key evolution includes: + ++ KCL language is further improved for convenience, the user interface is continuously optimized and experience is improved, user support and pain points are solved. ++ More IDE extensions, package management tools, Kubernetes scenario integration, feature support, and user experience improvement. ++ Provide more out-of-box KCL model support for cloud-native scenarios, mainly including containers, services, computing, storage, and networks. ++ More CI/CD integrations such as Jenkins, Gitlab CI, FluxCD, etc. ++ Support `helmfile` KCL plugins, directly generating, mutating, and validating Kubernetes resources through the KCL code. ++ Support for mutating and validating YAML by running KCL code through the admission controller at the Kubernetes runtime. + +For more details, please refer to [KCL 2023 Roadmap](https://kcl-lang.io/docs/community/release-policy/roadmap) and [KCL v0.6.0 Milestone](https://github.com/kcl-lang/kcl/milestone/6). + +If you have more ideas and needs, welcome to open [Issues](https://github.com/kcl-lang/kcl/issues) and join our community for communication as well 🙌 🙌 🙌 + +## FAQ + +For more information, see [KCL FAQ](https://kcl-lang.io/docs/user_docs/support/). + +## Additional Resources + +Thank all KCL users for their valuable feedback and suggestions during this version release. For more resources, please refer to: + ++ [KCL Website](https://kcl-lang.io/) ++ [Kusion Website](https://kusionstack.io/) ++ [KCL Repo](https://github.com/kcl-lang/kcl) ++ [Kusion Repo](https://github.com/KusionStack/kusion) ++ [Konfig Repo](https://github.com/KusionStack/konfig) + +See the [community](https://github.com/kcl-lang/community) for ways to join us. 👏👏👏 diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2022-09-15-declarative-config-overview/index.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2022-09-15-declarative-config-overview/index.md index 1aa1c9bd..ec9193c0 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-blog/2022-09-15-declarative-config-overview/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2022-09-15-declarative-config-overview/index.md @@ -73,11 +73,11 @@ tags: [KCL, Configuration] 模版化代表技术有: -- [Helm](https://helm.sh/)：Kubernetes 资源的包管理工具，通过配置模版管理 Kubernetes 资源配置。图 3 示出了一个 Helm Jekins Package ConfigMap 配置模版，可以看出这些模版本身都十分短小，可以书写简单的逻辑，适合 Kubernetes 基础组件固定的一系列资源配置通过包管理+额外的配置参数进行安装。相比于单纯的模版化的 KV，Helm 一定程度上提供了模版存储/引用和语义化版本管理的能力相比于 Kustomize 更适合管理外部 Charts, 但是在多环境、多租户的配置管理上不太擅长。 +- [Helm](https://helm.sh/)：Kubernetes 资源的包管理工具，通过配置模版管理 Kubernetes 资源配置。图 3 示出了一个 Helm Jenkins Package ConfigMap 配置模版，可以看出这些模版本身都十分短小，可以书写简单的逻辑，适合 Kubernetes 基础组件固定的一系列资源配置通过包管理+额外的配置参数进行安装。相比于单纯的模版化的 KV，Helm 一定程度上提供了模版存储/引用和语义化版本管理的能力相比于 Kustomize 更适合管理外部 Charts, 但是在多环境、多租户的配置管理上不太擅长。 ![](/img/blog/2022-09-15-declarative-config-overview/03-helm.png) -图 3 Helm Jekins Package ConfigMap 配置模版 +图 3 Helm Jenkins Package ConfigMap 配置模版 - 其他各种配置模版：Java Velocity, Go Template 等文本模板引擎非常适合 HTML 编写模板。但是在配置场景中使用时，存在所有配置字段即模版参数的风险，开发者和工具都难以维护和分析它们。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-07-14-kcl-0.5.0-release/index.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-07-14-kcl-0.5.0-release/index.md new file mode 100644 index 00000000..b10f4e67 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-07-14-kcl-0.5.0-release/index.md @@ -0,0 +1,485 @@ +--- +slug: 2022-kcl-0.5.0-release-blog +title: KCL v0.5.0 发布日志 +authors: + name: KCL Team + title: KCL Team +tags: [Release Blog, KCL] +--- + + + +## 简介 + +KCL 团队很高兴地宣布 KCL v0.5.0 新版本现在已经可用！本次发布为大家带来了三方面的重点更新：**语言**、**工具链**、**社区集成 & 扩展支持**。 + ++ *使用功能更完善错误更少的 KCL 语言和 IDE 提升代码编写体验和效率* ++ *使用 KPM, KCL OpenAPI 和 OCI Registry 等工具直接使用和共享您的云原生领域模型，降低学习和上手成本* ++ *使用 Github Action, ArgoCD 和 Kubectl KCL 插件等社区工具集成和扩展支持提升自动化效率* + +进一步您可以在 [KCL v0.5.0 发布页面](https://github.com/kcl-lang/kcl/releases/tag/v0.5.0) 或者 [KCL 官方网站](https://kcl-lang.io) 获得下载安装指南和详细发布信息。 + +[KCL](https://github.com/kcl-lang/kcl) 是一个开源的基于约束的记录及函数语言并通过成熟的编程语言技术和实践来改进对大量繁杂配置比如云原生 Kubernetes 配置场景的编写，致力于构建围绕配置的更好的模块化、扩展性和稳定性，更简单的逻辑编写，以及更简单的自动化和生态工具集成。 + +本文重点介绍 KCL v0.5.0 版本的更新内容以及 KCL 社区的近期动态。 + +## 语言更新 + +### 顶级变量输出 + +在之前的 KCL 版本中，运行如下 KCL 代码不会得到 YAML 输出，在 KCL v0.5.0 版本中，我们对此进行了改进并支持了顶级变量导出为 YAML 配置，用于减少额外的 KCL 代码书写和命令行参数，比如对于如下 KCL 代码 (main.k) + +```python +schema Nginx: + http: Http + +schema Http: + server: Server + +schema Server: + listen: int | str + location?: Location + +schema Location: + root: str + index: str + +Nginx { # 这里的 Nginx 实例会直接输出为 YAML + http.server = { + listen = 80 + location = { + root = "/var/www/html" + index = "index.html" + } + } +} +``` + +在新版本中，运行 KCL 代码可以直接获得如下输出 + +```yaml +$ kcl main.k +http: + server: + listen: 80 + location: + root: /var/www/html + index: index.html +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/556) + +### 索引签名更新 + +在之前的 KCL 版本中，尚未支持在 Schema 索引签名中直接引用，在 KCL v0.5.0 版本中，我们对此进行了改进并支持了顶级变量导出为 YAML 配置，用于减少额外的 KCL 样板配置代码书写，比如对于如下 KCL 代码 (main.k) + +```python +schema TeamSpec: + fullName: str + name = id + shortName: str = name + +schema TeamMap: + [n: str]: TeamSpec = TeamSpec { + name = n # n 作为 Schema 索引签名别名，可以直接使用 + } + +teamMap = TeamMap { + a.fullName = "alpha" + b.fullName = "bravo" +} +``` + +在新版本中，运行 KCL 代码可以获得如下输出 + +```yaml +$ kcl main.k +teamMap: + b: + fullName: bravo + name: b + shortName: b + a: + fullName: alpha + name: a + shortName: a +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/582) + +### KCL 支持运行时错误 Backtrace 打印 + +在新版本中，我们支持当 KCL 代码运行发生报错时输出 Backtrace 的特性，用于提升 KCL 代码错误排查效率，比如对于如下代码 (main.k) + +```python +schema Fib: + n1 = n - 1 + n2 = n1 - 1 + n: int + value: int + + if n <= 1: + value = [][n] # 这里有索引溢出的运行时错误 + elif n == 2: + value = 1 + else: + value = Fib {n = n1}.value + Fib {n = n2}.value + +fib8 = Fib {n = 4}.value +``` + +执行后会获得如下报错 + +```shell +$ kcl main.k -d +error[E3M38]: EvaluationError +EvaluationError + --> main.k:8 + | +8 | value = [][n] # 这里有索引溢出的运行时错误 + | list index out of range: 1 + | +note: backtrace: + 1: __main__.Fib + at main.k:8 + 2: __main__.Fib + at main.k:12 + 3: __main__.Fib + at main.k:12 + 4: main + at main.k:14 +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/528) + +### 错误修复 + +#### filter 表达式返回值类型错误修复 + +在之前的 KCL 版本中，filter 表达式会返回错误的类型（应该返回被迭代对象的类型，而不是返回迭代对象的类型），在 KCL v0.5.0 版本中，我们修复了此类类似的问题 + +```python +schema Student: + name: str + grade: int + +students: [Student] = [ + {name = "Alice", grade = 85} + {name = "Bob", grade = 70} +] + +studentsGrade70: [Student] = filter s in students { + s.grade == 70 +} # 这里之前得到一个类型错误，版本更新后修复了此类问题 +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/546) + +#### lambda 函数闭包捕获 + +在之前的 KCL 版本中，在编写如下 KCL 代码时，会错误的捕获闭包变量的值。在 KCL v0.5.0 版本中，我们修复了此类类似的问题 + +```python +z = 1 +add = lambda x { lambda y { x + y + z} } # x 是内层 lambda 函数的闭包变量 +res = add(1)(1) # 3 +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/548) + +#### 包含 UTF-8 字符的字符串联合类型检查错误修复 + +在之前的 KCL 版本中，在编写如下包含 UTF-8 字符的字符串联合类型 KCL 代码时，会获得一个非预期的类型错误。在 KCL v0.5.0 版本中，我们修复了此类类似的问题 + +```python +msg: "无需容灾" | "标准型" | "流水型" = "流水型" +``` + +更多信息[详见](https://github.com/kcl-lang/kcl/pull/600) + +## IDE & 工具链更新 + +### KCL OpenAPI 工具 + +kcl-openapi 命令行工具支持由 OpenAPI Spec 到 KCL 代码的转换。可通过 go install 或 curl 获得安装： + +```bash +# go install +go install kcl-lang.io/kcl-openapi@latest + +# curl install (MacOS & Linux) +curl -fsSL https://kcl-lang.io/script/install-kcl-openapi.sh | /bin/bash +``` + +#### Kubernetes KCL 包转换优化 + +v0.5.0 版本优化了使用 Kubernetes KCL 包的体验： + ++ 免转换获得：KCL 提供了开箱即用的 Kubernetes 1.14-1.27 各个版本的 KCL 包，通过包管理工具 `kpm add k8s:` 即可获得 ++ 如需自行转换其他 Kubernetes 版本的 KCL 模型，可通过如下的预处理脚本一键从 Kubernetes 仓库下载的 swagger.json 文件转换为 KCL 包，将如下命令的 1.27 改为需要的 Kubernetes 版本即可 + +```bash +version=1.27 +spec_path=swagger.json +script_path=main.py +wget https://raw.githubusercontent.com/kubernetes/kubernetes/release-${version}/api/openapi-spec/swagger.json -O swagger.json +wget https://raw.githubusercontent.com/kcl-lang/kcl-openapi/main/scripts/preprocess/main.py -O main.py +python3 ${script_path} ${spec_path} --omit-status --rename=io.k8s=k8s +kcl-openapi generate model -f processed-${spec_path} +``` + +脚本预期的执行输出为对应版本的 KCL Kubernetes 模型，生成的路径为 `<工作空间路径>/models/k8s` + +```bash +$ tree models/k8s +models/k8s +├── api +│ ├── admissionregistration +│ │ ├── v1 +│ │ │ ├── match_condition.k +│ │ │ ├── mutating_webhook.k +│ │ │ ├── mutating_webhook_configuration.k +│ │ │ ├── mutating_webhook_configuration_list.k +│ │ │ ├── rule_with_operations.k +│ │ │ ├── service_reference.k +│ │ │ ├── validating_webhook.k +... +``` + +#### 错误修复 + ++ 将带有-符号的属性名称转义为_符号，以符合 KCL v0.5.0 语法，[详见](https://github.com/kcl-lang/kcl-openapi/pull/43) ++ 自动识别并设置 import as 引用别名，避免引用冲突，[详见](https://github.com/kcl-lang/kcl-openapi/pull/45) ++ 修复 docstring 中属性描述缩进问题，对属性描述内部换行进行自动缩进，[详见](https://github.com/kcl-lang/kcl-openapi/pull/46) ++ 修复生成的引用路径为基于包的根目录的全引用路径，[详见](https://github.com/kcl-lang/kcl-openapi/pull/51) + +### 包管理工具 + +在 KCL v0.5.0 新版本中，我们提供了全新的 KCL 包管理工具，用户可以通过几个命令即可获得社区中已经编写好的 KCL 模型。 + +#### 通过 kpm 命令行管理 KCL 程序 + +在使用 kpm 之前，需要确保您当前在一个 KCL 包中工作，您可以使用命令 kpm init 创建一个标准的 KCL 程序包。 + +```bash +kpm init kubernetes_demo && cd kubernetes_demo && kpm add k8s +``` + +然后，使用 k8s 包中的内容编写您的 KCL 代码（main.k）。 + +```python +# 导入 k8s 包中的内容 +import k8s.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} + ] + } + ] + } +} +``` + +通过 `kpm run` 和 `kubectl` 命令行结合使用，我们可以直接将资源配置下发到集群 + +```bash +$ kpm run | kubectl apply -f - + +deployment.apps/nginx-deployment configured +``` + +#### OCI Registry 支持 + +kpm 支持通过 OCI Registry 保存 KCL 的程序包，kpm 目前提供的默认的 OCI Registry 为：[https://github.com/orgs/KusionStack/packages](https://github.com/orgs/KusionStack/packages) + +您可以在这里浏览您需要的 KCL 包，我们目前提供了 k8s 的 KCL 程序包，支持 k8s 1.14 到 1.27 的全部版本。欢迎提 [Issues](https://github.com/kcl-lang/kpm/issues) 共建 KCL 模型 + +更多关于 kpm 包管理工具的内容[详见](https://kcl-lang.io/docs/user_docs/guides/package-management/quick-start) + +## 社区集成 & 扩展更新 + +### CI 集成 + +在此次更新中我们提供了 **Github Actions 作为 CI 集成**的示例方案，希望通过使用容器、用于生成配置的持续集成 (CI) 和用于持续部署 (CD) 的 GitOps 来实现端到端应用程序开发流程。整体工作流程如下： + ++ 应用代码开发并提交到提交到 GitHub 存储库触发 CI (这里使用 Python Flask Web 应用作为示例) + +![app](/img/blog/2023-07-14-kcl-0.5.0-release/app.png) + ++ GitHub Actions 从应用代码生成容器镜像，并将容器镜像推送到 docker.io 容器注册表 + +![app-ci](/img/blog/2023-07-14-kcl-0.5.0-release/app-ci.png) + ++ GitHub Actions 根据 docker.io 容器注册表中容器镜像的版本号并自动同步更新 KCL 清单部署文件 + +![auto-update](/img/blog/2023-07-14-kcl-0.5.0-release/auto-update.png) + +我们可以获得部署清单源码进行编译验证会得到如下 YAML 输出 + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: flask_demo + labels: + app: flask_demo +spec: + replicas: 1 + selector: + matchLabels: + app: flask_demo + template: + metadata: + labels: + app: flask_demo + spec: + containers: + - name: flask_demo + image: "kcllang/flask_demo:6428cff4309afc8c1c40ad180bb9cfd82546be3e" + ports: + - protocol: TCP + containerPort: 5000 +--- +apiVersion: v1 +kind: Service +metadata: + name: flask_demo + labels: + app: flask_demo +spec: + type: NodePort + selector: + app: flask_demo + ports: + - port: 5000 + protocol: TCP + targetPort: 5000 +``` + +从上述配置可以看出资源的镜像确实自动更新为了新构建的镜像内容 。此外，我们还可以使用 Argo CD KCL 插件自动从 Git 存储库同步或从中拉取数据并将应用部署到 Kubernetes 集群 + +更多详情请参考[这里](https://kcl-lang.io/docs/user_docs/guides/ci-integration/github-actions) + +### CD 集成 + +此外我们还提供了 **ArgoCD 作为 CD 集成**的示例方案，通过 Github Action CI 集成和 ArgoCD KCL 插件，我们可以完成端到端的 GitOps 工作流，提升应用配置自动变更和部署效率。如下示出了使用 ArgoCD 应用 Kubernetes 配置的概览和同步情况，通过使用 ArgoCD 的能力，当业务代码发生变化时，自动同步更新并部署。 + ++ **应用概览** + +![argocd-app](/img/blog/2023-07-14-kcl-0.5.0-release/argocd-app.png) + ++ **配置同步** + +![argocd-sync](/img/blog/2023-07-14-kcl-0.5.0-release/argocd-sync.png) + +更多插件安装和使用方式请参考[这里](https://kcl-lang.io/docs/user_docs/guides/gitops/gitops-quick-start) + +### Kubernetes 配置管理工具扩展支持 + +在 KCL v0.5.0 中，我们以统一的编程界面方式为 Kubernetes 社区的 Kubectl, Helm, Kustomize, KPT 等配置管理工具提供了插件支持，编写几行配置代码即可无侵入地完成对存量 Kustomize YAML，Helm Charts 的编辑和校验，比如修改资源标签/注解, 注入 Sidecar 容器配置，使用 KCL schema 校验资源，定义自己的抽象模型并分享复用等。 + +下面以 Kubectl 工具对 KCL 的集成为例进行详细说明。您可以在[这里](https://github.com/kcl-lang/kubectl-kcl)获取 Kubectl KCL 插件的安装方式 + +首先执行如下命令获取一个配置示例 + +```shell +git clone https://github.com/kcl-lang/kubectl-kcl.git && cd ./kubectl-kcl/examples/ +``` + +然后执行如下命令显示配置 + +```shell +$ cat krm-kcl-abstration.yaml +apiVersion: krm.kcl.dev/v1alpha1 +kind: KCLRun +metadata: + name: web-service-abtraction +spec: + params: + name: app + containers: + ngnix: + image: ngnix + ports: + - containerPort: 80 + service: + ports: + - port: 80 + labels: + name: app + source: oci://ghcr.io/kcl-lang/web-service +``` + +在上述配置中，我们使用了在 OCI 上已经预定好的一个 Kubernetes Web 服务应用抽象模型 `oci://ghcr.io/kcl-lang/web-service`, 并通过 `params` 字段配置了该模型所需的配置字段。通过执行如下命令可以获得原始的 Kubernetes YAML 输出并下发到集群: + +```bash +$ kubectl kcl apply -f krm-kcl-abstration.yaml + +deployment.apps/app created +service/app created +``` + +更多 Kubernetes 配置管理工具详细介绍内容以及用例[详见](https://github.com/kcl-lang/krm-kcl/tree/main/examples) + +目前 KCL 支持的 Kubernetes 配置管理工具集成仍处于早期，如果您有更多的想法和需求，欢迎发起 Issues 讨论共建 + +## 其他更新与错误修复 + +完整更新和错误修复列表[详见](https://github.com/kcl-lang/kcl/compare/v0.4.6...v0.5.0) + +## 文档更新 + +[KCL 网站](https://kcl-lang.io/) 新增 KCL v0.5.0 文档内容并支持版本化语义选项，目前支持 v0.4.3, v0.4.4, v0.4.5, v0.4.6 和 v0.5.0 版本选择。同时欢迎社区同学进行文档共建。 + +## 社区动态 + ++ 感谢 @harri2012 对 KCL IDE 插件的首次贡献 🙌 ++ 感谢 @niconical 对 KCL 命令行基础代码和 CI/CD 脚本的贡献 🙌 ++ 感谢 @Ekko 对 KCL 云原生工具集成的贡献 🙌 ++ 恭喜来自华中科技大学朱俊星同学成功入选 GitLink编程夏令营（GLCC）"Terraform/JsonSchema 转 KCL Schema" 课题 🎉 ++ 恭喜来自东南大学的任一鸣同学成功入选 开源之夏 "IDE 插件增强和 Language Server 集成" 课题 🎉 ++ 为便于 KCL 及其子项目的仓库检索和管理，我们将 KCL 30+ 仓库整体搬迁到了新的 Github **kcl-lang** 组织，牢记项目地址，防止迷路 [https://github.com/kcl-lang](https://github.com/kcl-lang) ❤️ ++ KCL 加入 CNCF Landscape，算是云原生社区对我们小小的鼓励和认可，下一步计划是努力加入 CNCF Sadbox，为云原生社区作出更多的贡献 💪 + +## 下一步计划 + +预计 2023 年 9 月，我们将发布 **KCL v0.6.0 版本**，预期重点演进包括： + ++ 更多针对场景问题的 KCL 语言编写便利性改进，用户界面持续优化与体验提升，用户支持和痛点解决 ++ 更多 IDE 插件、语言工具链、包管理工具、Registry 功能支持和用户体验提升 ++ 针对云原生场景提供更多开箱即用的 KCL 模型支持，主要包含容器、服务、计算、存储和网络等 ++ 更多的 CI/CD 工具集成：如 Jenkins, Gitlab CI, FluxCD 等。 ++ 支持 Helmfile KCL 插件，通过 KCL 代码直接生成、编辑和校验 Kubernetes 原生资源 ++ 支持在 Kubernetes 运行时通过 KCL Operator 运行代码对 YAML 进行编辑和校验 + +更多详情请参考 [KCL 2023 路线规划](https://kcl-lang.io/docs/community/release-policy/roadmap) 和 [KCL v0.6.0 Milestone](https://github.com/kcl-lang/kcl/milestone/6) + +如果您有更多的想法和需求，欢迎在 KCL Github 仓库发起 [Issues](https://github.com/kcl-lang/kcl/issues)，也欢迎加入我们的社区进行交流 🙌 🙌 🙌 + +## 常见问题及解答 + +详见 [KCL 常见问题](https://kcl-lang.io/docs/user_docs/support/faq-kcl) + +## 其他资源 + +感谢所有 KCL 用户和社区小伙伴在此次版本更新过程中提出的宝贵反馈与建议。 + +更多其他资源请参考： + ++ [KCL 网站](https://kcl-lang.io/) ++ [Kusion 网站](https://kusionstack.io/) ++ [KCL Github 仓库](https://github.com/kcl-lang/kcl) ++ [Kusion Github 仓库](https://github.com/KusionStack/kusion) ++ [Konfig Github 仓库](https://github.com/KusionStack/konfig) + +欢迎加入我们的社区进行交流 👏👏👏：[https://github.com/kcl-lang/community](https://github.com/kcl-lang/community) diff --git a/static/img/blog/2023-07-14-kcl-0.5.0-release/app-ci.png b/static/img/blog/2023-07-14-kcl-0.5.0-release/app-ci.png new file mode 100644 index 00000000..3bc1bd4d Binary files /dev/null and b/static/img/blog/2023-07-14-kcl-0.5.0-release/app-ci.png differ diff --git a/static/img/blog/2023-07-14-kcl-0.5.0-release/app.png b/static/img/blog/2023-07-14-kcl-0.5.0-release/app.png new file mode 100644 index 00000000..121186ae Binary files /dev/null and b/static/img/blog/2023-07-14-kcl-0.5.0-release/app.png differ diff --git a/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-app.png b/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-app.png new file mode 100644 index 00000000..1784f9dc Binary files /dev/null and b/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-app.png differ diff --git a/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-sync.png b/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-sync.png new file mode 100644 index 00000000..70c24af0 Binary files /dev/null and b/static/img/blog/2023-07-14-kcl-0.5.0-release/argocd-sync.png differ diff --git a/static/img/blog/2023-07-14-kcl-0.5.0-release/auto-update.png b/static/img/blog/2023-07-14-kcl-0.5.0-release/auto-update.png new file mode 100644 index 00000000..4b1550c0 Binary files /dev/null and b/static/img/blog/2023-07-14-kcl-0.5.0-release/auto-update.png differ