From 635b4f35134d234b05f4a054e4a578e65f903a1e Mon Sep 17 00:00:00 2001 From: changzhen Date: Fri, 8 Mar 2024 15:53:10 +0800 Subject: [PATCH] add checklist for adding new API Signed-off-by: changzhen --- docs/developers/add-new-api.md | 51 +++++++++++++++++ .../current/developers/add-new-api.md | 55 +++++++++++++++++++ sidebars.js | 3 +- 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/developers/add-new-api.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/developers/add-new-api.md diff --git a/docs/developers/add-new-api.md b/docs/developers/add-new-api.md new file mode 100644 index 00000000..e5e08798 --- /dev/null +++ b/docs/developers/add-new-api.md @@ -0,0 +1,51 @@ +--- +title: Add new API +--- + +This article is a checklist. When you add an API, you need to check whether the following items are updated simultaneously. + +After modifying any of the following check items, or waiting for all modification items to be modified, you can execute the `make update` command to automatically generate the files, then submit these files to the [Karmada repo](https://github.com/karmada-io/karmada). + +## Update codegen + +Codegen contains many automatic code generation tools, including `deepcopy-gen`, `register-gen`, `conversion-gen`, `client-gen`, `lister-gen`, `informer-gen`, `openapi-gen`. You can set the above code generation configuration for the newly added API in the file `hack/update-codegen.sh`. + +## Update crdgen + +To generate CRD Yaml files for the added APIs using the controller-gen, set the configuration in the file `hack/update-crdgen.sh`. + +## Update import aliases + +To unify the format when importing APIs package name, Karmada defines the import aliases of different API packages in file `.import-aliases`. You can check whether you need to modify it. + +## CRD install + +To ensure that the new API can be installed correctly, you can modify the configuration of the following files: + +- charts/karmada/_crds/kustomization.yaml + +## Helm install + +If the new API is located in a new group, you can modify the following files and add corresponding configurations for the new API to ensure that helm is installed correctly: + +- charts/karmada/templates/post-delete-job.yaml +- charts/karmada/templates/post-install-job.yaml +- charts/karmada/templates/pre-install-job.yaml + +## Update Karmada schema + +To correctly discover the new API during the client call, you can check whether you need to modify the configuration of the following files: + +- pkg/util/gclient/gclient.go + +## Update swagger json + +To include the new API in [Karmada's API](https://karmada.io/docs/category/karmada-api), you need to modify the `hack/tools/swagger/generateswagger.go` file so that the new API can be generated in the `api/openapi-spec/swagger.json` file. + +## Update SkippedResourceConfig + +In the process of resource propagation, Karmada will filter out Karmada's own CRD resources. The code logic is here: + +https://github.com/karmada-io/karmada/blob/9ccc8be46c135005289367b8867f4b2c82ca44c0/pkg/util/apigroup.go#L59-L66 + +You can check if the code needs to be updated. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/developers/add-new-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/developers/add-new-api.md new file mode 100644 index 00000000..27933feb --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/developers/add-new-api.md @@ -0,0 +1,55 @@ +--- +title: 新增 API +--- + +本文是一个检查列表，当您在 Karmada 仓库中新增一个 API 时，您需要检查以下检查项是否需要同步更新。 + +修改以下任一检查项或等待所有修改项修改完成后，请执行 `make update` 命令来自动生成文件，然后将这些文件一并提交到 Karmada 仓库中。 + +## 更新 codegen + +codegen 包含许多代码自动生成工具，包括：`deepcopy-gen`，`register-gen`，`conversion-gen`，`client-gen`，`lister-gen`，`informer-gen`，`openapi-gen`。您可以在文件 `hack/update-codegen.sh` 中为新增的 API 配置代码生成器。 + +## 更新 crdgen + +使用 controller-gen 为新增的 API 生成 CRD Yaml 文件，您可以在文件 `hack/update-crdgen.sh` 中配置。 + +## 更新 import 别名 + +为了统一导入 API 包名时的格式，Karmada 在文件 `.import-aliases` 中定义了不同 API 包的导入别名，您可以检查下是否需要修改。 + +## CRD 安装 + +为确保正确安装新增的 API，您可以修改以下文件的配置： + +- charts/karmada/_crds/kustomization.yaml + +## Helm 安装 + +If the new API is located in a new group, please modify the following files and add corresponding configurations for the new API to ensure that helm is installed correctly: + +如果新增的 API 位于新的 group 中，您可以修改以下文件并为新的 API 添加相应的配置，以确保正确安装 helm： + +- charts/karmada/templates/post-delete-job.yaml +- charts/karmada/templates/post-install-job.yaml +- charts/karmada/templates/pre-install-job.yaml + +## 更新 Karmada schema + +为了在客户端调用时正确发现新增的 API，您可以检查下是否需要修改以下文件的配置： + +- pkg/util/gclient/gclient.go + +## 更新 swagger json + +为了在 [Karmada's API](https://karmada.io/docs/category/karmada-api) 中找到新增的 API，您需要修改 `hack/tools/swagger/generateswagger.go` 文件，以便在 `api/openapi-spec/swagger.json` 文件中生成新的 API。 + +## 更新 SkippedResourceConfig + +In the process of resource propagation, Karmada will filter out Karmada's own CRD resources. The code logic is here: + +在资源分发的过程中，Karmada 会过滤掉 Karmada 自身的 CRD 资源，相关代码逻辑： + +https://github.com/karmada-io/karmada/blob/9ccc8be46c135005289367b8867f4b2c82ca44c0/pkg/util/apigroup.go#L59-L66 + +你可以检查下是否需要更新代码。 diff --git a/sidebars.js b/sidebars.js index 447e58b7..43818554 100644 --- a/sidebars.js +++ b/sidebars.js @@ -222,7 +222,8 @@ module.exports = { "developers/performance-test-setup-for-karmada", "developers/releasing", "developers/customize-karmada-scheduler", - "developers/document-releasing" + "developers/document-releasing", + "developers/add-new-api" ], }, {