Merge pull request #199 from Peefy/publish-kubernetes-module-guide

Peefy · web-flow · commit f226288a10ec · 2023-11-02T21:53:23.000+08:00
docs: add kubernetes module publish docs
diff --git a/docs/user_docs/guides/working-with-k8s/4-publish-modules.md b/docs/user_docs/guides/working-with-k8s/4-publish-modules.md
@@ -0,0 +1,95 @@
+---
+title: "Publish Kubernetes Modules"
+sidebar_position: 4
+---
+
+## Introduction
+
+The community KCL module registry is located at [Artifact Hub](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1) and welcomes participation at the [GitHub repository](https://github.com/kcl-lang/artifacthub) using pull requests. This section explains how to publish Kubernetes modules and work with the module registry.
+
+> NOTE: If you want to publish your KCL modules to the `kcl-lang` official registry, then the source code of your KCL modules will be saved in this repo, you need to submit the source code of your module to this repository via PRs. But KCL also makes it possible to create and run your own kcl module registry such as OCI registries e.g., Docker Hub, Github Packages and Harbor, etc.
+
+> NOTE: The KCL module does not limit your configuration or policy code content. It can be a workload configuration for applications like Helm Chart, or it can be a Kubernetes validation code or a general code library. However, we strongly recommend that you provide a brief introduction and usage of a kcl module in the documentation.
+
+## Prerequisite
+
++ Install [kcl](https://kcl-lang.io/docs/user_docs/getting-started/install/)
+
+## Quick Start
+
+### Publish KCL module by PR
+
+#### 1. Fork and Clone the code repository
+
+First, you need to clone the repository
+
+```
+git clone https://github.com/{your_github_id}/artifacthub --depth=1
+```
+
+#### 2. Create a branch for your module
+
+We recommend that your branch name be: `publish-pkg-<pkg_name>`, `<pkg_name>` is the name of your module.
+
+Take the module `helloworld` as an example
+
+Enter the artifacthub directory you downloaded
+
+```shell
+cd artifacthub
+```
+
+Create a branch `publish-pkg-helloworld` for the module `helloworld`
+
+```shell
+git checkout -b publish-pkg-helloworld
+```
+
+#### 3. Add your KCL module
+
+You need to move your module to the current directory. In our example, we use the `kcl mod init` command to create the module `helloworld`
+
+```shell
+kcl mod init helloworld
+```
+
+You can add a `README.md` file to the root directory of the module to display on the homepage of AH.
+
+```shell
+echo "## Introduction" >> helloworld/README.md
+echo "This is a kcl module named helloworld." >> helloworld/README.md
+```
+
+Generate reference documents for your module (optional).
+
+```shell
+kcl doc generate
+```
+
+#### 4. Commit your module
+
+You can use the following command to commit your module
+
+Use `git add .` command to add your module to the staging area of git
+
+```shell
+git add .
+```
+
+Use `git commit -s` command to commit your module, we recommend that your commit message follow the format "publish module <pkg_name>".
+
+```shell
+git commit -m "publish module helloworld" -s
+```
+
+Use `git push` command to submit your module to your branch `publish-pkg-<pkg_name>`
+
+```shell
+git push
+```
+
+#### 5. Submit a PR
+
+Finally, you need to submit a PR to the main branch of the repository with your branch `publish-pkg-<pkg_name>`.
+
+- [How to create PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
diff --git a/docs/user_docs/guides/working-with-k8s/_4-publish-modules.md b/docs/user_docs/guides/working-with-k8s/_4-publish-modules.md
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/working-with-k8s/4-publish-modules.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/working-with-k8s/4-publish-modules.md
@@ -0,0 +1,91 @@
+---
+title: "发布 Kubernetes 模块"
+sidebar_position: 4
+---
+
+## 简介
+
+社区官方的 KCL 模块 Registry 位于 [Artifact Hub](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1)，欢迎通过在 [GitHub 仓库](https://github.com/kcl-lang/artifacthub) 提交 pull requests 参与共建。本部分介绍如何发布 Kubernetes 模块并使用模块 Registry。
+
+> 注意：如果您想将您的 KCL 模块发布到 `kcl-lang` 官方 Registry 中，则您的 KCL 模块的源代码将需要保存在上述存储库中。但是，KCL 允许接入三方的 Registry，例如各种 OCI Registry，如Docker Hub、Github Packages 和 Harbor 等。只需通过 `kcl registry login` 命令登录到对应的 Registry 即可。
+
+> 注意：KCL 模块不会限制模块中配置或策略代码的具体内容。它可以是一个与 Kubernetes Helm Chart 类似的用于发布的应用程序工作负载配置，也可以是一段策略代码用于校验 Kubernetes 配置或者使用 CRD 转换而来的 KCL Schema。但是，我们强烈建议您在文档中提供有关 KCL 模块的简要介绍文档和具体用法。
+
+## 先决条件
+
++ 安装 [kcl](https://kcl-lang.io/docs/user_docs/getting-started/install/)
+
+## 快速入门
+
+### 通过 GitHub PR 发布 KCL 模块
+
+#### 1. Fork 并克隆代码存储库
+
+```shell
+git clone https://github.com/{your_github_id}/artifacthub --depth=1
+```
+
+#### 2. 创建分支
+
+我们建议您的分支名称为：`publish-pkg-<pkg_name>`，`<pkg_name>` 是您的 KCL 模块的称。以模块 helloworld 为例
+
+进入您下载的 artifacthub 目录
+
+```shell
+cd artifacthub
+```
+
+为模块 `helloworld` 创建一个名为 `publish-pkg-helloworld` 的分支
+
+```shell
+git checkout -b publish-pkg-helloworld
+```
+
+#### 3. 添加您的 KCL 模块
+
+在我们的示例中，使用 `kcl mod init` 命令创建模块 `helloworld`
+
+```shell
+kcl mod init helloworld
+```
+
+您可以在模块的根目录添加一个 `README.md` 文件，以在 Artifact Hub 的模块主页上显示。
+
+```shell
+echo "## Introduction" >> helloworld/README.md
+echo "This is a kcl module named helloworld." >> helloworld/README.md
+```
+
+为模块生成参考文档（可选）
+
+```shell
+kcl doc generate
+```
+
+#### 4. 提交代码
+
+您可以使用以下命令提交您的模块
+
+使用 `git add .` 命令将您的模块添加到git的暂存区
+
+```shell
+git add .
+```
+
+使用 `git commit -s` 命令提交您的模块，我们建议您的提交消息遵循格式 `"publish module <pkg_name>"`。
+
+```shell
+git commit -m "publish module helloworld" -s
+```
+
+提交分支
+
+```shell
+git push
+```
+
+#### 5. 提交 PR
+
+最后，您需要提交一个 PR 到存储库的主分支，包括您的分支 `publish-pkg-<pkg_name>`。
+
+- [如何创建 PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/working-with-k8s/_4-publish-modules.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/working-with-k8s/_4-publish-modules.md
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/working-with-k8s/4-publish-modules.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/working-with-k8s/4-publish-modules.md
@@ -0,0 +1,91 @@
+---
+title: "发布 Kubernetes 模块"
+sidebar_position: 4
+---
+
+## 简介
+
+社区官方的 KCL 模块 Registry 位于 [Artifact Hub](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1)，欢迎通过在 [GitHub 仓库](https://github.com/kcl-lang/artifacthub) 提交 pull requests 参与共建。本部分介绍如何发布 Kubernetes 模块并使用模块 Registry。
+
+> 注意：如果您想将您的 KCL 模块发布到 `kcl-lang` 官方 Registry 中，则您的 KCL 模块的源代码将需要保存在上述存储库中。但是，KCL 允许接入三方的 Registry，例如各种 OCI Registry，如Docker Hub、Github Packages 和 Harbor 等。只需通过 `kcl registry login` 命令登录到对应的 Registry 即可。
+
+> 注意：KCL 模块不会限制模块中配置或策略代码的具体内容。它可以是一个与 Kubernetes Helm Chart 类似的用于发布的应用程序工作负载配置，也可以是一段策略代码用于校验 Kubernetes 配置或者使用 CRD 转换而来的 KCL Schema。但是，我们强烈建议您在文档中提供有关 KCL 模块的简要介绍文档和具体用法。
+
+## 先决条件
+
++ 安装 [kcl](https://kcl-lang.io/docs/user_docs/getting-started/install/)
+
+## 快速入门
+
+### 通过 GitHub PR 发布 KCL 模块
+
+#### 1. Fork 并克隆代码存储库
+
+```shell
+git clone https://github.com/{your_github_id}/artifacthub --depth=1
+```
+
+#### 2. 创建分支
+
+我们建议您的分支名称为：`publish-pkg-<pkg_name>`，`<pkg_name>` 是您的 KCL 模块的称。以模块 helloworld 为例
+
+进入您下载的 artifacthub 目录
+
+```shell
+cd artifacthub
+```
+
+为模块 `helloworld` 创建一个名为 `publish-pkg-helloworld` 的分支
+
+```shell
+git checkout -b publish-pkg-helloworld
+```
+
+#### 3. 添加您的 KCL 模块
+
+在我们的示例中，使用 `kcl mod init` 命令创建模块 `helloworld`
+
+```shell
+kcl mod init helloworld
+```
+
+您可以在模块的根目录添加一个 `README.md` 文件，以在 Artifact Hub 的模块主页上显示。
+
+```shell
+echo "## Introduction" >> helloworld/README.md
+echo "This is a kcl module named helloworld." >> helloworld/README.md
+```
+
+为模块生成参考文档（可选）
+
+```shell
+kcl doc generate
+```
+
+#### 4. 提交代码
+
+您可以使用以下命令提交您的模块
+
+使用 `git add .` 命令将您的模块添加到git的暂存区
+
+```shell
+git add .
+```
+
+使用 `git commit -s` 命令提交您的模块，我们建议您的提交消息遵循格式 `"publish module <pkg_name>"`。
+
+```shell
+git commit -m "publish module helloworld" -s
+```
+
+提交分支
+
+```shell
+git push
+```
+
+#### 5. 提交 PR
+
+最后，您需要提交一个 PR 到存储库的主分支，包括您的分支 `publish-pkg-<pkg_name>`。
+
+- [如何创建 PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
diff --git a/versioned_docs/version-0.7.0/user_docs/guides/working-with-k8s/4-publish-modules.md b/versioned_docs/version-0.7.0/user_docs/guides/working-with-k8s/4-publish-modules.md
@@ -0,0 +1,95 @@
+---
+title: "Publish Kubernetes Modules"
+sidebar_position: 4
+---
+
+## Introduction
+
+The community KCL module registry is located at [Artifact Hub](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1) and welcomes participation at the [GitHub repository](https://github.com/kcl-lang/artifacthub) using pull requests. This section explains how to publish Kubernetes modules and work with the module registry.
+
+> NOTE: If you want to publish your KCL modules to the `kcl-lang` official registry, then the source code of your KCL modules will be saved in this repo, you need to submit the source code of your module to this repository via PRs. But KCL also makes it possible to create and run your own kcl module registry such as OCI registries e.g., Docker Hub, Github Packages and Harbor, etc.
+
+> NOTE: The KCL module does not limit your configuration or policy code content. It can be a workload configuration for applications like Helm Chart, or it can be a Kubernetes validation code or a general code library. However, we strongly recommend that you provide a brief introduction and usage of a kcl module in the documentation.
+
+## Prerequisite
+
++ Install [kcl](https://kcl-lang.io/docs/user_docs/getting-started/install/)
+
+## Quick Start
+
+### Publish KCL module by PR
+
+#### 1. Fork and Clone the code repository
+
+First, you need to clone the repository
+
+```
+git clone https://github.com/{your_github_id}/artifacthub --depth=1
+```
+
+#### 2. Create a branch for your module
+
+We recommend that your branch name be: `publish-pkg-<pkg_name>`, `<pkg_name>` is the name of your module.
+
+Take the module `helloworld` as an example
+
+Enter the artifacthub directory you downloaded
+
+```shell
+cd artifacthub
+```
+
+Create a branch `publish-pkg-helloworld` for the module `helloworld`
+
+```shell
+git checkout -b publish-pkg-helloworld
+```
+
+#### 3. Add your KCL module
+
+You need to move your module to the current directory. In our example, we use the `kcl mod init` command to create the module `helloworld`
+
+```shell
+kcl mod init helloworld
+```
+
+You can add a `README.md` file to the root directory of the module to display on the homepage of AH.
+
+```shell
+echo "## Introduction" >> helloworld/README.md
+echo "This is a kcl module named helloworld." >> helloworld/README.md
+```
+
+Generate reference documents for your module (optional).
+
+```shell
+kcl doc generate
+```
+
+#### 4. Commit your module
+
+You can use the following command to commit your module
+
+Use `git add .` command to add your module to the staging area of git
+
+```shell
+git add .
+```
+
+Use `git commit -s` command to commit your module, we recommend that your commit message follow the format "publish module <pkg_name>".
+
+```shell
+git commit -m "publish module helloworld" -s
+```
+
+Use `git push` command to submit your module to your branch `publish-pkg-<pkg_name>`
+
+```shell
+git push
+```
+
+#### 5. Submit a PR
+
+Finally, you need to submit a PR to the main branch of the repository with your branch `publish-pkg-<pkg_name>`.
+
+- [How to create PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
