Skip to main content
Version: Next

KPT KCL SDK

Introduction​

kpt is a package-centric toolchain that enables a configuration authoring, automation, and delivery experience, which simplifies managing Kubernetes platforms and KRM-driven infrastructure (e.g., Config Connector, Crossplane) at scale by manipulating declarative Configuration as Data for automating Kubernetes configuration editing including transforming and validating.

KCL can be used to create functions to transform and/or validate the YAML Kubernetes Resource Model (KRM) input/output format, but we provide KPT KCL SDKs to simplify the function authoring process.

Prerequisites​

Quick Start​

Let’s write a KCL function which add annotation managed-by=kpt only to Deployment resources.

1. Get the Example​

git clone https://github.com/kcl-lang/kpt-kcl-sdk.git/
cd ./kpt-kcl-sdk/get-started/set-annotation

2. Show the KRM​

kpt pkg tree

The output is

set-annotation
├── [kcl-fn-config.yaml]  KCLRun set-annotation
└── data
    ├── [resources.yaml]  Deployment nginx-deployment
    └── [resources.yaml]  Service test

3. Show and Update the KCL FunctionConfig​

cat ./kcl-fn-config.yaml

The output is

# kcl-fn-config.yaml
apiVersion: krm.kcl.dev/v1alpha1
kind: KCLRun
metadata: # kpt-merge: /set-annotation
  name: set-annotation
spec:
  # EDIT THE SOURCE!
  # This should be your KCL code which preloads the `ResourceList` to `option("resource_list")`
  source: |
    [resource | {if resource.kind == "Deployment": metadata.annotations: {"managed-by" = "kpt"}} for resource in option("resource_list").items]

4. Test and Run​

Run the KCL code via kpt

kpt fn eval ./data -i docker.io/kcllang/kpt-kcl:v0.2.0 --fn-config kcl-fn-config.yaml

# Verify that the annotation is added to the `Deployment` resource and the other resource `Service` 
# does not have this annotation.
cat ./data/resources.yaml | grep annotations -A1 -B0

The output is

  annotations:
    managed-by: kpt

It can be seen that we have indeed added the annotation managed-by=kpt.

Guides for Developing KCL​

Here's what you can do in the KCL code:

  • Read resources from option("resource_list"). The option("resource_list") complies with the KRM Functions Specification. You can read the input resources from option("resource_list")["items"] and the functionConfig from option("resource_list")["functionConfig"].
  • Return a KPM list for output resources.
  • Return an error using assert {condition}, {error_message}.

More Documents and Examples​