Skip to main content

16 posts tagged with "KCL"

View All Tags

· 6 min read

Introduction

Kustomize provides a solution to customize the basic configuration and differential configuration of Kubernetes resources without templates. The configuration can be merged or overwritten through file-level YAML configuration with multiple strategies. In Kustomize, users need to know more about the content and location to be changed, For basic YAML with complex recursion too deep, it may not be easy to match Kustomize files through selectors.

In KCL, the user can directly write the configuration that needs to be modified in the corresponding code in the corresponding place, eliminating the cost of reading basic YAML. At the same time, the user can reuse the configuration fragments by code, avoiding massive copying and pasting of YAML configuration. The information density is higher, and it is not easy to make mistakes through KCL.

A classic example of Kustomize multi-environment configuration management is used to explain the differences between Kustomize and KCL in Kubernetes resource configuration management.

Kustomize

Kustomize has the concepts of base and overlay. In general, base and overlay are general a directory including a kustomization.yaml file. One base directory can be used by multiple overlay directories.

We can execute the following command line to obtain a typical Kustomize project

  • Create a base directory and create a deployment resource
# Create a directory to hold the base
mkdir base
# Create a base/deployment.yaml
cat <<EOF > base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ldap
labels:
app: ldap
spec:
replicas: 1
selector:
matchLabels:
app: ldap
template:
metadata:
labels:
app: ldap
spec:
containers:
- name: ldap
image: osixia/openldap:1.1.11
args: ["--copy-service"]
volumeMounts:
- name: ldap-data
mountPath: /var/lib/ldap
ports:
- containerPort: 389
name: openldap
volumes:
- name: ldap-data
emptyDir: {}
EOF
# Create a base/kustomization.yaml
cat <<EOF > base/kustomization.yaml
resources:
- deployment.yaml
EOF
  • Create a directory to hold the prod overlay configuration.
# Create a directory to hold the prod overlay
mkdir prod
# Create a prod/deployment.yaml
cat <<EOF > prod/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ldap
spec:
replicas: 6
template:
spec:
volumes:
- name: ldap-data
emptyDir: null
gcePersistentDisk:
readOnly: true
pdName: ldap-persistent-storage
EOF
cat <<EOF > prod/kustomization.yaml
resources:
- ../base
patchesStrategicMerge:
- deployment.yaml
EOF

Thus, we can get a basic Kustomize directory

.
├── base
│ ├── deployment.yaml
│ └── kustomization.yaml
└── prod
├── deployment.yaml
└── kustomization.yaml

The base directory stores the basic deployment configuration, and the prod environment stores the deployment configuration that needs to be overwritten. The metadata.name and other attributes such as spec.template.spec.volumes[0].name are used to indicate which resource to overwrite

We can display the real deployment configuration of the prod environment through the following command.

$ kubectl kustomize ./prod
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: ldap
name: ldap
spec:
replicas: 6
selector:
matchLabels:
app: ldap
template:
metadata:
labels:
app: ldap
spec:
containers:
- args:
- --copy-service
image: osixia/openldap:1.1.11
name: ldap
ports:
- containerPort: 389
name: openldap
volumeMounts:
- mountPath: /var/lib/ldap
name: ldap-data
volumes:
- gcePersistentDisk:
pdName: ldap-persistent-storage
readOnly: true
name: ldap-data

We can also directly apply the configuration to the cluster through the following command.

$ kubectl apply -k ./prod

deployment.apps/ldap created

KCL

We can write the following KCL code and name it main.k.

apiVersion = "apps/v1"
kind = "Deployment"
metadata = {
name = "ldap"
labels.app = "ldap"
}
spec = {
replicas = 1
# When env is prod, override the `replicas` attribute with `6`
if option("env") == "prod": replicas = 6
# Assign `metadata.labels` to `selector.matchLabels`
selector.matchLabels = metadata.labels
template.metadata.labels = metadata.labels
template.spec.containers = [
{
name = metadata.name
image = "osixia/openldap:1.1.11"
args = ["--copy-service"]
volumeMounts = [{ name = "ldap-data", mountPath = "/var/lib/ldap" }]
ports = [{ containerPort = 80, name = "openldap" }]
}
]
template.spec.volumes = [
{
name = "ldap-data"
emptyDir = {}
# When env is prod
# override the `emptyDir` attribute with `None`
# patch a `gcePersistentDisk` attribute with the value `{readOnly = True, pdName = "ldap-persistent-storage"}`
if option("env") == "prod":
emptyDir = None
gcePersistentDisk = {
readOnly = True
pdName = "ldap-persistent-storage"
}
}
]
}

In the above KCL code, we declare the apiVersion, kind, metadata, spec and other attributes of a Kubernetes Deployment resource, and assign the corresponding contents respectively. In particular, we assign metadata.labels to spec.selector.matchLabels and spec.template.metadata.labels. It can be seen that the data structure defined by KCL is more compact than Kustomize or YAML, and configuration reuse can be realized by defining local variables.

