Uniformity of kcl run and kcl mod add CLI, etc

[zong-zhe]

Uniformity of kcl mod add and kcl run CLI

1. This issue is created for

1. Support for seamless user experience with https/http.
2. Support for flexible referencing across multiple repositories including OCI, Git, and Localpath.
3. Uniformity in the style of add/run/push/pull commands to reduce user cognitive load.

2. The command design

The KCL command follows the following pattern:

kcl <op> <module_spec> <module_source>

1. <op> indicates an operation on a KCL module.
   • e.g. the <op> of command kcl mod add is mod add which means add a KCL module as dependency.
2. <module_spec> indicates the specification of the KCL module.
   • It mainly includes the module name and module version in the format <module_name>:<module_version>.
   • e.g. kcl mod add helloworld:0.1.2 means add a KCL module whose name is helloworld and version is 0.1.2 as dependency.
3. <module_source> indicates the source of the KCL module, including the specific source address and the corresponding selected flag.
   • e.g. kcl mod add cc:0.0.1 --git https://github.com/kcl-lang/flask-demo-kcl-manifests.git --commit 8308200 will clone the git repo with commit id and find the KCL module named cc with version 0.0.1 and add it as dependency.

Next, we will take kcl mod add as an example to give a more detailed case.

2.1 Direct use of https/http

We support the direct use of protocols starting with http/https, and use the flag to specify the module source type --oci or --git

Taking https as an example:

# Take the KCL module stored in oci registry as dependency. 
kcl mod add --oci https://ghcr.io/kcl-lang/helloworld --tag 0.1.2

# Take the KCL module stored in git repo as dependency. 
kcl mod add --git https://github.com/kcl-lang/flask-demo-kcl-manifests.git --branch main

2.2 Specifying using the oci/git protocol

kpm also supports the use of specific protocols to designate the source.

Specifying the source using the oci:// protocol:

kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.2

Specifying the source using the git:// protocol:

kcl mod add git://github.com/kcl-lang/flask-demo-kcl-manifests.git --branch main

For private git repo, ssh:// protocol is supported.

kcl mod add ssh://github.com/kcl-lang/flask-demo-kcl-manifests.git --branch main

3. The dependencies in kcl.mod

For kcl.mod, kpm supports writing dependencies as below, take k8s as example:

3.1 OCI Registry

Specify the KCL package source is OCI Registry

version it the oci tag

k8s = { oci=“oci://ghcr.io/kcl-lang/helloworld”, tag="0.1.2", version=“0.1.2”}

3.2 Git Registry

The design before:

#266

Some examples of other tools are referenced

• Go-getter: github.com/hashicorp/go-getter?ref=abcd1234
• Github: https://github.com/zong-zhe/kpm/releases/tag/v0.2.8
• Oras: localhost:5000/hello-artifact:v2
• Helm: helm pull oci://localhost:5000/helm-charts/mychart --version 0.1.0
• FluxCD:
• • flux pull artifact oci://ghcr.io/org/manifests/app:v0.0.1
• • flux create secret git podinfo-auth --url=ssh://[email protected]/stefanprodan/podinfo \

[Vanshikav123]

Hello ! @zong-zhe @Peefy is this issue still relevant can i work on it?

[zong-zhe]

Hi @Vanshikav123 😃

Welcome! You can begin with this task.

Remove the http/https switch and adjust oci access layer in kpm to support http/https non-awareness

I provide some more detailed information. Currently, kpm supports OCI Registries with URLs beginning with either 'https' or 'http' protocols.

• More details about 'kpm oci registry supports' - https://www.kcl-lang.io/docs/user_docs/guides/package-management/how-to/kpm_oci

kpm requires the environment variable OCI_REG_PLAIN_HTTP to be set, or you can adjust the field DefaultOciPlainHttp in kpm configuration file ~/.kcl/kpm/.kpm/config/kpm.json for its setup. Both OCI_REG_PLAIN_HTTP and DefaultOciPlainHttp influence the value of a switch variable within kpm.

• The switch variable is here:

  kpm/pkg/oci/oci.go

  Line 118 in bb39f68

  repo.PlainHTTP = settings.DefaultOciPlainHttp()

The state of this switch variable restricts kpm to effect only one protocol at a time—either https or http. This is quite detrimental to the user experience. It makes the user feel very confused. Users should not need to manually control this switch; kpm should support both http and https starting OCI registry urls without a switch control.

kpm utilizes the third-party library oras-go to implement the oci registry supports. I have noticed that oras is capable of working with OCI registry URLs starting with 'http' or 'https'.

• oras is https://github.com/oras-project/oras
• oras-go is https://github.com/oras-project/oras-go

Therefore, you could begin by research how the ORAS tool achieves this, and then try to implement the same functionality in kpm.

If you can find the apis used by oras, using those apis directly in kpm to implement the same functionality will make it very easy to solve this problem. 😊😊😊

[Vanshikav123]

Hi @Vanshikav123 😃

Welcome! You can begin with this task.

Remove the http/https switch and adjust oci access layer in kpm to support http/https non-awareness

I provide some more detailed information. Currently, kpm supports OCI Registries with URLs beginning with either 'https' or 'http' protocols.

• More details about 'kpm oci registry supports' - https://www.kcl-lang.io/docs/user_docs/guides/package-management/how-to/kpm_oci

kpm requires the environment variable OCI_REG_PLAIN_HTTP to be set, or you can adjust the field DefaultOciPlainHttp in kpm configuration file ~/.kcl/kpm/.kpm/config/kpm.json for its setup. Both OCI_REG_PLAIN_HTTP and DefaultOciPlainHttp influence the value of a switch variable within kpm.

• The switch variable is here:

  kpm/pkg/oci/oci.go

  Line 118 in bb39f68

  repo.PlainHTTP = settings.DefaultOciPlainHttp()

The state of this switch variable restricts kpm to effect only one protocol at a time—either https or http. This is quite detrimental to the user experience. It makes the user feel very confused. Users should not need to manually control this switch; kpm should support both http and https starting OCI registry urls without a switch control.

kpm utilizes the third-party library oras-go to implement the oci registry supports. I have noticed that oras is capable of working with OCI registry URLs starting with 'http' or 'https'.

• oras is https://github.com/oras-project/oras
• oras-go is https://github.com/oras-project/oras-go

Therefore, you could begin by research how the ORAS tool achieves this, and then try to implement the same functionality in kpm.

If you can find the apis used by oras, using those apis directly in kpm to implement the same functionality will make it very easy to solve this problem. 😊😊😊

Thanks for providing me with the references will come up with a solution soon !

[Peefy]

Can git://github.com be simplified to github.com and git://github.com is also allowed. Ref kubectl apply