Skip to main content
Version: 0.4.5

Adopt From Kubernetes to KCL

1. Kubernetes OpenAPI Spec​

Starting from Kubernetes 1.4, the alpha support for the OpenAPI specification (known as Swagger 2.0 before it was donated to the OpenAPI Initiative) was introduced, and the API descriptions follow the OpenAPI Spec 2.0. And since Kubernetes 1.5, Kubernetes supports directly extracting models from source code and then generating the OpenAPI spec file to automatically keep the specifications and documents up to date with the operation and models.

In addition, Kubernetes CRD uses OpenAPI V3.0 validation to describe a custom schema (in addition to the built-in attributes apiVersion, Kind, and metadata), that APIServer uses to validate the CR during the resource creation and update phases.

2. KCL OpenAPI Support​

The kcl-openapi tool supports extracting and generating KCL schemas from Kubernetes OpenAPI/CRD. the KCL OpenAPI Spec defines the mapping between the OpenAPI specification and the KCL language features. For a quick start with the tool, see KCL OpenAPI tool

3. Migrate From Kubernetes To KCL​

3.1 Write configurations based on the Kusion_Models package​

We provide an out-of-the-box `kusion_models` package for you to quickly start. It contains a well-designed frontend model called [`Server schema`](https://github.com/KusionStack/konfig/blob/main/base/pkg/kusion_models/kube/frontend/server.k). You can declare the configurations by initializing the `Server schema`. For the description and usage of the schema and its attributes, please refer to the [Server schema documentation](https://kusionstack.io/docs/reference/model/kusion_models/kube/frontend/doc_server).

3.2 Build Your Custom Frontend Models​

The existing KCL Models may not meet your specific business requirements, then you can also design your custom frontend model package. You can design your custom models based on the pre-generated Kubernetes KCL models among all versions. And you can also develop your custom scripts to migrate your configuration data as what kube2kcl tool does.

3.2.1 Get the k8s package​

The Kubernetes KCL models among all versions are pre-generated, you get it by executing kpm add k8s:<version> under your project. For detailed information about kpm usage, please refer to kpm quick start guide.

Alternatively, if you may want to generate them yourself, please refer to Generate KCL Packages from Kubernetes OpenAPI Specs.

3.2.2 Design Custom Frontend Models​

Since the Kubernetes built-in models are atomistic and kind of complex to beginners, we recommend taking the native model of Kubernetes as the backend output model and designing a batch of frontend models which could become a more abstract, friendlier and simpler interface to the user. You can refer to the design pattern in the Server Schema in the Konfig repo.

3.2.3 Migrate The Configuration Data​

You can develop your custom scripts to migrate your configuration data automatically. KCL will later provide writing scaffolding and writing guidelines for this script.

4. Migrate From Kubernetes CRD​

If you developed CRDs, you can generate the KCL version of the CRD schemas and declare CRs based on that.

  • Generate KCL Schema from CRD

    kcl-openapi generate model --crd --skip-validation -f <your_crd.yaml>

  • Define CR based on CRDs in KCL

    You can initialize the CRD schema to define a CR, or further, you can use the generated schema as a backend model and design a frontend interface for users to initialize. The practice is similar to what KCL Models does on Kubernetes built-in models.