kcl-lang / kubectl-kcl

Kubectl KCL Plugin

Kubectl KCL Plugin

KCL is a constraint-based record & functional domain language. Full documents of KCL can be found here.

This project is a kubectl plugin to generate, mutate and validate Kubernetes manifests using the KCL programming language.

Installation

Use this as a kubectl plugin.

From Krew Index

Add to krew index and install with:

kubectl krew index add kubectl-kcl https://github.com/kcl-lang/kubectl-kcl
kubectl krew install kubectl-kcl/kcl

From GitHub Releases

Download the binary from GitHub releases, then copy the kubectl-kcl binary to your PATH. If not, you can also use the binary standalone.

Usage

kubectl kcl run -f ./examples/kcl-run.yaml

Developing

Prerequisites

• GoLang 1.22+

git clone https://github.com/kcl-lang/kubectl-kcl.git
cd kubectl-kcl
go run main.go

Test

Unit Test

go test ./...

Integration Test

go run main.go run -f ./examples/kcl-run.yaml

Guides for Developing KCL

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

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

Full documents of KCL can be found here.

kubectl-kcl's Issues

Don't support running multiple KCLRun simultaneously

Bug Report

Please answer these questions before submitting your issue. Thanks!

1. Minimal reproduce step (Required)

I've written two KCLRun objects in a single YAML file. When I run kubectl kcl run, I encounter an error.

$ kubectl kcl run -f ./bug.yml 
panic: runtime error: index out of range [2] with length 1

goroutine 1 [running]:
kcl-lang.io/krm-kcl/pkg/kio.Filter.Filter({0x140008e3880}, {0x14000121d70, 0x3, 0x3})
        kcl-lang.io/[email protected]/pkg/kio/filter.go:31 +0x180
sigs.k8s.io/kustomize/kyaml/kio.Pipeline.ExecuteWithCallback({{0x14000b9fc58, 0x1, 0x1}, {0x14000b9fc48, 0x1, 0x1}, {0x14000b9fc38, 0x1, 0x1}, 0x0}, ...)
        sigs.k8s.io/kustomize/[email protected]/kio/kio.go:137 +0x24c
sigs.k8s.io/kustomize/kyaml/kio.Pipeline.Execute({{0x1400093fc58, 0x1, 0x1}, {0x1400093fc48, 0x1, 0x1}, {0x1400093fc38, 0x1, 0x1}, 0x0})
        sigs.k8s.io/kustomize/[email protected]/kio/kio.go:104 +0x6c
kcl-lang.io/kubectl-kcl/pkg/options.(*RunOptions).Run(0x0?)
        kcl-lang.io/kubectl-kcl/pkg/options/run.go:35 +0x184
kcl-lang.io/kubectl-kcl/cmd.NewRunCmd.func1(0x14000abc600, {0x1017aacc5, 0x2, 0x2})
        kcl-lang.io/kubectl-kcl/cmd/run.go:19 +0x20
github.com/spf13/cobra.(*Command).execute(0x14000abc600, {0x14000ab9160, 0x2, 0x2})
        github.com/spf13/[email protected]/command.go:940 +0x5c8
github.com/spf13/cobra.(*Command).ExecuteC(0x14000abc000)
        github.com/spf13/[email protected]/command.go:1068 +0x35c
github.com/spf13/cobra.(*Command).Execute(0x101d5f520?)
        github.com/spf13/[email protected]/command.go:992 +0x1c
main.main()
        kcl-lang.io/kubectl-kcl/main.go:10 +0x20

However, if I run each object separately, it works fine. But the result includes two annotations for each object that KCL added itself:

annotations:
    config.kubernetes.io/index: '0'
    internal.config.kubernetes.io/index: '0'

This is the yaml including two KCLRun object.

apiVersion: v1
kind: Service
metadata:
  name: default-domain-service
  namespace: knative-serving
spec:
  clusterIP: None
  selector:
    app: default-domain
  ports:
    - name: http
      port: 80
      targetPort: 8080
  type: ClusterIP
---
apiVersion: krm.kcl.dev/v1alpha1
kind: KCLRun
metadata:
  name: change-service-type
spec:
  params:
    annotations:
      managed-by: kubectl-kcl
  source: |
    [item | {
      if item.kind == "Service":
          spec.type = "LoadBalance"
    } for item in option("items")]