In KCL, we can dynamically receive external parameters through conditional statements and the option builtin function, and set different configuration values for different environments to generate resources. For example, for the above code, we wrote a conditional statement and entered a dynamic parameter named env. When env is prod, we will overwrite the replicas attribute from 1 to 6, and make some adjustments to the volume configuration named ldap-data, such as changing the emptyDir attribute to None, and adding the configuration value of gcePersistentDisk.

We can use the following command to view diff between different environment configurations

diff \
<(kcl main.k) \
<(kcl main.k -D env=prod) |\
more

The output is

8c8
< replicas: 1
---
> replicas: 6
30c30,33
< emptyDir: {}
---
> emptyDir: null
> gcePersistentDisk:
> readOnly: true
> pdName: ldap-persistent-storage

It can be seen that the diff between the production environment configuration and the base configuration mainly lies in the attributes of replicas, emptyDir and gcePersistentDisk, which is consistent with the expectation.

In addition, we can use the -o parameter of the KCL command line tool to output the compiled YAML to a file and view the diff between files

# Generate base deployment
kcl main.k -o deployment.yaml
# Generate prod deployment
kcl main.k -o prod-deployment.yaml -D env=prod
# Diff prod deployment and base deployment
diff prod-deployment.yaml deployment.yaml

Of course, we can also use KCL tools together with kubectl and other tools to apply the configuration of the production environment to the cluster

$ kcl main.k -D env=prod | kubectl apply -f -

deployment.apps/ldap created

Finally, check the deployment status through kubectl

$ kubectl get deploy

NAME READY UP-TO-DATE AVAILABLE AGE
ldap 0/6 6 0 15s

It can be seen from the results of the command that it is completely consistent with the deployment experience of using Kustomize configuration and kubectl apply directly, and there are no more side effects.

Summary

This article briefly introduces the quick start of writing complex multi-environment Kubernetes configuration with KCL and the comparison of Kustomize tool for Kubernetes multi-environment configuration management.

It can be seen that, compared with Kustomize, KCL reduces the number of configuration files and code lines by means of code generation on the basis of configuration reuse and coverage, And like Kustomize, it is a pure client solution, which can move the configuration and policy verification to the left as far as possible without additional dependency or burden on the cluster, or even without a real Kubernetes cluster.

· 4 min read

What is KCL

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.

What is KCL Go SDK?

kclvm is a runtime library for the KCL language that provides a programming interface for interacting with the KCL compiler. It is a client library that can be used to perform various operations on KCL source code such as execution and formatting. KCL Go SDK is a Go language wrapper for kclvm that provides an SDK for KCL language integration in cloud-native environments.

The current version of KCL Go SDK is built on top of the kclvm json2 RPC API, which means that it uses the same API as other language KCL clients to interact with KCL source code. The way it works is similar to other language KCL SDKs, but it provides a more user-friendly Go language style wrapper.

What problems does the new version of KCL Go SDK solve?

KCL is closely related to the cloud-native domain as a configuration language, while on the other hand, Go has become the de facto standard programming language for cloud-native domains. In this context, the development of a Go SDK for the KCL compiler to directly interact with Go was necessary, which is the reason for the creation of KCL Go SDK.

The initial version of the KCL compiler and runtime were written in Python, and the runtime for the first version of the KCL language had a lot of room for improvement in terms of performance and security due to the performance issues and characteristics of the dynamic nature of the Python language. In light of security and efficiency considerations, later versions of the KCL compiler were written in the Rust programming language. As a result, the new version of KCL Go SDK is based on rust-implemented kclvm packaging, eliminating Python dependencies, simplifying installation, and optimizing the user experience.

Quickly experience KCL Go SDK via the command line

KCL Go SDK provides a built-in command line tool named kcl-go ,which supports one-click installation through go install. The local Go version must be 1.18+ and the complete CGO toolchain is required.

Simply run:

go install kusionstack.io/kclvm-go/cmds/kcl-go@latest

Create a new KCL source file hello.k

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

And then execute the KCL directly from the command line with:

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

How to integrate KCL with Go code?

Here is an example of how to integrate KCL into your Go program. Using the hello.k file from the previous example, construct the following main.go code:

package main

import (
"fmt"
"kusionstack.io/kclvm-go"
)

func main() {
result := kclvm.MustRun("./hello.k").GetRawYamlResult()
fmt.Println(result)
}
  • kclvm.MustRun("./hello.k").GetRawYamlResult() runs the corresponding KCL source file
  • fmt.Println(result) prints the result of the run

The local environment requires Go version 1.18+ and a complete CGO toolchain. Add the KCL Go SDK dependency to this command line tool by running:

go get kusionstack.io/kclvm-go@main

The following command runs the Go program:

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

Conclusion

Through the version change, we have removed Python dependencies and switched to a more efficient Rust runtime. The article briefly demonstrates how to use the kcl-go command line tool to execute KCL source code and how to integrate KCL into your Go program.

In addition to compiling and running KCL source code, the KCL Go SDK provides a variety of features to facilitate KCL integration in Go, including:

  • KCL static error analysis (lint and format)
  • KCL dependency analysis
  • Go struct and KCL Schema mutual conversion

Additional Resources

Thank all KCL users for their valuable feedback and suggestions during this version release. For more resources, please refer to:

See the community for ways to join us. 👏👏👏