Kclipper

<p align="center"> <a href="#"><img src="docs/img/logo.svg" width="150px"></a> <h1 align="center">kclipper</h1> </p> <p align="center"><i>KCL + Helm = kclipper</i></p> <p align="center"> <a href="https://pkg.go.dev/github.com/macropower/kclipper"><img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/macropower/kclipper.svg"></a> <a href="https://goreportcard.com/report/github.com/macropower/kclipper"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/macropower/kclipper"></a> <a href="https://codecov.io/gh/macropower/kclipper"><img src="https://codecov.io/gh/macropower/kclipper/graph/badge.svg?token=S9MJNCPGYK"/></a> <a href="#installation"><img alt="GitHub Downloads" src="https://img.shields.io/github/downloads/macropower/kclipper/total"></a> <a href="#installation"><img alt="Latest tag" src="https://img.shields.io/github/v/tag/macropower/kclipper?label=version&sort=semver"></a> <a href="https://github.com/macropower/kclipper/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/macropower/kclipper"></a> </p>

Overview

KCL is a constraint-based record & functional language mainly used in cloud-native configuration and policy scenarios. It is hosted by the Cloud Native Computing Foundation (CNCF) as a Sandbox Project. The KCL website can be found here.

Kclipper combines KCL and Helm by wrapping KCL with additional plugins and commands, and by providing modules which act as friendly plugin interfaces.

Learn how kclipper compares to Holos and other KCL Helm plugins here.

To use kclipper, you must install it as a KCL replacement. Kclipper is a superset of KCL; all upstream KCL commands, packages, etc., are preserved. Docker images for x86 and arm64 are also available, which allow kclipper to be used as an Argo CD Config Management Plugin.

Features

Render Helm charts directly within KCL; take full control of all resources both pre- and post-rendering. Use KCL to its full potential within the Helm ecosystem for powerful and flexible templating, especially in multi-cluster scenarios where ApplicationSets and/or abstract interfaces similar to konfig are heavily utilized:

import helm
import manifests
import regex
import charts.podinfo
import charts.kube_prometheus_stack.api.v1 as prometheusv1

env = option("env")

_podinfo = helm.template(podinfo.Chart {
    valueFiles = [
        "values.yaml",
        "values-${env}.yaml",
    ]
    values = podinfo.Values {
        replicaCount = 3
    }
    postRenderer = lambda resource: {str:} -> {str:} {
        if regex.match(resource.metadata.name, "^podinfo-service-test-.*$"):
            resource.metadata.annotations |= {"example.com/added" = "by kcl patch"}
        resource
    }
})

_serviceMonitor = prometheusv1.ServiceMonitor {
    metadata.name = "podinfo"
    spec.selector.matchLabels = {
        app = "podinfo"
    }
}

manifests.yaml_stream([*_podinfo, _serviceMonitor])

See macropower/homelab for more examples. It defines 50+ charts and 100+ ArgoCD Apps using kclipper and a konfig-based library.

---

Declaratively manage all of your Helm charts and their schemas. Private, OCI, and local repos are all supported. Choose from a variety of available schema generators to enable validation, auto-completion, on-hover documentation, and more for Chart, CRD, and Value objects, as well as values.yaml files (if you prefer YAML over KCL for values, or want to use both). Use KCL keys to define the same chart with unique configuration (e.g. multiple targetRevisions). Optionally, use the kcl chart command to make quick edits from the command line:

import helm

charts: helm.Charts = {
    # kcl chart add -c podinfo -r https://stefanprodan.github.io/podinfo -t "6.7.0"
    podinfo: {
        chart = "podinfo"
        repoURL = "https://stefanprodan.github.io/podinfo"
        targetRevision = "6.7.0"
        schemaGenerator = "AUTO"
    }
    # kcl chart repo add -n bjw-s -u https://bjw-s.github.io/helm-charts/
    # kcl chart add -c app-template -r @bjw-s -t "3.6.0"
    app_template_v3: {
        chart = "app-template"
        repoURL = "@bjw-s"
        targetRevision = "3.6.0"
        schemaValidator = "KCL"
        schemaGenerator = "CHART-PATH"
        schemaPath = "charts/common/values.schema.json"
        repositories = [repos.bjw_s]
    }
    # kcl chart add -c my-chart -r ./my-charts/
    my_chart: {
        chart = "my-chart"
        repoURL = "./my-charts/"
        crdGenerator = "TEMPLATE"
    }
}

