From 0b6fa86c088c9185b05af83ef9d607e81b88a96c Mon Sep 17 00:00:00 2001 From: Jianbo Sun Date: Wed, 29 Jun 2022 11:12:35 +0800 Subject: [PATCH] refine docs for developer guide (#816) * refine docs for developer guide Signed-off-by: Jianbo Sun * update zh docs to fix link Signed-off-by: Jianbo Sun --- ...022-06-27-terraform-integrate-with-vela.md | 6 +- docs/contributor/cli-ref-doc.md | 7 +- docs/contributor/overview.md | 43 +- .../addon/addon-registry.md | 7 - .../current.json | 8 +- .../current/contributor/cli-ref-doc.md | 36 ++ .../current/contributor/code-contribute.md | 389 ++++++++++++++++++ .../current/contributor/overview.md | 53 +-- .../addon/addon-registry.md | 74 ++++ .../version-v1.4.json | 8 +- .../version-v1.4/contributor/cli-ref-doc.md | 36 ++ .../contributor/code-contribute.md | 389 ++++++++++++++++++ .../version-v1.4/contributor/overview.md | 53 +-- .../version-v1.4/end-user/version-control.md | 2 +- .../component-dependency-parameter.md | 2 +- .../end-user/workflow/overview.md | 4 +- .../version-v1.4/end-user/workflow/suspend.md | 2 +- .../version-v1.4/end-user/workflow/timeout.md | 2 +- .../end-user/workflow/webhook-notification.md | 76 +--- .../application/create-application.md | 28 +- .../addon/addon-registry.md | 74 ++++ .../version-v1.4/tutorials/workflows.md | 51 +-- sidebars.js | 51 +-- .../version-v1.4/contributor/cli-ref-doc.md | 7 +- .../version-v1.4/contributor/overview.md | 43 +- .../end-user/workflow/overview.md | 2 - .../addon/addon-registry.md | 7 - versioned_sidebars/version-v1.4-sidebars.json | 53 +-- 28 files changed, 1216 insertions(+), 297 deletions(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/contributor/cli-ref-doc.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/contributor/code-contribute.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/addon/addon-registry.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/cli-ref-doc.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/code-contribute.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-v1.4/platform-engineers/addon/addon-registry.md diff --git a/blog/2022-06-27-terraform-integrate-with-vela.md b/blog/2022-06-27-terraform-integrate-with-vela.md index 6838ff63..a91259aa 100644 --- a/blog/2022-06-27-terraform-integrate-with-vela.md +++ b/blog/2022-06-27-terraform-integrate-with-vela.md @@ -100,7 +100,7 @@ We'll use the terraform module we have already prepared just now. * Generate Component Definition ``` -vela def init ecs --type component --provider alibaba --desc "Terraform configuration for Alibaba Cloud Elastic Compute Service" --git https://github.com/wonderflow/terraform-alicloud-ecs-instance.git > alibaa-ecs.yaml +vela def init ecs --type component --provider alibaba --desc "Terraform configuration for Alibaba Cloud Elastic Compute Service" --git https://github.com/wonderflow/terraform-alicloud-ecs-instance.git > alibaba-ecs-def.yaml ``` > Change the git url with your own if you have customized. @@ -108,7 +108,7 @@ vela def init ecs --type component --provider alibaba --desc "Terraform configur * Apply it to the vela control plane ``` -vela kube apply -f alibaa-ecs-def.yaml +vela kube apply -f alibaba-ecs-def.yaml ``` > `vela kube apply` works the same with `kubectl apply`. @@ -291,7 +291,7 @@ EOF In this case, we specify the `local_ip` by `velaux.vela-system`, which means we're visiting the Kubernetes Service with name `velaux` in the namespace `vela-system`. -As a result, you can visit velaux service from the public IP `121.196.106.174:8083`. +As a result, you can visit [velaux](https://kubevela.io/docs/reference/addons/velaux) service from the public IP `121.196.106.174:8083`. 2. Compose two components together for the same lifecycle. diff --git a/docs/contributor/cli-ref-doc.md b/docs/contributor/cli-ref-doc.md index 3764c055..f8f2fd8b 100644 --- a/docs/contributor/cli-ref-doc.md +++ b/docs/contributor/cli-ref-doc.md @@ -1,4 +1,9 @@ -# Update KubeVela.io CLI Reference Doc +--- +title: Update CLI Reference +--- + +This guide introduce how to update [CLI reference doc](../cli/vela) in the website. +The whole process was done by script automatically. You need to follow this guide to build your environment. 1. step up these two projects in the same folder. diff --git a/docs/contributor/overview.md b/docs/contributor/overview.md index f6f0e7ef..bb00fd91 100644 --- a/docs/contributor/overview.md +++ b/docs/contributor/overview.md @@ -4,8 +4,28 @@ title: Overview The developer guide including two parts: -1. The first part is [contribution guide](#contribution-guide) that introduces how to participate and contribute to the community. -2. The second part is [extension guide](#extension-guide) that introduces how to extend KubeVela, you are also very welcome to contribute your extension to the community. +1. The first part is [extension guide](#extension-guide) that introduces how to extend KubeVela, you are also very welcome to contribute your extension to the community. +2. The second part is [contribution guide](#contribution-guide) that introduces how to participate and contribute to the community. + +## Extension Guide + +This part is a guide to help you extend capabilities for KubeVela. Make sure you have already understand the [**core concepts**](../getting-started/core-concept) before you start. + +### Extend Addons + +Building or installing addons is the most important way to extend KubeVela, there's a growing [catalog](https://github.com/kubevela/catalog) of addons you can choose for installation. You can also share your platform extension by KubeVela addon registry. + +* [Build Your Own Addon](../platform-engineers/addon/intro). +* [Build Your Addon Registry](../platform-engineers/addon/addon-registry). +* [Extend Cloud Resources by Addon](../platform-engineers/addon/terraform). + +### Learn CUE to extend more powerful features + +KubeVela use CUE as it's core engine, and you can use CUE and CRD controller to glue almost every infrastructure capabilities. +As a result, you can extend more powerful features for your platform. + +- Start to [Learn CUE in KubeVela](../platform-engineers/cue/basic). +- Learn what is [CRD Controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in Kubernetes. ## Contribution Guide @@ -50,23 +70,4 @@ If you're interested to become a community member or learn more about the govern * [VelaUX Developer Guide](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md) * [Terraform Controller Developer Guide](https://github.com/oam-dev/terraform-controller/blob/master/CONTRIBUTING.md) - -## Extension Guide - -This part is a guide to help you extend capabilities for KubeVela. Make sure you have already understand the [**core concepts**](../getting-started/core-concept) before you start. - -### Learn CUE with KubeVela - -KubeVela use CUE as it's core engine, and you can use CUE and CRD controller to glue almost every infrastructure capabilities. - -- [Learn CUE in KubeVela](../platform-engineers/cue/basic) -- Learn what is [CRD Controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in Kubernetes - -### Extend Addons - -Building or installing addons is the most important way to extend KubeVela, there's a growing [catalog](https://github.com/kubevela/catalog) of addons you can choose for installation. - -* [Build Your Own Addon](../platform-engineers/addon/intro) -* [Extend Cloud Resources by Addon](../platform-engineers/addon/terraform) - Enjoy coding and collaboration in OSS world! diff --git a/docs/platform-engineers/addon/addon-registry.md b/docs/platform-engineers/addon/addon-registry.md index e55f7457..9c1de827 100644 --- a/docs/platform-engineers/addon/addon-registry.md +++ b/docs/platform-engineers/addon/addon-registry.md @@ -72,10 +72,3 @@ vela addon registry add my-repo --type helm --endpoint= --username= + Install Kubebuilder manually + +linux: + +``` +wget https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.21.2-linux-amd64.tar.gz +tar -zxvf kubebuilder-tools-1.21.2-linux-amd64.tar.gz +mkdir -p /usr/local/kubebuilder/bin +sudo mv kubebuilder/bin/* /usr/local/kubebuilder/bin +``` + +macOS: + +``` +wget https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.21.2-darwin-amd64.tar.gz +tar -zxvf kubebuilder-tools-1.21.2-darwin-amd64.tar.gz +mkdir -p /usr/local/kubebuilder/bin +sudo mv kubebuilder/bin/* /usr/local/kubebuilder/bin +``` + +For other OS or system architecture, please refer to https://storage.googleapis.com/kubebuilder-tools/ + + + +You may also be interested with KubeVela's [design](https://github.com/oam-dev/kubevela/tree/master/design/vela-core) before diving into its code. + +### Build + +- Clone this project + +```shell script +git clone git@github.com:oam-dev/kubevela.git +``` + +KubeVela includes two parts, `vela core` and `vela cli`. + +- The `vela core` is actually a K8s controller, it will watch OAM Spec CRD and deploy resources. +- The `vela cli` is a command line tool that can build, run apps(with the help of `vela core`). + +For local development, we probably need to build both of them. + +- Build Vela CLI + +```shell script +make +``` + +After the vela cli built successfully, `make` command will create `vela` binary to `bin/` under the project. + +- Configure `vela` binary to System PATH + +```shell script +export PATH=$PATH:/your/path/to/project/kubevela/bin +``` + +Then you can use `vela` command directly. + +- Build Vela Core + +```shell script +make manager +``` + +- Run Vela Core + +Firstly make sure your cluster has CRDs, below is the command that can help install all CRDs. + +```shell script +make core-install +``` + +To ensure you have created vela-system namespace and install definitions of necessary module. +you can run the command: + +```shell script +make def-install +``` + +And then run locally: + +```shell script +make core-run +``` + +This command will run controller locally, it will use your local KubeConfig which means you need to have a k8s cluster +locally. If you don't have a one, we suggest that you could setup up a cluster with [kind](https://kind.sigs.k8s.io/). + +When you're developing `vela-core`, make sure the controller installed by helm chart is not running. +Otherwise, it will conflict with your local running controller. + +You can check and uninstall it by using helm. + +```shell script +helm list -A +helm uninstall -n vela-system kubevela +``` + +### Testing + +It's necessary to write tests for good code quality, please refer to [the principle of test](./principle-of-test) before you start. + +#### Unit test + +```shell script +make test +``` + +To execute the unit test of the API module, the mongodb service needs to exist locally. + +```shell script +make unit-test-apiserver +``` + +#### Integration and E2E test + +**Before e2e test start, make sure you have vela-core running.** + +```shell script +make core-run +``` + +Start to test. + +```shell script +make e2e-test +``` + +### Debugging Locally with Remote KubeVela Environment + +To run vela-core locally for debugging with kubevela installed in the remote cluster: +- Firstly, scaling the replicas of `kubevela-vela-core` to 0 for leader election of `controller-manager`: + ```shell + kubectl scale deploy -n vela-system kubevela-vela-core --replicas=0 + ``` +- Secondly, removing the `WebhookConfiguration`, otherwise an error will be reported when applying your application using `vela-cli` or `kubectl`: + ```shell + kubectl delete ValidatingWebhookConfiguration kubevela-vela-core-admission -n vela-system + kubectl delete MutatingWebhookConfiguration kubevela-vela-core-admission -n vela-system + ``` + +Finally, you can use the commands in the above [Build](#build) and [Testing](#Testing) sections, such as `make run`, to code and debug in your local machine. + +> Note you will not be able to test features relate with validating/mutating webhooks in this way. + +## Run VelaUX Locally + +VelaUX is the UI console of KubeVela, it's also an addon including apiserver code in `kubevela` repo and the frontend code in `velaux` repo. + +Before start, please make sure you have already started the vela controller environment in kubevela repo directory. + +```shell +make run-apiserver +``` + +By default, the apiserver will serving at "0.0.0.0:8000". + +Get the VelaUX code by: + +```shell +git clone git@github.com:kubevela/velaux.git +``` + +Configure the apiserver address: + +```shell +cd velaux +echo "BASE_DOMAIN='http://127.0.0.1:8000'" > .env +``` + +Make sure you have installed [yarn](https://classic.yarnpkg.com/en/docs/install). + +```shell +yarn install +yarn start +``` + +To execute the e2e test of the API module, the mongodb service needs to exist locally. + +```shell script +# save your config +mv ~/.kube/config ~/.kube/config.save + +kind create cluster --image kindest/node:v1.20.7@sha256:688fba5ce6b825be62a7c7fe1415b35da2bdfbb5a69227c499ea4cc0008661ca --name worker +kind get kubeconfig --name worker --internal > /tmp/worker.kubeconfig +kind get kubeconfig --name worker > /tmp/worker.client.kubeconfig + +# restore your config +mv ~/.kube/config.save ~/.kube/config + +make e2e-apiserver-test +``` + +## Create a pull request + +We're excited that you're considering making a contribution to the KubeVela project! +This document guides you through the process of creating a [pull request](https://help.github.com/en/articles/about-pull-requests/). + +### Before you begin + +We know you're excited to create your first pull request. Before we get started, make sure your code follows the relevant [code conventions](./code-conventions). + +### Your first pull request + +Before you submit a PR, run this command to ensure it is ready: +``` +make reviewable +``` + +If this is your first time contributing to an open-source project on GitHub, make sure you read about [Creating a pull request](https://help.github.com/en/articles/creating-a-pull-request). + +To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines: + +- Title and description matches the implementation. +- Commits within the pull request follow the [Formatting guidelines](#Formatting-guidelines). +- The pull request closes one related issue. +- The pull request contains necessary tests that verify the intended behavior. +- If your pull request has conflicts, rebase your branch onto the main branch. + +If the pull request fixes a bug: + +- The pull request description must include `Closes #` or `Fixes #`. +- To avoid regressions, the pull request should include tests that replicate the fixed bug. +- Generally, we will maintain the last 2 releases for bugfix. You should add `backport release-x.x` label or comment `/backport release-x.y` for the releases contained the bug, github bot will automatically backport this PR to the specified release branch after PR merged. If there're any conflicts, you should cherry-pick it manually. + +## Code review + +Once you've created a pull request, the next step is to have someone review your change. +A review is a learning opportunity for both the reviewer and the author of the pull request. + +If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment. +Tag a user by typing the `@` symbol followed by their GitHub username. + +We recommend that you read [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) to learn more about code reviews. + +## Formatting guidelines + +A well-written pull request minimizes the time to get your change accepted. +These guidelines help you write good commit messages and descriptions for your pull requests. + +### Commit message format + +KubeVela follows the [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/) and [commit messages best practices](https://chris.beams.io/posts/git-commit/) to improve better history information. + +The commit message should be structured as follows: + +``` +[optional scope]: + +[optional body] +``` + +#### Examples: + +Commit message with scope: + +``` +Feat(lang): add polish language +``` + +Commit message with no body: + +``` +Docs: correct spelling of CHANGELOG +``` + +Commit message with multi-paragraph body: + +``` +Fix: correct minor typos in code + +see the issue for details + +on typos fixed. + +Reviewed-by: Z +Refs #133 +``` + +#### `` (required) + +Type is required to better capture the area of the commit, based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). + +We capitalize the `` to make sure the subject line is capitalized. `` can be one of the following: + +* **Feat**: A new feature +* **Fix**: A bug fix +* **Docs**: Documentation only changes +* **Build**: Changes that affect the build system or external dependencies +* **Style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +* **Refactor**: A code change that neither fixes a bug nor adds a feature +* **Perf**: A code change that improves performance +* **Test**: Adding missing or correcting existing tests +* **Chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation + +#### `` (optional) + +Scope is optional, it may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, it is could be anything specifying place of the commit change. Github issue link is +also a valid scope. For example: Fix(cli), Feat(api), Fix(#233), etc. + +You can use `*` when the change affects more than a single scope. + +#### `` (required) + +The subject MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., "Fix: array parsing issue when multiple spaces were contained in string", instead of "Fix: bug". + +#### `` (optional) + +A longer commit body may be provided after the short subject, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. + +#### Area + +The area should use upper camel case, e.g. UpperCamelCase. + +Prefer using one of the following areas: + +- **Application:** Changes to the application controller. +- **Component:** Changes to the component related code or definition controller. +- **Trait:** Changes to the trait related code or definition controller. +- **CUE:** Changes to the CUE related logic. +- **Docs:** Changes to documentation. + +**Examples** + +- `Application: Support workflow in application controller` +- `CUE: Fix patch parse issues` +- `Docs: Changed url to URL in all documentation files` + +### Pull request titles + +The KubeVela team _squashes_ all commits into one when we accept a pull request. +The title of the pull request becomes the subject line of the squashed commit message. +We still encourage contributors to write informative commit messages, as they become a part of the Git commit body. + +We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible. + +Make sure that the title for your pull request uses the same format as the subject line in the commit message. If the format is not followed, we will add a label `title-needs-formatting` on the pull request. + +### Pass all the CI checks + +Before merge, All test CI should pass green. +- The `codecov/project` should also pass. This means the coverage should not drop. Currently, the coverage of the Pull Request should have at least 70%. +- KubeVela uses [DCO](https://wiki.linuxfoundation.org/dco) for contributor agreements. It requires you to sign-off every commit before the pull request being merged. + - Git provides a convenient flag `-s` in your commit command to sign-off automatically: + ```shell + git commit -s -m 'This is my commit message' + ``` + - Contributors can also sign-off manually by adding a `Signed-off-by` line to commit messages as the following format, make sure the email matches your github account or the check bot won't pass. + ```shell + This is my commit message + + Signed-off-by: Random Developer + ``` + +## Update the docs & website + +If your pull request merged and this is a new feature or enhancement, it's necessary to update the docs and send a pull request to [kubevela.io](https://github.com/kubevela/kubevela.io) repo. + +Learn how to write the docs by the following guide: + +* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md) +* [Update KubeVela.io CLI Reference Doc](./cli-ref-doc) + +Great, you have complete the lifecycle of code contribution, try to [join the community as a member](https://github.com/kubevela/community/blob/main/community-membership.md) if you're interested. \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contributor/overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/contributor/overview.md index 2ca580e5..74dfa227 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contributor/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/contributor/overview.md @@ -2,11 +2,32 @@ title: 介绍 --- -开发者手册主要包含以下两个部分： -1. 第一部分是[贡献手册](https://kubevela.io/zh/docs/next/contributor/overview#contribution-guide)，介绍如何参与和贡献社区。 -2. 第二部分是[扩展手册](https://kubevela.io/zh/docs/next/contributor/overview#extension-guide)，介绍如何扩展 KubeVela，也非常欢迎你为社区贡献你的扩展。 +开发者手册主要包含以下三个部分： -## 贡献手册 +1. 第一部分是[平台扩展手册](#扩展手册)，介绍扩展 KubeVela 的方法，也非常欢迎你为社区贡献你的扩展。 +2. 第二部分是[贡献指南](#贡献指南)，介绍如何参与和贡献社区，包含了代码和非代码贡献。 + +## 扩展手册 + +这一部分是帮助你扩展 KubeVela 功能的手册。在开始之前确保你已经理解了[核心概念](../getting-started/core-concept)。 + +### 扩展和分发平台插件 + +构建或安装平台插件（Addon）是扩展 KubeVela 平台的基本方式，这里有一个在持续完善的 [catalog](https://github.com/kubevela/catalog)，你可以发现、安装、分享 KubeVela 的平台扩展能力。 + +* [构建你的扩展插件](../platform-engineers/addon/intro)。 +* [制作你的企业级插件仓库](../platform-engineers/addon/addon-registry) +* [制作插件扩展云资源](../platform-engineers/addon/terraform)。 + +### 使用 CUE 扩展高级功能 + +KubeVela 使用 CUE 作为核心引擎，你可以使用 CUE 和 CRD 控制器来粘合绝大部分基础设施功能，扩展更丰富更灵活的高级功能。 + +* 从[学习 CUE](../platform-engineers/cue/basic) 开始。 +* 了解什么是 Kubernetes 中的 [CRD 控制器](https://kubernetes.io/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/)。 + + +## 贡献指南 KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[来自 8 个以上不同组织的贡献者启动](https://github.com/kubevela/community/blob/main/OWNERS.md#bootstrap-contributors)。我们希望 KubeVela 从一开始就有开放的治理方式，所以在项目发布后立即将其捐赠给中立基金会。 @@ -27,7 +48,7 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ 用 Apache 的方式来说“社区胜于代码”。尽管 Kubevela 是 CNCF/Linux 项目，但我们对此具有很强的共鸣。更深入地延续这一点，对于社区的存在及其未来的增长而言，我们认为非编码贡献和代码贡献同样重要。 -* 请参阅[非代码贡献手册](https://kubevela.io/zh/docs/next/contributor/non-code-contribute)，了解你可以提供什么帮助。 +* 请参阅[非代码贡献手册](./non-code-contribute)，了解你可以提供什么帮助。 ### 代码贡献 @@ -35,9 +56,9 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ * [Good first issue](https://github.com/kubevela/kubevela/labels/good%20first%20issue) 通常比较简单。 * [Help wanted](https://github.com/kubevela/kubevela/labels/help%20wanted) 是我们希望社区帮助我们解决的问题，而不关注问题是否复杂。 -* 更多细节请参考[代码贡献手册](https://kubevela.io/zh/docs/next/contributor/code-contribute)。 +* 更多细节请参考[代码贡献手册](./code-contribute)。 -查看[发行过程和节奏](https://kubevela.io/zh/docs/next/contributor/release-process)，以了解你的代码更改何时会发布。 +查看[发行过程和节奏](./release-process)，以了解你的代码更改何时会发布。 ### 成为社区成员 @@ -48,22 +69,4 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ * [VelaUX 开发手册](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md) * [Terraform Controller 开发手册](https://github.com/kubevela/terraform-controller/blob/master/CONTRIBUTING.md) -## 扩展手册 - -这一部分是帮助你扩展 KubeVela 功能的手册。在开始之前确保你已经理解了[核心概念](https://kubevela.io/zh/docs/next/getting-started/core-concept)。 - -### 使用 Kubevela 学习 CUE - -KubeVela 使用 CUE 作为核心引擎，你可以使用 CUE 和 CRD 控制器来粘合绝大部分基础设施功能。 - -* [在 KubeVela 中学习 CUE](https://kubevela.io/zh/docs/next/platform-engineers/cue/basic) -* 了解什么是 Kubernetes 中的 [CRD 控制器](https://kubernetes.io/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/) - -### 扩展 Addons - -构建或安装 addons 是扩展 KubeVela 最重要的方式，这里有一个在持续完善的 [catalog](https://github.com/kubevela/catalog)，你可以查看并选择安装。 - -* [构建自己的 Addon](https://kubevela.io/zh/docs/next/platform-engineers/addon/intro) -* [通过 Addon 扩展云资源](https://kubevela.io/zh/docs/next/platform-engineers/addon/terraform) - 开启并享受你的开源贡献之旅吧！ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/addon/addon-registry.md b/i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/addon/addon-registry.md new file mode 100644 index 00000000..9c1de827 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/platform-engineers/addon/addon-registry.md @@ -0,0 +1,74 @@ +--- +title: Build your Own Registry +--- + +An addon registry can be used for discovering and distributing addons. Currently, KubeVela has supported two type registry: git server and helm repo. + +## Git as registry + +A directory contains some sub-directories stored in git repository can be used as an addon registry. + +The git type registry type has supported github, gitlab and gitee. + +A typical git addon registry is like [catalog](https://github.com/kubevela/catalog/tree/master/addons). You can clone this repo to your local path and then push to your own git repository. + +```yaml +$ git clone https://github.com/kubevela/catalog/tree/master/addons +$ git remote add +$ git push -u master +``` + +If your repository type is github, you can use this command to add your addon registry. + +```yaml +vela addon registry add my-repo --type git --endpoint= --path= --gitToken= +``` + +If your type is gitee, you can use: + +```yaml +vela addon registry add my-repo --type gitee --endpoint= --path= --gitToken= +``` + +If your type is gitlab, you can use: + +```yaml +vela addon registry add my-repo --type gitlab --gitRepoName= --endpoint= --path= --gitToken= +``` + +## Helm chart repository as registry + +A [helm chart repository](https://helm.sh/docs/topics/chart_repository/) can be used to store addon package. + +You can build your own helm repository by following this [tutorial](https://helm.sh/docs/topics/chart_repository/#hosting-chart-repositories). + +If you already have one, you can follow these steps package add push addon to helm repository. + +Package the addon: + +```yaml +$ vela addon package +``` + +Use [helm cli](https://helm.sh/docs/intro/install/#helm) to push addon package which generated by last step to the helm repository. + +```yaml +$ helm plugin install https://github.com/chartmuseum/helm-push +$ helm cm-push +``` + +More info please refer to [chartmuseum docs](https://github.com/chartmuseum/helm-push). + +Then you can add it as addon registry by this command: + +```yaml +vela addon registry add my-repo --type helm --endpoint= +``` + +If your helm repo must be accessed with username and password. You can set them by: + +```yaml +vela addon registry add my-repo --type helm --endpoint= --username= --password= +``` + +A helm repo type registry can store addon's multi-versions of an addon. In the future we will support [chart-museum](https://chartmuseum.com/docs/) addon, and provide an easier way to build your own versioned addon registry. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4.json b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4.json index c88526a8..f87d592b 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4.json +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4.json @@ -163,8 +163,12 @@ "message": "调试指南", "description": "The label for category Debugging in sidebar docs" }, - "sidebar.docs.category.Contribute Extension": { - "message": "贡献平台扩展", + "sidebar.docs.category.Extension": { + "message": "平台扩展", + "description": "平台扩展参考文档" + }, + "sidebar.docs.category.Contribution Guide": { + "message": "贡献指南", "description": "平台扩展参考文档" }, "sidebar.docs.category.Simple Template": { diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/cli-ref-doc.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/cli-ref-doc.md new file mode 100644 index 00000000..f8f2fd8b --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/cli-ref-doc.md @@ -0,0 +1,36 @@ +--- +title: Update CLI Reference +--- + +This guide introduce how to update [CLI reference doc](../cli/vela) in the website. +The whole process was done by script automatically. You need to follow this guide to build your environment. + +1. step up these two projects in the same folder. + +```shell +$ tree -L 1 +. +├── kubevela +└── kubevela.io +``` + +2. Run generate command in kubevela root dir. + +```shell +cd kubevela/ +go run ./hack/docgen/gen.go +``` + +3. Update more docs such as i18n zh + +```shell +$ go run ./hack/docgen/gen.go ../kubevela.io/i18n/zh/docusaurus-plugin-content-docs/current/cli +scanning rootPath of CLI docs for replace: ../kubevela.io/i18n/zh/docusaurus-plugin-content-docs/current/cli +``` + +4. Then you can check the difference in kubevela.io. + +```shell +cd ../kubevela.io +git status +``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/code-contribute.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/code-contribute.md new file mode 100644 index 00000000..db3e232a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/code-contribute.md @@ -0,0 +1,389 @@ +--- +title: Code Contribution Guide +--- + +You will learn the following things in the code contribution guide: + +- [How to Run KubeVela Locally](#run-kubevela-locally) +- [How to Run VelaUX Locally](#run-velaux-locally) +- [How to Create a pull request](#create-a-pull-request) +- [Code Review Guide](#code-review) +- [Formatting guidelines of pull request](#formatting-guidelines) + +## Run KubeVela Locally + +This guide helps you get started developing KubeVela. + +### Prerequisites + +1. Golang version 1.17+ +2. Kubernetes version v1.20+ with `~/.kube/config` configured. +3. ginkgo 1.14.0+ (just for [E2E test](#e2e-test)) +4. golangci-lint 1.38.0+, it will install automatically if you run `make`, you can [install it manually](https://golangci-lint.run/usage/install/#local-installation) if the installation is too slow. +5. kubebuilder v3.1.0+ and you need to manually install the dependency tools for unit test. +6. [CUE binary](https://github.com/cue-lang/cue/releases) v0.3.0+ + +
+ Install Kubebuilder manually + +linux: + +``` +wget https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.21.2-linux-amd64.tar.gz +tar -zxvf kubebuilder-tools-1.21.2-linux-amd64.tar.gz +mkdir -p /usr/local/kubebuilder/bin +sudo mv kubebuilder/bin/* /usr/local/kubebuilder/bin +``` + +macOS: + +``` +wget https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.21.2-darwin-amd64.tar.gz +tar -zxvf kubebuilder-tools-1.21.2-darwin-amd64.tar.gz +mkdir -p /usr/local/kubebuilder/bin +sudo mv kubebuilder/bin/* /usr/local/kubebuilder/bin +``` + +For other OS or system architecture, please refer to https://storage.googleapis.com/kubebuilder-tools/ + +
+ +You may also be interested with KubeVela's [design](https://github.com/oam-dev/kubevela/tree/master/design/vela-core) before diving into its code. + +### Build + +- Clone this project + +```shell script +git clone git@github.com:oam-dev/kubevela.git +``` + +KubeVela includes two parts, `vela core` and `vela cli`. + +- The `vela core` is actually a K8s controller, it will watch OAM Spec CRD and deploy resources. +- The `vela cli` is a command line tool that can build, run apps(with the help of `vela core`). + +For local development, we probably need to build both of them. + +- Build Vela CLI + +```shell script +make +``` + +After the vela cli built successfully, `make` command will create `vela` binary to `bin/` under the project. + +- Configure `vela` binary to System PATH + +```shell script +export PATH=$PATH:/your/path/to/project/kubevela/bin +``` + +Then you can use `vela` command directly. + +- Build Vela Core + +```shell script +make manager +``` + +- Run Vela Core + +Firstly make sure your cluster has CRDs, below is the command that can help install all CRDs. + +```shell script +make core-install +``` + +To ensure you have created vela-system namespace and install definitions of necessary module. +you can run the command: + +```shell script +make def-install +``` + +And then run locally: + +```shell script +make core-run +``` + +This command will run controller locally, it will use your local KubeConfig which means you need to have a k8s cluster +locally. If you don't have a one, we suggest that you could setup up a cluster with [kind](https://kind.sigs.k8s.io/). + +When you're developing `vela-core`, make sure the controller installed by helm chart is not running. +Otherwise, it will conflict with your local running controller. + +You can check and uninstall it by using helm. + +```shell script +helm list -A +helm uninstall -n vela-system kubevela +``` + +### Testing + +It's necessary to write tests for good code quality, please refer to [the principle of test](./principle-of-test) before you start. + +#### Unit test + +```shell script +make test +``` + +To execute the unit test of the API module, the mongodb service needs to exist locally. + +```shell script +make unit-test-apiserver +``` + +#### Integration and E2E test + +**Before e2e test start, make sure you have vela-core running.** + +```shell script +make core-run +``` + +Start to test. + +```shell script +make e2e-test +``` + +### Debugging Locally with Remote KubeVela Environment + +To run vela-core locally for debugging with kubevela installed in the remote cluster: +- Firstly, scaling the replicas of `kubevela-vela-core` to 0 for leader election of `controller-manager`: + ```shell + kubectl scale deploy -n vela-system kubevela-vela-core --replicas=0 + ``` +- Secondly, removing the `WebhookConfiguration`, otherwise an error will be reported when applying your application using `vela-cli` or `kubectl`: + ```shell + kubectl delete ValidatingWebhookConfiguration kubevela-vela-core-admission -n vela-system + kubectl delete MutatingWebhookConfiguration kubevela-vela-core-admission -n vela-system + ``` + +Finally, you can use the commands in the above [Build](#build) and [Testing](#Testing) sections, such as `make run`, to code and debug in your local machine. + +> Note you will not be able to test features relate with validating/mutating webhooks in this way. + +## Run VelaUX Locally + +VelaUX is the UI console of KubeVela, it's also an addon including apiserver code in `kubevela` repo and the frontend code in `velaux` repo. + +Before start, please make sure you have already started the vela controller environment in kubevela repo directory. + +```shell +make run-apiserver +``` + +By default, the apiserver will serving at "0.0.0.0:8000". + +Get the VelaUX code by: + +```shell +git clone git@github.com:kubevela/velaux.git +``` + +Configure the apiserver address: + +```shell +cd velaux +echo "BASE_DOMAIN='http://127.0.0.1:8000'" > .env +``` + +Make sure you have installed [yarn](https://classic.yarnpkg.com/en/docs/install). + +```shell +yarn install +yarn start +``` + +To execute the e2e test of the API module, the mongodb service needs to exist locally. + +```shell script +# save your config +mv ~/.kube/config ~/.kube/config.save + +kind create cluster --image kindest/node:v1.20.7@sha256:688fba5ce6b825be62a7c7fe1415b35da2bdfbb5a69227c499ea4cc0008661ca --name worker +kind get kubeconfig --name worker --internal > /tmp/worker.kubeconfig +kind get kubeconfig --name worker > /tmp/worker.client.kubeconfig + +# restore your config +mv ~/.kube/config.save ~/.kube/config + +make e2e-apiserver-test +``` + +## Create a pull request + +We're excited that you're considering making a contribution to the KubeVela project! +This document guides you through the process of creating a [pull request](https://help.github.com/en/articles/about-pull-requests/). + +### Before you begin + +We know you're excited to create your first pull request. Before we get started, make sure your code follows the relevant [code conventions](./code-conventions). + +### Your first pull request + +Before you submit a PR, run this command to ensure it is ready: +``` +make reviewable +``` + +If this is your first time contributing to an open-source project on GitHub, make sure you read about [Creating a pull request](https://help.github.com/en/articles/creating-a-pull-request). + +To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines: + +- Title and description matches the implementation. +- Commits within the pull request follow the [Formatting guidelines](#Formatting-guidelines). +- The pull request closes one related issue. +- The pull request contains necessary tests that verify the intended behavior. +- If your pull request has conflicts, rebase your branch onto the main branch. + +If the pull request fixes a bug: + +- The pull request description must include `Closes #` or `Fixes #`. +- To avoid regressions, the pull request should include tests that replicate the fixed bug. +- Generally, we will maintain the last 2 releases for bugfix. You should add `backport release-x.x` label or comment `/backport release-x.y` for the releases contained the bug, github bot will automatically backport this PR to the specified release branch after PR merged. If there're any conflicts, you should cherry-pick it manually. + +## Code review + +Once you've created a pull request, the next step is to have someone review your change. +A review is a learning opportunity for both the reviewer and the author of the pull request. + +If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment. +Tag a user by typing the `@` symbol followed by their GitHub username. + +We recommend that you read [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) to learn more about code reviews. + +## Formatting guidelines + +A well-written pull request minimizes the time to get your change accepted. +These guidelines help you write good commit messages and descriptions for your pull requests. + +### Commit message format + +KubeVela follows the [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/) and [commit messages best practices](https://chris.beams.io/posts/git-commit/) to improve better history information. + +The commit message should be structured as follows: + +``` +[optional scope]: + +[optional body] +``` + +#### Examples: + +Commit message with scope: + +``` +Feat(lang): add polish language +``` + +Commit message with no body: + +``` +Docs: correct spelling of CHANGELOG +``` + +Commit message with multi-paragraph body: + +``` +Fix: correct minor typos in code + +see the issue for details + +on typos fixed. + +Reviewed-by: Z +Refs #133 +``` + +#### `` (required) + +Type is required to better capture the area of the commit, based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). + +We capitalize the `` to make sure the subject line is capitalized. `` can be one of the following: + +* **Feat**: A new feature +* **Fix**: A bug fix +* **Docs**: Documentation only changes +* **Build**: Changes that affect the build system or external dependencies +* **Style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +* **Refactor**: A code change that neither fixes a bug nor adds a feature +* **Perf**: A code change that improves performance +* **Test**: Adding missing or correcting existing tests +* **Chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation + +#### `` (optional) + +Scope is optional, it may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, it is could be anything specifying place of the commit change. Github issue link is +also a valid scope. For example: Fix(cli), Feat(api), Fix(#233), etc. + +You can use `*` when the change affects more than a single scope. + +#### `` (required) + +The subject MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., "Fix: array parsing issue when multiple spaces were contained in string", instead of "Fix: bug". + +#### `` (optional) + +A longer commit body may be provided after the short subject, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. + +#### Area + +The area should use upper camel case, e.g. UpperCamelCase. + +Prefer using one of the following areas: + +- **Application:** Changes to the application controller. +- **Component:** Changes to the component related code or definition controller. +- **Trait:** Changes to the trait related code or definition controller. +- **CUE:** Changes to the CUE related logic. +- **Docs:** Changes to documentation. + +**Examples** + +- `Application: Support workflow in application controller` +- `CUE: Fix patch parse issues` +- `Docs: Changed url to URL in all documentation files` + +### Pull request titles + +The KubeVela team _squashes_ all commits into one when we accept a pull request. +The title of the pull request becomes the subject line of the squashed commit message. +We still encourage contributors to write informative commit messages, as they become a part of the Git commit body. + +We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible. + +Make sure that the title for your pull request uses the same format as the subject line in the commit message. If the format is not followed, we will add a label `title-needs-formatting` on the pull request. + +### Pass all the CI checks + +Before merge, All test CI should pass green. +- The `codecov/project` should also pass. This means the coverage should not drop. Currently, the coverage of the Pull Request should have at least 70%. +- KubeVela uses [DCO](https://wiki.linuxfoundation.org/dco) for contributor agreements. It requires you to sign-off every commit before the pull request being merged. + - Git provides a convenient flag `-s` in your commit command to sign-off automatically: + ```shell + git commit -s -m 'This is my commit message' + ``` + - Contributors can also sign-off manually by adding a `Signed-off-by` line to commit messages as the following format, make sure the email matches your github account or the check bot won't pass. + ```shell + This is my commit message + + Signed-off-by: Random Developer + ``` + +## Update the docs & website + +If your pull request merged and this is a new feature or enhancement, it's necessary to update the docs and send a pull request to [kubevela.io](https://github.com/kubevela/kubevela.io) repo. + +Learn how to write the docs by the following guide: + +* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md) +* [Update KubeVela.io CLI Reference Doc](./cli-ref-doc) + +Great, you have complete the lifecycle of code contribution, try to [join the community as a member](https://github.com/kubevela/community/blob/main/community-membership.md) if you're interested. \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/overview.md index 2ca580e5..74dfa227 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/contributor/overview.md @@ -2,11 +2,32 @@ title: 介绍 --- -开发者手册主要包含以下两个部分： -1. 第一部分是[贡献手册](https://kubevela.io/zh/docs/next/contributor/overview#contribution-guide)，介绍如何参与和贡献社区。 -2. 第二部分是[扩展手册](https://kubevela.io/zh/docs/next/contributor/overview#extension-guide)，介绍如何扩展 KubeVela，也非常欢迎你为社区贡献你的扩展。 +开发者手册主要包含以下三个部分： -## 贡献手册 +1. 第一部分是[平台扩展手册](#扩展手册)，介绍扩展 KubeVela 的方法，也非常欢迎你为社区贡献你的扩展。 +2. 第二部分是[贡献指南](#贡献指南)，介绍如何参与和贡献社区，包含了代码和非代码贡献。 + +## 扩展手册 + +这一部分是帮助你扩展 KubeVela 功能的手册。在开始之前确保你已经理解了[核心概念](../getting-started/core-concept)。 + +### 扩展和分发平台插件 + +构建或安装平台插件（Addon）是扩展 KubeVela 平台的基本方式，这里有一个在持续完善的 [catalog](https://github.com/kubevela/catalog)，你可以发现、安装、分享 KubeVela 的平台扩展能力。 + +* [构建你的扩展插件](../platform-engineers/addon/intro)。 +* [制作你的企业级插件仓库](../platform-engineers/addon/addon-registry) +* [制作插件扩展云资源](../platform-engineers/addon/terraform)。 + +### 使用 CUE 扩展高级功能 + +KubeVela 使用 CUE 作为核心引擎，你可以使用 CUE 和 CRD 控制器来粘合绝大部分基础设施功能，扩展更丰富更灵活的高级功能。 + +* 从[学习 CUE](../platform-engineers/cue/basic) 开始。 +* 了解什么是 Kubernetes 中的 [CRD 控制器](https://kubernetes.io/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/)。 + + +## 贡献指南 KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[来自 8 个以上不同组织的贡献者启动](https://github.com/kubevela/community/blob/main/OWNERS.md#bootstrap-contributors)。我们希望 KubeVela 从一开始就有开放的治理方式，所以在项目发布后立即将其捐赠给中立基金会。 @@ -27,7 +48,7 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ 用 Apache 的方式来说“社区胜于代码”。尽管 Kubevela 是 CNCF/Linux 项目，但我们对此具有很强的共鸣。更深入地延续这一点，对于社区的存在及其未来的增长而言，我们认为非编码贡献和代码贡献同样重要。 -* 请参阅[非代码贡献手册](https://kubevela.io/zh/docs/next/contributor/non-code-contribute)，了解你可以提供什么帮助。 +* 请参阅[非代码贡献手册](./non-code-contribute)，了解你可以提供什么帮助。 ### 代码贡献 @@ -35,9 +56,9 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ * [Good first issue](https://github.com/kubevela/kubevela/labels/good%20first%20issue) 通常比较简单。 * [Help wanted](https://github.com/kubevela/kubevela/labels/help%20wanted) 是我们希望社区帮助我们解决的问题，而不关注问题是否复杂。 -* 更多细节请参考[代码贡献手册](https://kubevela.io/zh/docs/next/contributor/code-contribute)。 +* 更多细节请参考[代码贡献手册](./code-contribute)。 -查看[发行过程和节奏](https://kubevela.io/zh/docs/next/contributor/release-process)，以了解你的代码更改何时会发布。 +查看[发行过程和节奏](./release-process)，以了解你的代码更改何时会发布。 ### 成为社区成员 @@ -48,22 +69,4 @@ KubeVela 项目从一开始就由 Cloud Native 社区初始化和维护，由[ * [VelaUX 开发手册](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md) * [Terraform Controller 开发手册](https://github.com/kubevela/terraform-controller/blob/master/CONTRIBUTING.md) -## 扩展手册 - -这一部分是帮助你扩展 KubeVela 功能的手册。在开始之前确保你已经理解了[核心概念](https://kubevela.io/zh/docs/next/getting-started/core-concept)。 - -### 使用 Kubevela 学习 CUE - -KubeVela 使用 CUE 作为核心引擎，你可以使用 CUE 和 CRD 控制器来粘合绝大部分基础设施功能。 - -* [在 KubeVela 中学习 CUE](https://kubevela.io/zh/docs/next/platform-engineers/cue/basic) -* 了解什么是 Kubernetes 中的 [CRD 控制器](https://kubernetes.io/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/) - -### 扩展 Addons - -构建或安装 addons 是扩展 KubeVela 最重要的方式，这里有一个在持续完善的 [catalog](https://github.com/kubevela/catalog)，你可以查看并选择安装。 - -* [构建自己的 Addon](https://kubevela.io/zh/docs/next/platform-engineers/addon/intro) -* [通过 Addon 扩展云资源](https://kubevela.io/zh/docs/next/platform-engineers/addon/terraform) - 开启并享受你的开源贡献之旅吧！ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/version-control.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/version-control.md index c78a9b75..ef878420 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/version-control.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/version-control.md @@ -1,5 +1,5 @@ --- -title: 版本管理 +title: 应用版本管理 --- ## 简介 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/component-dependency-parameter.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/component-dependency-parameter.md index 0184b926..9bd86878 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/component-dependency-parameter.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/component-dependency-parameter.md @@ -1,5 +1,5 @@ --- -title: 应用组件间的依赖和参数传递 +title: 组件编排 --- 本节将介绍如何在 KubeVela 中进行组件间的依赖关系和参数传递。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/overview.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/overview.md index 7b154c2e..48f0afcd 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/overview.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/overview.md @@ -1,9 +1,7 @@ --- -title: 工作流总览 +title: 总览 --- -## 总览 - 工作流作为一个应用部署计划的一部分，可以帮助你自定义应用部署计划中的步骤，粘合额外的交付流程，指定任意的交付环境。简而言之，工作流提供了定制化的控制逻辑，在原有 Kubernetes 模式交付资源（Apply）的基础上，提供了面向过程的灵活性。比如说，使用工作流实现条件判断、暂停、状态等待、数据流传递、多环境灰度、A/B 测试等复杂操作。 工作流由多个步骤组成，典型的工作流步骤包括步骤组（包含一系列子步骤）、人工审核、多集群发布、通知等。你可以在 [内置工作流步骤](./built-in-workflow-defs) 中查看 KubeVela 默认提供的所有内置工作流步骤。如果内置的工作流步骤无法满足你的需求，你也可以 [自定义工作流步骤](../../platform-engineers/workflow/workflow)。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/suspend.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/suspend.md index 680f9f79..358c565f 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/suspend.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/suspend.md @@ -1,5 +1,5 @@ --- -title: 暂停和继续工作流 +title: 暂停和继续 --- 本节将介绍如何在 KubeVela 中暂停和继续工作流。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/timeout.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/timeout.md index a3d13e55..ce5249b0 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/timeout.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/timeout.md @@ -1,5 +1,5 @@ --- -title: 步骤的超时 +title: 步骤超时 --- > 注意：你需要升级到 1.5 及以上版本来使用超时功能。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/webhook-notification.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/webhook-notification.md index 95a91516..ca8030ab 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/webhook-notification.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/end-user/workflow/webhook-notification.md @@ -2,78 +2,4 @@ title: 使用 Webhook 发送通知 --- -在一些情况下，当我们使用工作流部署应用前后，希望能够得到部署的通知。KubeVela 提供了与 Webhook 集成的能力，支持用户在工作流中向邮件、钉钉、Slack 或者飞书发送通知。 - -本节将介绍如何在工作流中通过 `notification` 发送 Webhook 通知。 - -## 如何使用 - -部署如下应用部署计划，在部署组件前后，都有一个 `notification` 步骤发送通知： - -```yaml -apiVersion: core.oam.dev/v1beta1 -kind: Application -metadata: - name: first-vela-workflow - namespace: default -spec: - components: - - name: express-server - type: webservice - properties: - image: oamdev/hello-world - port: 8000 - traits: - - type: ingress - properties: - domain: testsvc.example.com - http: - /: 8000 - workflow: - steps: - - name: dingtalk-message - # 指定步骤类型 - type: notification - properties: - dingding: - # 钉钉 Webhook 地址，请查看：https://developers.dingtalk.com/document/robots/custom-robot-access - url: - value: - # 具体要发送的信息详情 - message: - msgtype: text - text: - content: 开始运行工作流 - - name: application - type: apply-component - properties: - component: express-server - outputs: - - name: app-status - valueFrom: output.status.conditions[0].message + "工作流运行完成" - - name: slack-message - type: webhook-notification - inputs: - - from: app-status - parameterKey: slack.message.text - properties: - slack: - # Slack Webhook 地址，请查看：https://api.slack.com/messaging/webhooks - url: - secretRef: - name: - key: - # 具体要发送的信息详情，会被 input 中的值覆盖 - # message: - # text: condition message + 工作流运行完成 -``` - -## 期望结果 - -通过与 Webhook 的对接，可以看到，在工作流中的组件部署前后，都能在对应的群聊中看到相应的信息。 - -通过 `notification` ，可以使用户方便的与 Webhook 对接消息通知。 - -## 参数说明 - -请参考 [Notification 内置步骤](built-in-workflow-defs##notification) +文档已经迁移到[这里](../../end-user/workflow/built-in-workflow-defs#notification). \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/how-to/dashboard/application/create-application.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/how-to/dashboard/application/create-application.md index 1e8e711a..bc7ffb69 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/how-to/dashboard/application/create-application.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/how-to/dashboard/application/create-application.md @@ -1,8 +1,10 @@ --- -title: 应用生命周期管理 +title: 图形化界面操作 description: 本文介绍在 KubeVela Dashboard 中创建应用的操作方法。 --- +本文档将介绍如何通过图形化界面操作应用。 + ## 创建应用 ### 判断你的应用类别 @@ -63,6 +65,30 @@ description: 本文介绍在 KubeVela Dashboard 中创建应用的操作方法 更新部署可以在任意状态下进行，选择执行某一个流水线后，将使用最新的应用配置进行部署。如果该环境正在执行部署，UI 将提示你是否强制进行新的部署。 +## 管理工作流 + +工作流与应用发布的环境绑定，即应用的每一个环境都有独立的工作流。 + +### 工作流与应用版本的关系 + +应用进行部署的动作则为执行某一个工作流发布一个版本，版本状态跟随工作流的执行状态，也就是说工作流执行完成，则代表该版本处于完成发布的状态。 + +![Application Revision List](../../../resources/app-revision.jpg) + +对接 CI 系统后，版本可以与 Code Commit 关联，实现版本可追溯。在版本操作中后续会实现版本回退功能，你可在任何时候选择将某个环境回退到指定版本。 + +### 编辑工作流 + +进入应用工作流管理页面，选择一个环境的工作流点击 `Edit` 按钮进入编辑状态。我们以使用 `notification` 步骤为例。 + +![workflow-edit](../../../resources/workflow-edit.jpg) + +选择左侧的 `notification` 类型的步骤拖入右侧画布，页面将自动弹出工作流步骤编辑窗口，在设置窗口中，你可以根据需要设置参数。 + +配置完成点击 `Submit` 保存步骤配置，这时需要规划通知步骤的位置，默认它将添加到最后，如果你希望将其放置到中间步骤，需要断开原有步骤直接的连线，然后将通知步骤进行连线放置在中间。 + +工作流配置完成后注意点击工作流窗口右上方的 Save 按钮保存所有变更。保存完成后可以点击页面右上方的 `Deploy` 或右边的选择按钮选择执行该工作流，验证是否可以收到消息通知。 + ## 查看应用实例 查看应用运行实例信息是掌握应用运行状态的直接方式。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/platform-engineers/addon/addon-registry.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/platform-engineers/addon/addon-registry.md new file mode 100644 index 00000000..9c1de827 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/platform-engineers/addon/addon-registry.md @@ -0,0 +1,74 @@ +--- +title: Build your Own Registry +--- + +An addon registry can be used for discovering and distributing addons. Currently, KubeVela has supported two type registry: git server and helm repo. + +## Git as registry + +A directory contains some sub-directories stored in git repository can be used as an addon registry. + +The git type registry type has supported github, gitlab and gitee. + +A typical git addon registry is like [catalog](https://github.com/kubevela/catalog/tree/master/addons). You can clone this repo to your local path and then push to your own git repository. + +```yaml +$ git clone https://github.com/kubevela/catalog/tree/master/addons +$ git remote add +$ git push -u master +``` + +If your repository type is github, you can use this command to add your addon registry. + +```yaml +vela addon registry add my-repo --type git --endpoint= --path= --gitToken= +``` + +If your type is gitee, you can use: + +```yaml +vela addon registry add my-repo --type gitee --endpoint= --path= --gitToken= +``` + +If your type is gitlab, you can use: + +```yaml +vela addon registry add my-repo --type gitlab --gitRepoName= --endpoint= --path= --gitToken= +``` + +## Helm chart repository as registry + +A [helm chart repository](https://helm.sh/docs/topics/chart_repository/) can be used to store addon package. + +You can build your own helm repository by following this [tutorial](https://helm.sh/docs/topics/chart_repository/#hosting-chart-repositories). + +If you already have one, you can follow these steps package add push addon to helm repository. + +Package the addon: + +```yaml +$ vela addon package +``` + +Use [helm cli](https://helm.sh/docs/intro/install/#helm) to push addon package which generated by last step to the helm repository. + +```yaml +$ helm plugin install https://github.com/chartmuseum/helm-push +$ helm cm-push +``` + +More info please refer to [chartmuseum docs](https://github.com/chartmuseum/helm-push). + +Then you can add it as addon registry by this command: + +```yaml +vela addon registry add my-repo --type helm --endpoint= +``` + +If your helm repo must be accessed with username and password. You can set them by: + +```yaml +vela addon registry add my-repo --type helm --endpoint= --username= --password= +``` + +A helm repo type registry can store addon's multi-versions of an addon. In the future we will support [chart-museum](https://chartmuseum.com/docs/) addon, and provide an easier way to build your own versioned addon registry. diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/tutorials/workflows.md b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/tutorials/workflows.md index e8acbb18..33b3fa4d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/tutorials/workflows.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-v1.4/tutorials/workflows.md @@ -3,53 +3,4 @@ title: 管理应用工作流 description: 本文介绍 KubeVela 的工作流工程模式，常用操作和适用的场景。 --- -本文详细介绍应用工作流的功能和使用场景，带你更全面的了解工作流。 - -在 [交付 Kubernetes 原生资源](./k8s-object) 一文中，我们初识了工作流的一个重要使用场景，即人工介入多集群发布的过程，实现可控多集群发布。在本文中我们继续介绍以下话题： - -1. 进一步了解 Workflow 、Revision 和 Env 的关系，以及目前内置的 Workflow 步骤。 -2. 在工作流中实现通知。 -3. 在工作流中进行数据初始化。 - -## 开始之前 - -本文介绍内容相对深入，在此之前，建议先参考 [交付第一个应用](../quick-start), [交付容器镜像](./webservice) 等文章了解其他基础知识和流程。 - -## 工作流与应用版本的关系 - -应用进行部署的动作则为执行某一个工作流发布一个版本，版本状态跟随工作流的执行状态，也就是说工作流执行完成，则代表该版本处于完成发布的状态。工作流与应用发布的环境绑定，即应用的每一个环境都有独立的工作流。 - -![Application Revision List](../resources/app-revision.jpg) - -对接 CI 系统后，版本可以与 Code Commit 关联，实现版本可追溯。在版本操作中后续会实现版本回退功能，你可在任何时候选择将某个环境回退到指定版本。 - -## 内置支持的工作流步骤 - -在 [交付 Kubernetes 原生资源](./k8s-object) 文章中，我们使用了人工审核步骤 `suspend`。我们再来了解一下其他内置的步骤分别是什么作用： - -- `deploy2env`: 应用交付到指定 Target。该步骤 Vela 会根据环境中配置的 Target 自动生成。 -- `deploy-cloud-resource`: 云资源应用交付到指定 Target。该步骤 Vela 会为云资源应用，根据环境中配置的 Target 自动生成，需要注意的是，该类型步骤与 deploy2env 的区别在于控制云资源创建的 CR 资源是部署到管控集群的，服务创建完成生成访问密钥(Secret)后，将 Secret 分发到 Target 指定集群和 Namespace。 -- `share-cloud-resource`: 分发云服务生成的 Secret 到指定 Target，使用该步骤实现云服务多集群共享，即在多集群应用中只创建一个云服务，将其访问密钥分发到多个集群，实现服务共享。 -- `notification`: 通知，支持钉钉、邮件、Slack 三种通知模式，你可将其置于工作流的任何阶段实现消息通知。 -- `webhook`: Web 钩子，你可将其置于工作流任何阶段，实现对外部系统的调用。 - -## 实现消息通知 - -使用 `notification` 步骤可实现钉钉、邮件和 Slack 三种通知模式。进入应用工作流管理页面，选择一个环境的工作流点击 `Edit` 按钮进入编辑状态。 - -![workflow-edit](../resources/workflow-edit.jpg) - -选择左侧的 `notification` 类型的步骤拖入右侧画布，页面将自动弹出工作流步骤编辑窗口，在设置窗口中，你可以根据需要设置三种通知，在同一步骤中，如果设置了多种通知，它同时生效。 - -![workflow-notification](../resources/workflow-notification.jpg) - -如果设置 `Dingding` 通知，点击 `Dingding` 窗口右侧的启用按钮，页面将出现两个输入框，一个是钉钉群通知机器人的 Webhook 地址，参考 [Dingding 群机器人参考文档](https://open.dingtalk.com/document/group/custom-robot-access) 获取。另外一个是通知内容输入框，你可以自定义任何需要发送的通知内容。 - -`Slack` 与 `Dingding` 配置方式类似，参考 [Slack 中获取 Webhook 地址](https://api.slack.com/messaging/webhooks)。 - -`Email` 相对配置数据更多，需要配置邮件服务器、邮件内容和发送目标邮件地址等。 - -配置完成点击 `Submit` 保存步骤配置，这时需要规划通知步骤的位置，默认它将添加到最后，如果你希望将其放置到中间步骤，需要断开原有步骤直接的连线，然后将通知步骤进行连线放置在中间。 - -工作流配置完成后注意点击工作流窗口右上方的 Save 按钮保存所有变更。保存完成后可以点击页面右上方的 `Deploy` 或右边的选择按钮选择执行该工作流，验证是否可以收到消息通知。 - +文档已经迁移到[这里](../how-to/dashboard/application/create-application#deploy-application). \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 2f5818ff..236f3060 100644 --- a/sidebars.js +++ b/sidebars.js @@ -165,13 +165,23 @@ module.exports = { collapsed: true, items: [ 'contributor/overview', - 'contributor/non-code-contribute', - 'contributor/code-contribute', { - Conventions: [ - 'contributor/release-process', - 'contributor/code-conventions', - 'contributor/principle-of-test', + type: 'category', + label: 'Extension', + collapsed: true, + items: [ + { + Addons: [ + 'platform-engineers/addon/intro', + 'platform-engineers/addon/addon-registry' + ], + }, + { + 'Cloud Resources': [ + 'platform-engineers/addon/terraform', + 'platform-engineers/components/component-terraform', + ], + }, ], }, { @@ -195,26 +205,21 @@ module.exports = { 'platform-engineers/debug/debug', ], }, + 'platform-engineers/x-def-version', ], }, { - type: 'category', - label: 'Contribute Extension', - collapsed: true, - items: [ - { - Addons: [ - 'platform-engineers/addon/intro', - 'platform-engineers/addon/addon-registry' - ], - }, - { - 'Cloud Resources': [ - 'platform-engineers/addon/terraform', - 'platform-engineers/components/component-terraform', - ], - }, - 'platform-engineers/x-def-version', + 'Contribution Guide': [ + 'contributor/non-code-contribute', + 'contributor/code-contribute', + 'contributor/cli-ref-doc', + ], + }, + { + Conventions: [ + 'contributor/release-process', + 'contributor/code-conventions', + 'contributor/principle-of-test', ], }, ], diff --git a/versioned_docs/version-v1.4/contributor/cli-ref-doc.md b/versioned_docs/version-v1.4/contributor/cli-ref-doc.md index 3764c055..f8f2fd8b 100644 --- a/versioned_docs/version-v1.4/contributor/cli-ref-doc.md +++ b/versioned_docs/version-v1.4/contributor/cli-ref-doc.md @@ -1,4 +1,9 @@ -# Update KubeVela.io CLI Reference Doc +--- +title: Update CLI Reference +--- + +This guide introduce how to update [CLI reference doc](../cli/vela) in the website. +The whole process was done by script automatically. You need to follow this guide to build your environment. 1. step up these two projects in the same folder. diff --git a/versioned_docs/version-v1.4/contributor/overview.md b/versioned_docs/version-v1.4/contributor/overview.md index f6f0e7ef..bb00fd91 100644 --- a/versioned_docs/version-v1.4/contributor/overview.md +++ b/versioned_docs/version-v1.4/contributor/overview.md @@ -4,8 +4,28 @@ title: Overview The developer guide including two parts: -1. The first part is [contribution guide](#contribution-guide) that introduces how to participate and contribute to the community. -2. The second part is [extension guide](#extension-guide) that introduces how to extend KubeVela, you are also very welcome to contribute your extension to the community. +1. The first part is [extension guide](#extension-guide) that introduces how to extend KubeVela, you are also very welcome to contribute your extension to the community. +2. The second part is [contribution guide](#contribution-guide) that introduces how to participate and contribute to the community. + +## Extension Guide + +This part is a guide to help you extend capabilities for KubeVela. Make sure you have already understand the [**core concepts**](../getting-started/core-concept) before you start. + +### Extend Addons + +Building or installing addons is the most important way to extend KubeVela, there's a growing [catalog](https://github.com/kubevela/catalog) of addons you can choose for installation. You can also share your platform extension by KubeVela addon registry. + +* [Build Your Own Addon](../platform-engineers/addon/intro). +* [Build Your Addon Registry](../platform-engineers/addon/addon-registry). +* [Extend Cloud Resources by Addon](../platform-engineers/addon/terraform). + +### Learn CUE to extend more powerful features + +KubeVela use CUE as it's core engine, and you can use CUE and CRD controller to glue almost every infrastructure capabilities. +As a result, you can extend more powerful features for your platform. + +- Start to [Learn CUE in KubeVela](../platform-engineers/cue/basic). +- Learn what is [CRD Controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in Kubernetes. ## Contribution Guide @@ -50,23 +70,4 @@ If you're interested to become a community member or learn more about the govern * [VelaUX Developer Guide](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md) * [Terraform Controller Developer Guide](https://github.com/oam-dev/terraform-controller/blob/master/CONTRIBUTING.md) - -## Extension Guide - -This part is a guide to help you extend capabilities for KubeVela. Make sure you have already understand the [**core concepts**](../getting-started/core-concept) before you start. - -### Learn CUE with KubeVela - -KubeVela use CUE as it's core engine, and you can use CUE and CRD controller to glue almost every infrastructure capabilities. - -- [Learn CUE in KubeVela](../platform-engineers/cue/basic) -- Learn what is [CRD Controller](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in Kubernetes - -### Extend Addons - -Building or installing addons is the most important way to extend KubeVela, there's a growing [catalog](https://github.com/kubevela/catalog) of addons you can choose for installation. - -* [Build Your Own Addon](../platform-engineers/addon/intro) -* [Extend Cloud Resources by Addon](../platform-engineers/addon/terraform) - Enjoy coding and collaboration in OSS world! diff --git a/versioned_docs/version-v1.4/end-user/workflow/overview.md b/versioned_docs/version-v1.4/end-user/workflow/overview.md index da5b7fbe..bd82ecdf 100644 --- a/versioned_docs/version-v1.4/end-user/workflow/overview.md +++ b/versioned_docs/version-v1.4/end-user/workflow/overview.md @@ -2,8 +2,6 @@ title: Overview --- -## Overview - Workflows, as part of the Application, can glue together additional delivery processes and specify arbitrary delivery environments. In short, `Workflow` provides customized control flow and flexibility based on the original delivery model of Kubernetes(Apply). For example, `Workflow` can be used to implement complex operations such as pause, manual approval, if conditions, waiting status, data flow, multi-environment gray release, A/B testing, etc. A workflow consists of multiple steps, and typical workflow steps include step groups (containing a series of sub-steps), human review, multi-cluster publishing, notifications, etc. You can view all built-in workflow steps provided by default in KubeVela in [built-in workflow steps](./built-in-workflow-defs). If the built-in workflow steps don't meet your needs, you can also [custom workflow steps](../../platform-engineers/workflow/workflow). diff --git a/versioned_docs/version-v1.4/platform-engineers/addon/addon-registry.md b/versioned_docs/version-v1.4/platform-engineers/addon/addon-registry.md index e55f7457..9c1de827 100644 --- a/versioned_docs/version-v1.4/platform-engineers/addon/addon-registry.md +++ b/versioned_docs/version-v1.4/platform-engineers/addon/addon-registry.md @@ -72,10 +72,3 @@ vela addon registry add my-repo --type helm --endpoint= --username=