---
apiVersion: krm.kcl.dev/v1alpha1
kind: KCLRun
metadata:
  name: add-labels
spec:
  params:
    annotations:
      managed-by: kubectl-kcl
  source: |
    [item | {
      if item.kind == "Service":
          metadata.labels = {
              app = item.metadata.name
          }
    } for item in option("items")]
---

2. What did you expect to see? (Required)

Get the correct result.

3. What did you see instead (Required)

Encountered an error.

4. What is your KCL components version? (Required)

• kubectl-kcl 0.4.0
• kcl 0.5.3

Don't work with multiple files

Bug Report

Please answer these questions before submitting your issue. Thanks!

1. Minimal reproduce step (Required)

kubectl kcl run -f original.yaml kcl.yaml

I have a bunch of YAML files and I want to make changes to all of them using kcl. So, I created a KCL object in a YAML file called kcl.yaml. Then, I tried running kubectl kcl run with multiple YAML files. Unfortunately, it didn't work out as expected. It seems like this command doesn't support this use case.

$ kubectl kcl run --help
Run KCL codes.

Usage:
  kcl run [flags]

Flags:
  -f, --filename string   input kcl spec file to pass to kubectl kcl
  -h, --help              help for run
  -o, --output string     output yaml path, default is stdout

2. What did you expect to see? (Required)

The YAML content has been modified.

3. What did you see instead (Required)

Doesn't work.

4. What is your KCL components version? (Required)

• kubectl-kcl 0.4.0
• kcl 0.5.3

kubectl krew install failed with status code 404

Bug Report

1. Minimal reproduce step

Execute krew install:

kubectl krew index add kubectl-kcl https://github.com/kcl-lang/kubectl-kcl
kubectl krew install kubectl-kcl/kubectl-kcl

2. What did you expect to see?

Successful installation expected

3. What did you see instead

A page Not Found error (status 404). The installation script tries to download v0.1.0 instead of the latest release version.

kubectl krew install kubectl-kcl/kubectl-kcl
Updated the local copy of plugin index.
Updated the local copy of plugin index "kubectl-kcl".
Installing plugin: kubectl-kcl
W0317 20:37:07.876641   54479 install.go:164] failed to install plugin "kubectl-kcl": install failed: failed to unpack into staging dir: failed to unpack the plugin archive: failed to obtain plugin archive: failed to download "https://github.com/kcl-lang/kubectl-kcl/releases/download/v0.1.0/kubectl-kcl-linux-amd64.tar.gz", status code 404
failed to install some plugins: [kubectl-kcl]: install failed: failed to unpack into staging dir: failed to unpack the plugin archive: failed to obtain plugin archive: failed to download "https://github.com/kcl-lang/kubectl-kcl/releases/download/v0.1.0/kubectl-kcl-linux-amd64.tar.gz", status code 404

4. What is your KCL components version?

kcl version
0.8.1-linux-amd64

Apply options and run options need more validation

Enhancement

Now the code only impl the basic feature. apply and run operation need more validation.
cc: @Peefy

krew plugin installation not working

Due to subdirectories in the release-archives the krew installation is not working. I will also submit a PR with a fix

krew installation not working on Macos

1. Minimal reproduce step (Required)

kubectl krew install kubectl-kcl/kubectl-kcl

2. What did you expect to see? (Required)

Installation successful

3. What did you see instead (Required)

Updated the local copy of plugin index.
Updated the local copy of plugin index "kubectl-kcl".
Installing plugin: kubectl-kcl
W0415 11:43:01.188678 68348 install.go:164] failed to install plugin "kubectl-kcl": install failed: failed to unpack into staging dir: failed to unpack the plugin archive: failed to obtain plugin archive: failed to download "https://github.com/kcl-lang/kubectl-kcl/releases/download/v0.5.0/kubectl-kcl-darwin-amd64.tar.gz", status code 404
failed to install some plugins: [kubectl-kcl]: install failed: failed to unpack into staging dir: failed to unpack the plugin archive: failed to obtain plugin archive: failed to download "https://github.com/kcl-lang/kubectl-kcl/releases/download/v0.5.0/kubectl-kcl-darwin-amd64.tar.gz", status code 404

4. Solution

The files are named differently. It needs to be kubectl-kcl-macos-amd64.tar.gz in my case.

Please fix it in builds or rename the binaries in krew-index-file. Thanks!