---

Automate updates to all KCL and JSON Schemas, in accordance with your declarations:

Also works with Renovate! You can find example pull requests and a config file in this repo.

---

Enjoy blazing-fast reconciliation times. Kclipper is built with performance in mind and is optimized for speedy rendering at runtime. It achieves this with a custom Helm template implementation, based on the Argo CD Helm source implementation, with edits to minimize I/O.

| Chart | Vanilla Argo CD | kclipper | kclipper (schemaValidator=KCL) | | :----------- | :-------------- | :--------- | :----------------------------- | | podinfo | 9.1 ms/op | 0.78 ms/op | 0.76 ms/op (~12x) | | app-template | 159 ms/op | 143 ms/op | 1.48 ms/op (~107x) |

Approximate values from my Mac Mini M2.

See benchmarks for more details.

Installation

OCI artifacts for KCL are available under packages.

The binary name for kclipper is still just kcl, so it can be used as a drop-in replacement for official KCL binaries. Versions are tagged independently of upstream KCL, e.g. kclipper v0.1.0 maps to kcl v0.11.0, but kclipper releases still follow semver with consideration for upstream KCL changes.

Using Homebrew

You cannot have both kcl and kclipper installed via Homebrew. If you already installed kcl via Homebrew, you should uninstall it before proceeding.

You can install macropower/tap/kclipper to obtain kcl and kcl-language-server binaries.

brew tap macropower/tap
brew install macropower/tap/kclipper

kcl version
kcl-language-server version

Using Docker

Docker images are available under packages, e.g.:

docker pull ghcr.io/macropower/kclipper:latest

To use kclipper with Argo CD, see the Argo CD Config Management Plugin docs.

Using Release Archives

Binary archives are posted in releases.

Usage

This guide assumes you are fully utilizing plugins, packages, and the kcl chart CLI. If you only want to use a subset of these, please see the extension docs.

First, navigate to your project directory. If you don't have a KCL project set up yet, you can run the following command:

kcl mod init

We now have the following project structure:

.
├── kcl.mod
├── kcl.mod.lock
└── main.k

Now, we can initialize a new charts package:

kcl chart init

This should result in a project structure similar to the following:

.
├── charts
│   ├── charts.k
│   ├── kcl.mod
│   └── kcl.mod.lock
├── main.k
├── kcl.mod
└── kcl.mod.lock

The important note is that the charts package is available to your KCL code, but is in its own separate package. You should not try to combine packages or write your own code inside the charts package, other than to edit the charts.k file.

The charts.k file will have no entries by default.

import helm

charts: helm.Charts = {}

You can add a new chart to your project by running the following command:

kcl chart add -c podinfo -r https://stefanprodan.github.io/podinfo -t "6.7.0"

This command will automatically add a new entry to your charts.k file, and generate a new podinfo package in your charts directory.

:warning: Everything in the chart sub-packages, podinfo in this case, is auto-generated, and any manual edits will be lost. If you need to make changes, you should do so in the charts.k file, or in your own package that imports the podinfo package (e.g. via overriding attributes).

Your project structure should now look like this:

.
├── charts
│   ├── charts.k
│   ├── kcl.mod
│   ├── kcl.mod.lock
│   └── podinfo
│       ├── chart.k
│       ├── values.schema.json
│       └── values.schema.k
├── main.k
├── kcl.mod
└── kcl.mod.lock

And your charts.k file will have a new entry for the podinfo chart:

import helm

charts: helm.Charts = {
    podinfo: {
        chart = "podinfo"
        repoURL = "https://stefanprodan.github.io/podinfo"
        targetRevision = "6.7.0"
        schemaGenerator = "AUTO"
    }
}

Note that keys and folder/package names will be valid KCL identifiers, whereas the chart argument is the name of the Helm chart. Typically these will be the same, but for example an app-template chart will have a key and folder/package named app_template.

The charts.podinfo package will contain the schemas podinfo.Chart and podinfo.Values, as well as a values.schema.json file for use with your values.yaml files, should you choose to use them. You can now use these objects in your main.k file:

import helm
import char