barnettZQG
GitHub
commit
b4408363c0
15
README.md
15
README.md
|
|
@ -59,7 +59,7 @@ When you add or modify the docs, these three files(`docs/en/`, `docs/en/resource
|
||||||
},
|
},
|
||||||
```
|
```
|
||||||
|
|
||||||
|
After you finished modify the docs, please try to [have a preview of the changes](#Website-Preview).
|
||||||
|
|
||||||
|
|
||||||
## Localization README
|
## Localization README
|
||||||
|
|
@ -69,9 +69,9 @@ When you add or modify the docs, these three files(`docs/en/`, `docs/en/resource
|
||||||
| [Chinese](README-zh.md) |
|
| [Chinese](README-zh.md) |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# Website Preview
|
# Website Preview
|
||||||
|
|
||||||
|
Please make sure you have [yarn installed](https://www.geeksforgeeks.org/how-to-install-yarn-in-macos-ubuntu-windows/) in your OS environment.
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
|
|
@ -103,15 +103,22 @@ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
|
||||||
|
|
||||||
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
|
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
|
||||||
|
|
||||||
|
## Versions for new release
|
||||||
|
|
||||||
## Build New Version
|
All docs of new features should be updated in the latest docs, we will create a new version of docs along with the code release.
|
||||||
|
|
||||||
|
### Build New Version
|
||||||
|
|
||||||
```
|
```
|
||||||
yarn docusaurus docs:version v1.3
|
yarn docusaurus docs:version v1.3
|
||||||
```
|
```
|
||||||
|
|
||||||
## Update Docs for version
|
### Update Docs for version
|
||||||
|
|
||||||
```
|
```
|
||||||
make update-version version=v1.3
|
make update-version version=v1.3
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Send your pull request
|
||||||
|
|
||||||
|
After all changes checked well, please [creating a pull request](https://help.github.com/en/articles/creating-a-pull-request) with [DCO](https://github.com/apps/dco).
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
title: Multi-Cluster Delivery
|
title: Deploy across Multi-Clusters
|
||||||
---
|
---
|
||||||
|
|
||||||
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
|
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
|
||||||
|
|
@ -17,22 +17,10 @@ The following guide will introduce how to manage applications across clusters on
|
||||||
|
|
||||||
## Preparation
|
## Preparation
|
||||||
|
|
||||||
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
|
Please make sure you have clusters in your control plane, in general, this work should be done by operator engineers.
|
||||||
|
If you're a DevOps engineer or trying KubeVela, you can refer to [manage cluster docs](../platform-engineers/system-operation/managing-clusters) to learn how to join clusters.
|
||||||
|
|
||||||
```shell script
|
For the rest docs, we assume you have clusters with the following names:
|
||||||
vela cluster join <your kubeconfig path>
|
|
||||||
```
|
|
||||||
|
|
||||||
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
|
|
||||||
you can also specify the name by `--name` parameter. For example:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ vela cluster join beijing.kubeconfig --name beijing
|
|
||||||
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
|
|
||||||
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
|
|
||||||
```
|
|
||||||
|
|
||||||
After clusters joined, you could list all clusters managed by KubeVela.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ vela cluster list
|
$ vela cluster list
|
||||||
|
|
@ -45,27 +33,6 @@ cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
|
||||||
|
|
||||||
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
||||||
|
|
||||||
You can also detach a cluster if you do not want to use it anymore.
|
|
||||||
|
|
||||||
```shell script
|
|
||||||
$ vela cluster detach beijing
|
|
||||||
```
|
|
||||||
|
|
||||||
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
|
|
||||||
|
|
||||||
You can also give labels to your clusters, which helps you select clusters for deploying applications.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
|
|
||||||
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
|
|
||||||
$ vela cluster list
|
|
||||||
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
|
||||||
local Internal - true
|
|
||||||
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
|
||||||
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
|
|
||||||
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
## Deliver Application to Clusters
|
## Deliver Application to Clusters
|
||||||
|
|
||||||
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
|
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
|
||||||
|
|
@ -530,7 +497,3 @@ If you already have applications running in production environment and do not wa
|
||||||
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
|
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
|
||||||
|
|
||||||
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
|
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
|
||||||
|
|
||||||
## Next Step
|
|
||||||
|
|
||||||
* Refer to more examples about [integrating with Jenkins](../tutorials/jenkins).
|
|
||||||
|
|
@ -0,0 +1,360 @@
|
||||||
|
---
|
||||||
|
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+
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Install Kubebuilder manually</summary>
|
||||||
|
|
||||||
|
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/
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 #<issue number>` or `Fixes #<issue number>`.
|
||||||
|
- To avoid regressions, the pull request should include tests that replicate the fixed bug.
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>[optional scope]: <subject>
|
||||||
|
|
||||||
|
[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
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `<type>` (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 `<type>` to make sure the subject line is capitalized. `<type>` 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
|
||||||
|
|
||||||
|
#### `<scope>` (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.
|
||||||
|
|
||||||
|
#### `<subject>` (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".
|
||||||
|
|
||||||
|
#### `<body>` (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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
@ -0,0 +1,179 @@
|
||||||
|
---
|
||||||
|
title: Code Conventions
|
||||||
|
---
|
||||||
|
|
||||||
|
In this section, you will find the code conventions for all kinds of code KubeVela project related. It's not necessary to learn all of them at once, but make sure you have read corresponding parts before you start to code.
|
||||||
|
|
||||||
|
- [Go Code Conventions](#go-code-conventions)
|
||||||
|
- [Bash or Script Conventions](#bash-or-script-conventions)
|
||||||
|
- [API Conventions](#api-conventions)
|
||||||
|
- [Testing Conventions](#testing-conventions)
|
||||||
|
- [Directory and File Conventions](#directory-and-file-conventions)
|
||||||
|
- [Logging Conventions](#logging-conventions)
|
||||||
|
|
||||||
|
## Go Code Conventions
|
||||||
|
|
||||||
|
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
|
||||||
|
|
||||||
|
- [Effective Go](https://golang.org/doc/effective_go.html)
|
||||||
|
|
||||||
|
- Know and avoid [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f)
|
||||||
|
|
||||||
|
- Comment your code.
|
||||||
|
- [Go's commenting conventions](http://blog.golang.org/godoc-documenting-go-code)
|
||||||
|
- If reviewers ask questions about why the code is the way it is, that's a
|
||||||
|
sign that comments might be helpful.
|
||||||
|
|
||||||
|
- Command-line flags should use dashes, not underscores
|
||||||
|
|
||||||
|
- API
|
||||||
|
- According to RFC3986, URLs are "case sensitive". KubeVela uses snake_case for API URLs.
|
||||||
|
- e.g.: `POST /v1/cloud_clusters`
|
||||||
|
|
||||||
|
- Naming
|
||||||
|
- Please consider package name when selecting an interface name, and avoid
|
||||||
|
redundancy.
|
||||||
|
|
||||||
|
- e.g.: `storage.Interface` is better than `storage.StorageInterface`.
|
||||||
|
|
||||||
|
- Do not use uppercase characters, underscores, or dashes in package
|
||||||
|
names.
|
||||||
|
- Please consider parent directory name when choosing a package name.
|
||||||
|
|
||||||
|
- so pkg/controllers/autoscaler/foo.go should say `package autoscaler`
|
||||||
|
not `package autoscalercontroller`.
|
||||||
|
- Unless there's a good reason, the `package foo` line should match
|
||||||
|
the name of the directory in which the .go file exists.
|
||||||
|
- Importers can use a different name if they need to disambiguate.
|
||||||
|
|
||||||
|
- Locks should be called `lock` and should never be embedded (always `lock
|
||||||
|
sync.Mutex`). When multiple locks are present, give each lock a distinct name
|
||||||
|
following Go conventions - `stateLock`, `mapLock` etc.
|
||||||
|
|
||||||
|
## Bash or Script Conventions
|
||||||
|
|
||||||
|
- https://google.github.io/styleguide/shell.xml
|
||||||
|
|
||||||
|
- Ensure that build, release, test, and cluster-management scripts run on
|
||||||
|
macOS
|
||||||
|
|
||||||
|
## API Conventions
|
||||||
|
|
||||||
|
- KubeVela follows the Kubernetes conventions
|
||||||
|
|
||||||
|
- [API changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md)
|
||||||
|
|
||||||
|
- [API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md)
|
||||||
|
|
||||||
|
## Testing Conventions
|
||||||
|
|
||||||
|
- All new packages and most new significant functionality must come with unit
|
||||||
|
tests
|
||||||
|
|
||||||
|
- Table-driven tests are preferred for testing multiple scenarios/inputs; for
|
||||||
|
example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
|
||||||
|
|
||||||
|
- Unit tests must pass on macOS and Windows platforms - if you use Linux
|
||||||
|
specific features, your test case must either be skipped on windows or compiled
|
||||||
|
out (skipped is better when running Linux specific commands, compiled out is
|
||||||
|
required when your code does not compile on Windows).
|
||||||
|
|
||||||
|
- Avoid waiting for a short amount of time (or without waiting) and expect an
|
||||||
|
asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
|
||||||
|
running). Wait and retry instead.
|
||||||
|
|
||||||
|
- Significant features should come with integration (test/integration) and/or
|
||||||
|
end-to-end (e2e/) tests.
|
||||||
|
|
||||||
|
- Including new vela cli commands and major features of existing commands
|
||||||
|
|
||||||
|
Please refer to [the principle of test](./principle-of-test) for more details.
|
||||||
|
|
||||||
|
## Directory and file Conventions
|
||||||
|
|
||||||
|
- Avoid package sprawl. Find an appropriate subdirectory for new packages.
|
||||||
|
- Libraries with no more appropriate home belong in new package
|
||||||
|
subdirectories of pkg/util
|
||||||
|
|
||||||
|
- Avoid general utility packages. Packages called "util" are suspect. Instead,
|
||||||
|
derive a name that describes your desired function. For example, the utility
|
||||||
|
functions dealing with waiting for operations are in the "wait" package and
|
||||||
|
include functionality like Poll. So the full name is wait.Poll
|
||||||
|
|
||||||
|
- All filenames should be lowercase
|
||||||
|
|
||||||
|
- Go source files and directories use underscores, not dashes
|
||||||
|
- Package directories should generally avoid using separators as much as
|
||||||
|
possible (when packages are multiple words, they usually should be in nested
|
||||||
|
subdirectories).
|
||||||
|
|
||||||
|
- Document directories and filenames should use dashes rather than underscores
|
||||||
|
|
||||||
|
- Contrived examples that illustrate system features belong in
|
||||||
|
`/docs/user-guide` or `/docs/admin`, depending on whether it is a feature primarily
|
||||||
|
intended for users that deploy applications or cluster administrators,
|
||||||
|
respectively. Actual application examples belong in /examples.
|
||||||
|
- Examples should also illustrate [best practices for configuration and using the system](https://kubernetes.io/docs/concepts/configuration/overview/)
|
||||||
|
|
||||||
|
- Third-party code
|
||||||
|
|
||||||
|
- Go code for normal third-party dependencies is managed using
|
||||||
|
[go modules](https://github.com/golang/go/wiki/Modules)
|
||||||
|
|
||||||
|
- Other third-party code belongs in `/third_party`
|
||||||
|
- forked third party Go code goes in `/third_party/forked`
|
||||||
|
- forked _golang stdlib_ code goes in `/third_party/forked/golang`
|
||||||
|
|
||||||
|
- Third-party code must include licenses
|
||||||
|
|
||||||
|
- This includes modified third-party code and excerpts, as well
|
||||||
|
|
||||||
|
## Logging Conventions
|
||||||
|
|
||||||
|
### Structured logging
|
||||||
|
|
||||||
|
We recommend using `klog.InfoS` to structure the log. The `msg` argument need start from a capital letter.
|
||||||
|
and name arguments should always use lowerCamelCase.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// func InfoS(msg string, keysAndValues ...interface{})
|
||||||
|
klog.InfoS("Reconcile traitDefinition", "traitDefinition", klog.KRef(req.Namespace, req.Name))
|
||||||
|
// output:
|
||||||
|
// I0605 10:10:57.308074 22276 traitdefinition_controller.go:59] "Reconcile traitDefinition" traitDefinition="vela-system/expose"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Use `klog.KObj` and `klog.KRef` for Kubernetes objects
|
||||||
|
|
||||||
|
`klog.KObj` and `klog.KRef` can unify the output of kubernetes object.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// KObj is used to create ObjectRef when logging information about Kubernetes objects
|
||||||
|
klog.InfoS("Start to reconcile", "appDeployment", klog.KObj(appDeployment))
|
||||||
|
// KRef is used to create ObjectRef when logging information about Kubernetes objects without access to metav1.Object
|
||||||
|
klog.InfoS("Reconcile application", "application", klog.KRef(req.Namespace, req.Name))
|
||||||
|
```
|
||||||
|
|
||||||
|
### Logging Level
|
||||||
|
|
||||||
|
[This file](https://github.com/kubevela/kubevela/blob/master/pkg/controller/common/logs.go) contains KubeVela's log level,
|
||||||
|
you can set the log level by `klog.V(level)`.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// you can use klog.V(common.LogDebug) to print debug log
|
||||||
|
klog.V(common.LogDebug).InfoS("Successfully applied components", "workloads", len(workloads))
|
||||||
|
```
|
||||||
|
|
||||||
|
Looking for more details in [Structured Logging Guide](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md#structured-logging-in-kubernetes).
|
||||||
|
|
||||||
|
|
||||||
|
## Linting and formatting
|
||||||
|
|
||||||
|
To ensure consistency across the Go codebase, we require all code to pass a number of linter checks.
|
||||||
|
|
||||||
|
To run all linters, use the `reviewable` Makefile target:
|
||||||
|
|
||||||
|
```shell script
|
||||||
|
make reviewable
|
||||||
|
```
|
||||||
|
|
||||||
|
The command will clean code along with some lint checks. Please remember to check in all changes after that.
|
||||||
|
|
@ -0,0 +1,53 @@
|
||||||
|
---
|
||||||
|
title: Non-code Contribution Guide
|
||||||
|
---
|
||||||
|
|
||||||
|
You can pick up any of the following ways you're interested to contribute.
|
||||||
|
|
||||||
|
## Contribute Use cases and Samples
|
||||||
|
|
||||||
|
* If you're using KubeVela, the easiest thing to contribute is to [credit the community](https://github.com/kubevela/kubevela/issues/1662).
|
||||||
|
|
||||||
|
* If you are interested, you can also write a [kubevela.io blog](https://kubevela.net/blog) to tell more about the use case.
|
||||||
|
|
||||||
|
* You can also contribute to [KubeVela Official Samples](https://github.com/kubevela/samples).
|
||||||
|
|
||||||
|
|
||||||
|
## Report bugs
|
||||||
|
|
||||||
|
Before submitting a new issue, try to make sure someone hasn't already reported the problem.
|
||||||
|
Look through the [existing issues](https://github.com/kubevela/kubevela/issues) for similar issues.
|
||||||
|
|
||||||
|
Report a bug by submitting a [bug report](https://github.com/kubevela/kubevela/issues/new?assignees=&labels=kind%2Fbug&template=bug_report.md&title=).
|
||||||
|
Make sure that you provide as much information as possible on how to reproduce the bug.
|
||||||
|
|
||||||
|
Follow the issue template and add additional information that will help us replicate the problem.
|
||||||
|
|
||||||
|
### Security issues
|
||||||
|
|
||||||
|
If you believe you've found a security vulnerability, please read our [security policy](https://github.com/kubevela/kubevela/blob/master/SECURITY.md) for more details.
|
||||||
|
|
||||||
|
## Suggest enhancements
|
||||||
|
|
||||||
|
If you have an idea to improve KubeVela, submit an [feature request](https://github.com/kubevela/kubevela/issues/new?assignees=&labels=kind%2Ffeature&template=feature_request.md&title=%5BFeature%5D).
|
||||||
|
|
||||||
|
## Triage issues
|
||||||
|
|
||||||
|
If you don't have the knowledge or time to code, consider helping with _issue triage_. The community will thank you for saving them time by spending some of yours.
|
||||||
|
|
||||||
|
Read more about the ways you can [Triage issues](https://github.com/kubevela/community/blob/main/ISSUE_TRIAGE.md).
|
||||||
|
|
||||||
|
## Answering questions
|
||||||
|
|
||||||
|
If you have a question and you can't find the answer in the [documentation](https://kubevela.io/docs/),
|
||||||
|
the next step is to ask it on the [github discussion](https://github.com/kubevela/kubevela/discussions).
|
||||||
|
|
||||||
|
It's important to us to help these users, and we'd love your help. You can help other KubeVela users by answering [their questions](https://github.com/kubevela/kubevela/discussions).
|
||||||
|
|
||||||
|
## Contribute to the Docs
|
||||||
|
|
||||||
|
Contributing to the docs needs to learn some knowledge about how to make a pull request to Github, I think this won't be hard if you follow the guide.
|
||||||
|
|
||||||
|
* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md)
|
||||||
|
|
||||||
|
For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/).
|
||||||
|
|
@ -1,35 +1,49 @@
|
||||||
---
|
---
|
||||||
title: Developer Guide
|
title: Introduction
|
||||||
---
|
---
|
||||||
|
|
||||||
Welcome developers out there! Please check the [Community Membership](https://github.com/kubevela/community/blob/main/community-membership.md) to start engaging with the community.
|
KubeVela project is initialized and maintained by the cloud native community since day 0 with [bootstrapping contributors from 8+ different organizations](https://github.com/kubevela/community/blob/main/OWNERS.md#bootstrap-contributors). We intend for KubeVela to have an open governance since the very beginning and donate the project to neutral foundation as soon as it's released.
|
||||||
|
|
||||||
## Common Code Contribution Guide
|
To help us create a safe and positive community experience for all, we require all participants adhere to the CNCF Community [Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
|
||||||
|
|
||||||
* [Create a pull request](https://github.com/kubevela/kubevela/blob/master/contribute/create-pull-request.md)
|
This document is a guide to help you through the process of contributing to KubeVela.
|
||||||
* [Developer guide](https://github.com/kubevela/kubevela/blob/master/contribute/developer-guide.md)
|
|
||||||
* [Triage issues](https://github.com/kubevela/kubevela/blob/master/contribute/triage-issues.md)
|
|
||||||
* [Code conventions](https://github.com/kubevela/kubevela/blob/master/contribute/coding-conventions.md)
|
|
||||||
* [Release Process And Cadence](https://github.com/kubevela/kubevela/blob/master/contribute/develop-code-flow.pdf)
|
|
||||||
|
|
||||||
## Contribute Addons
|
## Become a contributor
|
||||||
|
|
||||||
|
You can contribute to KubeVela in several ways including code and non-code contributions,
|
||||||
|
we appreciate every effort you contribute to the community. Here are some examples:
|
||||||
|
|
||||||
|
* Contribute to the codebase and docs.
|
||||||
|
* Report and triage issues.
|
||||||
|
* Organize meetups and user groups in your local area.
|
||||||
|
* Help others by answering questions about KubeVela.
|
||||||
|
|
||||||
|
### Non-code contribution
|
||||||
|
|
||||||
|
The Apache way says "Community Over Code". Although KubeVela is a CNCF/Linux project, we possess a strong resonance to it. To second and stretch this merit deeper, we regard non-coding contribution as equally important with code contribution for the community's very existence and its future growth.
|
||||||
|
|
||||||
|
- Refer to [Non-code Contribution Guide](./non-code-contribute) to know how you could help.
|
||||||
|
|
||||||
|
### Code contribution
|
||||||
|
|
||||||
|
Unsure where to begin contributing to KubeVela codebase? Start by browsing issues labeled `good first issue` or `help wanted`.
|
||||||
|
|
||||||
|
- [Good first issue](https://github.com/kubevela/kubevela/labels/good%20first%20issue) issues are generally straightforward to complete.
|
||||||
|
- [Help wanted](https://github.com/kubevela/kubevela/labels/help%20wanted) issues are problems we would like the community to help us with regardless of complexity.
|
||||||
|
- Refer to [Code Contribution Guide](./code-contribute) for more details.
|
||||||
|
|
||||||
|
Learn the [Release Process And Cadence](https://github.com/kubevela/kubevela/blob/master/contribute/develop-code-flow.pdf) to know when your code changes will be released.
|
||||||
|
|
||||||
|
|
||||||
|
## Become a community member
|
||||||
|
|
||||||
|
If you're interested to become a community member or learn more about the governance, please check the [community membership](https://github.com/kubevela/community/blob/main/community-membership.md) for details.
|
||||||
|
|
||||||
|
|
||||||
|
## Contribute Addons and related projects
|
||||||
|
|
||||||
* [Build Your Own Addon](../platform-engineers/addon/intro)
|
* [Build Your Own Addon](../platform-engineers/addon/intro)
|
||||||
* [Addon Repository](https://github.com/kubevela/catalog)
|
* [Addon Repository](https://github.com/kubevela/catalog)
|
||||||
|
|
||||||
## Contribute to the Docs & Website
|
|
||||||
|
|
||||||
* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md)
|
|
||||||
* [Update KubeVela.io CLI Reference Doc](./cli-ref-doc)
|
|
||||||
|
|
||||||
## Contribute use cases and more samples
|
|
||||||
|
|
||||||
* [Credit the community](https://github.com/kubevela/kubevela/issues/1662)
|
|
||||||
* [KubeVela Official Samples](https://github.com/kubevela/samples)
|
|
||||||
* [Add a blog](https://kubevela.net/blog)
|
|
||||||
|
|
||||||
## Other Projects
|
|
||||||
|
|
||||||
* [VelaUX Developer Guide](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md)
|
* [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)
|
* [Terraform Controller Developer Guide](https://github.com/oam-dev/terraform-controller/blob/master/CONTRIBUTING.md)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,97 @@
|
||||||
|
---
|
||||||
|
title: Principle of Test
|
||||||
|
---
|
||||||
|
|
||||||
|
## Definition of concept
|
||||||
|
|
||||||
|
Generally, there are three types of test cases:
|
||||||
|
|
||||||
|
- unit test
|
||||||
|
- integration test, with mocking api for test
|
||||||
|
- end to end(e2e) test
|
||||||
|
|
||||||
|
Each of them brings us different gains and pains. We should follow the principles below for better development life.
|
||||||
|
|
||||||
|
## Unit Test
|
||||||
|
|
||||||
|
The main purposes of writing and maintaining unit tests are:
|
||||||
|
|
||||||
|
- Explicit: ensure that the function behavior meets the design expectations.
|
||||||
|
- Implicit: facilitates more reasonable code structure and interface-oriented programming.
|
||||||
|
|
||||||
|
Test target of a unit test is a class or a segment of algorithm code. In theory, functions with relatively independent logic should has at least one unit test case (except for getter and setter).
|
||||||
|
|
||||||
|
Basic principles for writing a single test are:
|
||||||
|
|
||||||
|
- Keep It Simple and Stupid.
|
||||||
|
- One case covers only one scenario.
|
||||||
|
- Mock tools (such as golang/mock) are powerful, but **NOT recommended**. When you think you have to introduce mocking to unit test, what you really need is Integration test or event e2e test。
|
||||||
|
|
||||||
|
Single test requires high efficiency. For example, during code refactoring, after a function logic is modified, unit test of the entire module may be triggered to ensure that the modification meets expectations.
|
||||||
|
|
||||||
|
## Integration Test
|
||||||
|
|
||||||
|
The propose of integration test is to setup parts of highly associated modules in a system, test is to ensure the interaction between modules within expectations.
|
||||||
|
|
||||||
|
Let's use an example to learn how it works. In KubeVela project, integration tests are mainly divided into two categories:
|
||||||
|
|
||||||
|
- The vela core controller. You need to add corresponding tests for major processes such as render, orchestrate, and deploy the CRD results into Kubernetes. In this case, you will have a mock server for Kubernetes API, then you can add tests to cover all these automated logic without the real Kubernetes and the other CRD controllers running.
|
||||||
|
- Addons, such as velaux, apiserver and cli. You can add corresponding tests like creating, destroying, and updating an Application without the controller really acting.
|
||||||
|
|
||||||
|
Integration test of the core part don't care about how CRD working. Therefore, it can mock the CRD controller behavior to speed up the test efficiency. While the outside CLI don't care about how applications acted, they just not to ensure the application has the correct spec.
|
||||||
|
|
||||||
|
## E2E Test
|
||||||
|
|
||||||
|
The propose of e2e test is to simulate the user's real behavior, suitable for verification of the whole project.
|
||||||
|
|
||||||
|
We recommend e2e test to be added in the following situations:
|
||||||
|
|
||||||
|
- To interact with upstream and downstream projects, for example:
|
||||||
|
1. The application controller should interact with rollout and workload for progressive rollout.
|
||||||
|
1. The CLI relies on the controller to response for next actions in one command.
|
||||||
|
- Core Feature/Scenario: each core feature or scenario must has at least one e2e test case.
|
||||||
|
|
||||||
|
## Best Practice
|
||||||
|
|
||||||
|
The purpose of the test is to ensure the quality of continuous software delivery, with emphasis on the word "continuous". It is necessary to ensure not only the quality of the current delivery, but also the quality of future software delivery. It is particularly important to make good use of the respective advantages of the three test types and combine them to ensure the overall quality of the software.
|
||||||
|
|
||||||
|
| | Time consumed Running | Test Stability | Can simulate User behavior |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| unittest | minimal | high | no |
|
||||||
|
| integration test | middium | middium | almost |
|
||||||
|
| e2e test | much | low | yes |
|
||||||
|
|
||||||
|
Time consumed running is easy to understand here. A larger scale of software ability one test covering, the more time environment preparation and case running will cost. As a result, the testing efficiency is also lower.
|
||||||
|
In terms of stability, the larger the case coverage scale is, the more problems it may encounter, and some of the problems are not the real bugs we want to discover, but merely noises. In simulating real user behavior, only e2e can cover end-to-end to ensure that the entire link can work together.
|
||||||
|
|
||||||
|
As for the long-term value, it refers to the value of the existing case in the continuous software iteration process. For unit test, during code refactoring, it is adjusted with the adjustment of class and function, the code base is consistent with the hot spots in software iteration and continues to evolve.
|
||||||
|
|
||||||
|
However, integration/e2e test is usually split into subsystem boundaries, whose external interfaces are relatively stable (there are very few functional changes during the software iteration of distributed systems, generally forward compatibility), integration/e2e test code base is relatively stable, which is very important in the future evolution of the system. It can timely discover whether new functions damage existing functions.
|
||||||
|
|
||||||
|
|
||||||
|
Combined with the characteristics of all three, the best way to balance is to comply with the pyramid model. The chassis is unittest, the middle is integration test, and the top layer is e2e.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
\
|
||||||
|
/ \
|
||||||
|
/ \
|
||||||
|
/ \
|
||||||
|
/ e2e \
|
||||||
|
/----------
|
||||||
|
/ \
|
||||||
|
/intergeration\
|
||||||
|
/ \
|
||||||
|
/-----------------\
|
||||||
|
/ \
|
||||||
|
/ unit-test \
|
||||||
|
/ \
|
||||||
|
---------------------------
|
||||||
|
```
|
||||||
|
|
||||||
|
KubeVela would like to follow the 70/20/10 principle. that is, 70% unittest,20% integration test, and 10% e2e test. Each module has some differences. However, the higher the upper layer, the larger the test coverage, but the smaller the test case set. This pyramid model remains unchanged. The following situations need to be avoided:
|
||||||
|
|
||||||
|
- Inverted pyramid, all rely on e2e to build the test
|
||||||
|
- Funnel model, a large number of unit + e2e test, but no integration test
|
||||||
|
|
||||||
|
It's hard to keep the test quality as we mainly focus on features instead of the stability. But for all of our maintainers, it's our duty to keep the test in good quality to make the community running well in the long term.
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
---
|
||||||
|
title: Release Process And Cadence
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,5 +1,103 @@
|
||||||
---
|
---
|
||||||
title: Distributed External Kubernetes Objects
|
title: Multi-cluster Distribution
|
||||||
---
|
---
|
||||||
|
|
||||||
This docs has been migrated, please refer to the [k8s-objects docs](../../tutorials/k8s-object#distributed-external-kubernetes-objects).
|
> This section requires you to know the basics about how to deploy multi-cluster application with policy and workflow. You can refer to [Multi-cluster Delivery](../../case-studies/multi-cluster) for container images, they're working in the same way.
|
||||||
|
|
||||||
|
You can reference and distribute existing Kubernetes objects with KubeVela in the following scenarios:
|
||||||
|
|
||||||
|
- Copying secrets from the hub cluster into managed clusters.
|
||||||
|
- Promote deployments from canary clusters into production clusters.
|
||||||
|
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Refer to Existing Kubernetes Objects in Component
|
||||||
|
|
||||||
|
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-example
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: image-pull-secrets
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: secret
|
||||||
|
name: image-credential-to-copy
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-clusters
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusterLabelSelector:
|
||||||
|
region: hangzhou
|
||||||
|
```
|
||||||
|
|
||||||
|
### Details for the *ref-objects* typed component
|
||||||
|
|
||||||
|
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
|
||||||
|
|
||||||
|
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
|
||||||
|
|
||||||
|
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-duplicate-deployments
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: duplicate-deployment
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: deployment
|
||||||
|
cluster: hangzhou-1
|
||||||
|
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
|
||||||
|
labelSelector:
|
||||||
|
need-duplicate: "true"
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-2
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusters: ["hangzhou-2"]
|
||||||
|
```
|
||||||
|
|
||||||
|
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
|
||||||
|
|
||||||
|
### Working with Trait
|
||||||
|
|
||||||
|
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-multiple-resources
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: nginx-ref-multiple-resources
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: deployment
|
||||||
|
- resource: service
|
||||||
|
traits:
|
||||||
|
- type: scaler
|
||||||
|
properties:
|
||||||
|
replicas: 3
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-clusters
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusterLabelSelector:
|
||||||
|
region: hangzhou
|
||||||
|
```
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
title: Create Application
|
title: Lifecycle of Application
|
||||||
description: create an application by kubevela dashboard
|
description: lifecycle of an application by kubevela dashboard
|
||||||
---
|
---
|
||||||
|
|
||||||
### Configure the basic information
|
### Configure the basic information
|
||||||
|
|
@ -30,8 +30,156 @@ Different component types are different significantly, you can fill in the forms
|
||||||
|
|
||||||
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
|
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
|
||||||
|
|
||||||
You need to [bind environment](./bind-new-environment) for real deployment.
|
### Bind Application with Environment
|
||||||
|
|
||||||
### Next Step
|
We can specify bind with one or more environments before deploy.
|
||||||
|
|
||||||
* [Bind Application with Environment](./bind-new-environment)
|
After we have created application and configured the baseline well, we can bind an application with environment to deploy.
|
||||||
|
|
||||||
|
You can bind with one environment as `dev` environment for develop and debug. When everything works well, you can bind with the production environment.
|
||||||
|
|
||||||
|
The operation likes below:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, in the application management page, click `Bind Environment`, choose the environment prepared.
|
||||||
|
|
||||||
|
If there's no environment, you can click the `Create new environment` for creation.
|
||||||
|
|
||||||
|
After choose well, click the `submit` button, it will show the new environment created on the right side of the baseline config as a tab.
|
||||||
|
|
||||||
|
KubeVela will automatically generate the deploy workflow for the newly created environments.
|
||||||
|
|
||||||
|
In the environment tab, you can click `Deploy` button to deploy the application.
|
||||||
|
|
||||||
|
### Deploy Application
|
||||||
|
|
||||||
|
|
||||||
|
After application created and bond with an environment, you can deploy the application instance.
|
||||||
|
|
||||||
|
#### First time deploy
|
||||||
|
|
||||||
|
You can view the application detail page by click the application name or the UI card.
|
||||||
|
|
||||||
|
The tabs on the right side of the `Baseline Config` are environments which bond by the application. Choose one of the environment you want to deploy. Click that tab, you'll see the picture below.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
If this is the first time deploy, you'll see the Deploy button in the middle of the environment page, just click the `Deploy` button to deploy.
|
||||||
|
|
||||||
|
Then the workflow start to running, you can see the workflow status on the top right corner.
|
||||||
|
|
||||||
|
If you have configured a suspend workflow step, it will run and stop in that state. It will wait until you have checked your application well and click the approve button.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
If there's something wrong with the workflow step, the workflow node will become red. Move your mouse to hover that area, you'll see the error reason.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Upgrade the application
|
||||||
|
|
||||||
|
There's a `Deploy` button on the top right corner, you can click that for deploy. On the right side of the button, there's detail button, you can choose which workflow to run if there's multiple environments configured.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
You can upgrade the application in any state, as KubeVela is a declarative system. There will be a kindly reminder for you if the workflow is running when you want to upgrade.
|
||||||
|
|
||||||
|
### Check Application State
|
||||||
|
|
||||||
|
Different tabs of environment will show different application instances inside.
|
||||||
|
|
||||||
|
By default, it will display all instances deployed in the environment, you can filter the status by select targets.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, check the application pod details by click the expand button("+") on the left. You can view the pod status including the events and error message about it.
|
||||||
|
|
||||||
|
For cloud resources, there will be a link to the cloud console for management.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### View Application Logs
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
You can view the logs of application in the environment tab.
|
||||||
|
|
||||||
|
By default, the logs will refresh every 5s. If your logs didn't have timestamp, you can click the `Show timestamps` to see.
|
||||||
|
|
||||||
|
You can also view logs from command line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
vela logs <app_name> -n <namespace>
|
||||||
|
```
|
||||||
|
|
||||||
|
Select a workload to view the logs.
|
||||||
|
|
||||||
|
|
||||||
|
### Expose your application for public access
|
||||||
|
|
||||||
|
You can configure your application for public access.
|
||||||
|
|
||||||
|
There're mainly three ways to expose your service.
|
||||||
|
|
||||||
|
1. Choose `webservice` Type and configure the service type to be `LoadBalancer` or `NodePort`.
|
||||||
|
2. Configure `gateway` trait, it works for `webservice`, `worker` and `task` component types. `gateway` trait must configure a domain and works only for HTTP/HTTPs protocols.
|
||||||
|
3. Case by case component configurations.
|
||||||
|
|
||||||
|
#### Expose service for `webservice` typed component
|
||||||
|
|
||||||
|
You can modify `ExposeType` to choose the way, and you should configure the `Service Ports` to listen the ports and turn on the `Expose` radio.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Add `gateway` trait
|
||||||
|
|
||||||
|
The `gateway` trait requires you have `Ingress Controller` available in your cluster. You can add this trait to expose your service and configure a domain.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, the `Domain` field configure your domain, please configure your DNS for domain to route to the Kubernetes cluster gateway IP.
|
||||||
|
|
||||||
|
In the `Http` section, you can configure the routing rules. For example, set `/`:`80` means the domain index page will route to the port `80`. You can configure this rule as you need.
|
||||||
|
|
||||||
|
Other component types can also be able to configure the service expose, but they're usually case by case, especially for helm charts.
|
||||||
|
|
||||||
|
### Get the service endpoint
|
||||||
|
|
||||||
|
After the application deployed with service exposed configuration, you can see a `Service Endpoint` button on the left of the `Recycle` button. You'll see the endpoint when hover your mouse there.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### List Resources Created
|
||||||
|
|
||||||
|
If you want to learn the resources created by the applications, you can open the environment status page.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
There're three kinds of information including `Applied Resources`,`Conditions` and `Component Status`. The `Applied Resources` are all resources created by the applications.
|
||||||
|
|
||||||
|
You can also list resources from command line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela status <app_name> -n <namespace> --tree
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recycle Application Instance
|
||||||
|
|
||||||
|
When you want to delete the application instance in some environment, you can click the `Recycle` button in that environment.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
It will delete the whole application instance with related resources.
|
||||||
|
|
||||||
|
> Note that recycle means delete an application, data can't be recovered automatically. Please make sure you have back up all the important data of this instance before recycle it.
|
||||||
|
|
||||||
|
### Delete Application
|
||||||
|
|
||||||
|
After all application instance were recycled, you can click `Remove` for deletion.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, the `Remove` button is hidden in the application detail.
|
||||||
|
|
||||||
|
Now you have learned the basic lifecycle of an application.
|
||||||
|
|
@ -15,33 +15,63 @@ For connecting the ACK clusters, the platform will save some cloud info, Region,
|
||||||
|
|
||||||
## Manage the cluster via CLI
|
## Manage the cluster via CLI
|
||||||
|
|
||||||
### vela cluster list
|
|
||||||
|
|
||||||
This command could list all clusters managed by KubeVela currently.
|
|
||||||
```bash
|
|
||||||
$ vela cluster list
|
|
||||||
CLUSTER TYPE ENDPOINT
|
|
||||||
CLUSTER ALIAS TYPE ENDPOINT ACCEPTED LABELS
|
|
||||||
local Internal - true
|
|
||||||
ask-beijing X509Certificate https://*.*.*.*:6443 true
|
|
||||||
```
|
|
||||||
|
|
||||||
### vela cluster join
|
### vela cluster join
|
||||||
|
|
||||||
This command can join new cluster into KubeVela and name it as `cluster-prod`. The joined cluster can be used in [Multi-Environment Deployment](../../end-user/policies/envbinding).
|
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
|
||||||
|
|
||||||
```shell script
|
```shell script
|
||||||
$ vela cluster join example-cluster.kubeconfig --name cluster-prod
|
vela cluster join <your kubeconfig path>
|
||||||
|
```
|
||||||
|
|
||||||
|
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
|
||||||
|
you can also specify the name by `--name` parameter. For example:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ vela cluster join beijing.kubeconfig --name beijing
|
||||||
|
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
|
||||||
|
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
|
||||||
|
```
|
||||||
|
|
||||||
|
### vela cluster list
|
||||||
|
|
||||||
|
After clusters joined, you could list all clusters managed by KubeVela.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela cluster list
|
||||||
|
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
||||||
|
local Internal - true
|
||||||
|
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
||||||
|
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true
|
||||||
|
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
|
||||||
|
```
|
||||||
|
|
||||||
|
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
||||||
|
|
||||||
|
### label your cluster
|
||||||
|
|
||||||
|
You can also give labels to your clusters, which helps you select clusters for deploying applications.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
|
||||||
|
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
|
||||||
|
$ vela cluster list
|
||||||
|
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
||||||
|
local Internal - true
|
||||||
|
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
||||||
|
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
|
||||||
|
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
|
||||||
```
|
```
|
||||||
|
|
||||||
### vela cluster detach
|
### vela cluster detach
|
||||||
|
|
||||||
This command can be used to detach cluster from KubeVela.
|
You can also detach a cluster if you do not want to use it anymore.
|
||||||
|
|
||||||
```shell script
|
```shell script
|
||||||
$ vela cluster detach cluster-prod
|
$ vela cluster detach beijing
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
|
||||||
|
|
||||||
### vela cluster rename
|
### vela cluster rename
|
||||||
|
|
||||||
This command can rename cluster managed by KubeVela.
|
This command can rename cluster managed by KubeVela.
|
||||||
|
|
|
||||||
|
|
@ -128,7 +128,3 @@ Services:
|
||||||
```
|
```
|
||||||
|
|
||||||
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
|
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
|
||||||
|
|
||||||
## Next step
|
|
||||||
|
|
||||||
- [Deploy Kubernetes Objects](./k8s-object)
|
|
||||||
|
|
|
||||||
|
|
@ -11,13 +11,6 @@ KubeVela supports you to render, orchestrate and deploy Kubernetes objects. The
|
||||||
3. Multi-env/cluster in application delivery.
|
3. Multi-env/cluster in application delivery.
|
||||||
4. The control loop of application deployment: Rollback, Terminate and Continue.
|
4. The control loop of application deployment: Rollback, Terminate and Continue.
|
||||||
|
|
||||||
What's more, you can even distribute existing Kubernetes objects with KubeVela in the following scenarios:
|
|
||||||
|
|
||||||
- Copying secrets from the hub cluster into managed clusters.
|
|
||||||
- Promote deployments from canary clusters into production clusters.
|
|
||||||
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
|
|
||||||
|
|
||||||
|
|
||||||
## Before starting
|
## Before starting
|
||||||
|
|
||||||
- Prepare a Deployment+Service yaml config resource.
|
- Prepare a Deployment+Service yaml config resource.
|
||||||
|
|
@ -197,104 +190,4 @@ $ vela up -f https://kubevela.io/example/applications/app-with-k8s-objects.yaml
|
||||||
$ vela workflow resume app-with-k8s-objects
|
$ vela workflow resume app-with-k8s-objects
|
||||||
```
|
```
|
||||||
|
|
||||||
## Distributed External Kubernetes Objects
|
|
||||||
|
|
||||||
> This section requires you to know how to deploy multi-cluster application with policy and workflow first. You can refer to [Multi-cluster Application Delivery](../case-studies/multi-cluster) for details.
|
|
||||||
|
|
||||||
|
|
||||||
### Refer to Existing Kubernetes Objects in Component
|
|
||||||
|
|
||||||
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-example
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: image-pull-secrets
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: secret
|
|
||||||
name: image-credential-to-copy
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-clusters
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusterLabelSelector:
|
|
||||||
region: hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
### Details for the *ref-objects* typed component
|
|
||||||
|
|
||||||
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
|
|
||||||
|
|
||||||
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
|
|
||||||
|
|
||||||
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-duplicate-deployments
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: duplicate-deployment
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: deployment
|
|
||||||
cluster: hangzhou-1
|
|
||||||
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
|
|
||||||
labelSelector:
|
|
||||||
need-duplicate: "true"
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-2
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusters: ["hangzhou-2"]
|
|
||||||
```
|
|
||||||
|
|
||||||
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
|
|
||||||
|
|
||||||
### Working with Trait
|
|
||||||
|
|
||||||
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-multiple-resources
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: nginx-ref-multiple-resources
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: deployment
|
|
||||||
- resource: service
|
|
||||||
traits:
|
|
||||||
- type: scaler
|
|
||||||
properties:
|
|
||||||
replicas: 3
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-clusters
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusterLabelSelector:
|
|
||||||
region: hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
Congrats! Now you've learned how to deploy Kubernetes objects.
|
Congrats! Now you've learned how to deploy Kubernetes objects.
|
||||||
|
|
||||||
## Next step
|
|
||||||
|
|
||||||
- [Deploy Cloud Service](./consume-cloud-services)
|
|
||||||
- [Distributed External Kubernetes Objects](../end-user/components/ref-objects)
|
|
||||||
|
|
|
||||||
|
|
@ -119,7 +119,3 @@ Services:
|
||||||
|
|
||||||
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
|
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
|
||||||
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
|
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
|
||||||
|
|
||||||
## Next Step
|
|
||||||
|
|
||||||
[Learn to deploy Helm Chart](./helm)
|
|
||||||
|
|
|
||||||
30
sidebars.js
30
sidebars.js
|
|
@ -33,7 +33,6 @@ module.exports = {
|
||||||
'end-user/traits/rollout',
|
'end-user/traits/rollout',
|
||||||
'end-user/traits/ingress',
|
'end-user/traits/ingress',
|
||||||
'end-user/traits/sidecar',
|
'end-user/traits/sidecar',
|
||||||
'tutorials/k8s-object',
|
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
|
@ -59,6 +58,7 @@ module.exports = {
|
||||||
collapsed: true,
|
collapsed: true,
|
||||||
items: [
|
items: [
|
||||||
'tutorials/k8s-object',
|
'tutorials/k8s-object',
|
||||||
|
'end-user/components/ref-objects',
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
|
@ -73,23 +73,9 @@ module.exports = {
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
'How-to manage the applications': [
|
'General CD Features': [
|
||||||
'how-to/dashboard/application/create-application',
|
'how-to/dashboard/application/create-application',
|
||||||
'how-to/dashboard/application/bind-new-environment',
|
|
||||||
'tutorials/workflows',
|
'tutorials/workflows',
|
||||||
'how-to/dashboard/application/deploy-application',
|
|
||||||
'how-to/dashboard/application/get-application-instance',
|
|
||||||
'tutorials/scaler',
|
|
||||||
'how-to/dashboard/application/get-application-log',
|
|
||||||
'how-to/dashboard/application/get-application-endpoint',
|
|
||||||
'how-to/dashboard/application/view-application-resource',
|
|
||||||
'how-to/dashboard/application/get-application-revision',
|
|
||||||
'how-to/dashboard/application/recycle-environment',
|
|
||||||
'how-to/dashboard/application/delete-application',
|
|
||||||
],
|
|
||||||
},
|
|
||||||
{
|
|
||||||
'Advanced Features': [
|
|
||||||
'end-user/workflow/component-dependency-parameter',
|
'end-user/workflow/component-dependency-parameter',
|
||||||
'end-user/version-control',
|
'end-user/version-control',
|
||||||
'end-user/policies/apply-once',
|
'end-user/policies/apply-once',
|
||||||
|
|
@ -177,7 +163,19 @@ module.exports = {
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
type: 'category',
|
||||||
|
label: 'Developer Guide',
|
||||||
|
collapsed: true,
|
||||||
|
items: [
|
||||||
'contributor/overview',
|
'contributor/overview',
|
||||||
|
'contributor/non-code-contribute',
|
||||||
|
'contributor/code-contribute',
|
||||||
|
'contributor/release-process',
|
||||||
|
'contributor/code-conventions',
|
||||||
|
'contributor/principle-of-test',
|
||||||
|
],
|
||||||
|
},
|
||||||
{
|
{
|
||||||
type: 'category',
|
type: 'category',
|
||||||
label: 'References',
|
label: 'References',
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
title: Multi-Cluster Delivery
|
title: Deploy across Multi-Clusters
|
||||||
---
|
---
|
||||||
|
|
||||||
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
|
KubeVela is by design a full functional Continuous Delivery (CD) platform with fine grained support for hybrid/multi-cloud/multi-cluster deployment.
|
||||||
|
|
@ -17,22 +17,10 @@ The following guide will introduce how to manage applications across clusters on
|
||||||
|
|
||||||
## Preparation
|
## Preparation
|
||||||
|
|
||||||
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
|
Please make sure you have clusters in your control plane, in general, this work should be done by operator engineers.
|
||||||
|
If you're a DevOps engineer or trying KubeVela, you can refer to [manage cluster docs](../platform-engineers/system-operation/managing-clusters) to learn how to join clusters.
|
||||||
|
|
||||||
```shell script
|
For the rest docs, we assume you have clusters with the following names:
|
||||||
vela cluster join <your kubeconfig path>
|
|
||||||
```
|
|
||||||
|
|
||||||
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
|
|
||||||
you can also specify the name by `--name` parameter. For example:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ vela cluster join beijing.kubeconfig --name beijing
|
|
||||||
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
|
|
||||||
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
|
|
||||||
```
|
|
||||||
|
|
||||||
After clusters joined, you could list all clusters managed by KubeVela.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ vela cluster list
|
$ vela cluster list
|
||||||
|
|
@ -45,27 +33,6 @@ cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
|
||||||
|
|
||||||
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
||||||
|
|
||||||
You can also detach a cluster if you do not want to use it anymore.
|
|
||||||
|
|
||||||
```shell script
|
|
||||||
$ vela cluster detach beijing
|
|
||||||
```
|
|
||||||
|
|
||||||
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
|
|
||||||
|
|
||||||
You can also give labels to your clusters, which helps you select clusters for deploying applications.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
|
|
||||||
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
|
|
||||||
$ vela cluster list
|
|
||||||
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
|
||||||
local Internal - true
|
|
||||||
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
|
||||||
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
|
|
||||||
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
## Deliver Application to Clusters
|
## Deliver Application to Clusters
|
||||||
|
|
||||||
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
|
To deliver your application into multiple clusters, you simply need to configure which clusters you want to deploy through the `topology` policy. For example, you can deploy an nginx webservice in hangzhou clusters by running the following commands
|
||||||
|
|
@ -530,7 +497,3 @@ If you already have applications running in production environment and do not wa
|
||||||
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
|
In this section, we introduced how KubeVela delivering micro services in multiple clusters, the whole process can be easily modeled as a declarative deployment plan.
|
||||||
|
|
||||||
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
|
No more add-hoc scripts or glue code, KubeVela will get the application delivery workflow done with full automation and determinism. Most importantly, KubeVela expects you keep using the CI solutions you are already familiar with and KubeVela is fully complementary to them as the CD control plane.
|
||||||
|
|
||||||
## Next Step
|
|
||||||
|
|
||||||
* Refer to more examples about [integrating with Jenkins](../tutorials/jenkins).
|
|
||||||
|
|
@ -0,0 +1,360 @@
|
||||||
|
---
|
||||||
|
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+
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Install Kubebuilder manually</summary>
|
||||||
|
|
||||||
|
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/
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 #<issue number>` or `Fixes #<issue number>`.
|
||||||
|
- To avoid regressions, the pull request should include tests that replicate the fixed bug.
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>[optional scope]: <subject>
|
||||||
|
|
||||||
|
[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
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `<type>` (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 `<type>` to make sure the subject line is capitalized. `<type>` 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
|
||||||
|
|
||||||
|
#### `<scope>` (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.
|
||||||
|
|
||||||
|
#### `<subject>` (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".
|
||||||
|
|
||||||
|
#### `<body>` (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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
@ -0,0 +1,179 @@
|
||||||
|
---
|
||||||
|
title: Code Conventions
|
||||||
|
---
|
||||||
|
|
||||||
|
In this section, you will find the code conventions for all kinds of code KubeVela project related. It's not necessary to learn all of them at once, but make sure you have read corresponding parts before you start to code.
|
||||||
|
|
||||||
|
- [Go Code Conventions](#go-code-conventions)
|
||||||
|
- [Bash or Script Conventions](#bash-or-script-conventions)
|
||||||
|
- [API Conventions](#api-conventions)
|
||||||
|
- [Testing Conventions](#testing-conventions)
|
||||||
|
- [Directory and File Conventions](#directory-and-file-conventions)
|
||||||
|
- [Logging Conventions](#logging-conventions)
|
||||||
|
|
||||||
|
## Go Code Conventions
|
||||||
|
|
||||||
|
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
|
||||||
|
|
||||||
|
- [Effective Go](https://golang.org/doc/effective_go.html)
|
||||||
|
|
||||||
|
- Know and avoid [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f)
|
||||||
|
|
||||||
|
- Comment your code.
|
||||||
|
- [Go's commenting conventions](http://blog.golang.org/godoc-documenting-go-code)
|
||||||
|
- If reviewers ask questions about why the code is the way it is, that's a
|
||||||
|
sign that comments might be helpful.
|
||||||
|
|
||||||
|
- Command-line flags should use dashes, not underscores
|
||||||
|
|
||||||
|
- API
|
||||||
|
- According to RFC3986, URLs are "case sensitive". KubeVela uses snake_case for API URLs.
|
||||||
|
- e.g.: `POST /v1/cloud_clusters`
|
||||||
|
|
||||||
|
- Naming
|
||||||
|
- Please consider package name when selecting an interface name, and avoid
|
||||||
|
redundancy.
|
||||||
|
|
||||||
|
- e.g.: `storage.Interface` is better than `storage.StorageInterface`.
|
||||||
|
|
||||||
|
- Do not use uppercase characters, underscores, or dashes in package
|
||||||
|
names.
|
||||||
|
- Please consider parent directory name when choosing a package name.
|
||||||
|
|
||||||
|
- so pkg/controllers/autoscaler/foo.go should say `package autoscaler`
|
||||||
|
not `package autoscalercontroller`.
|
||||||
|
- Unless there's a good reason, the `package foo` line should match
|
||||||
|
the name of the directory in which the .go file exists.
|
||||||
|
- Importers can use a different name if they need to disambiguate.
|
||||||
|
|
||||||
|
- Locks should be called `lock` and should never be embedded (always `lock
|
||||||
|
sync.Mutex`). When multiple locks are present, give each lock a distinct name
|
||||||
|
following Go conventions - `stateLock`, `mapLock` etc.
|
||||||
|
|
||||||
|
## Bash or Script Conventions
|
||||||
|
|
||||||
|
- https://google.github.io/styleguide/shell.xml
|
||||||
|
|
||||||
|
- Ensure that build, release, test, and cluster-management scripts run on
|
||||||
|
macOS
|
||||||
|
|
||||||
|
## API Conventions
|
||||||
|
|
||||||
|
- KubeVela follows the Kubernetes conventions
|
||||||
|
|
||||||
|
- [API changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md)
|
||||||
|
|
||||||
|
- [API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md)
|
||||||
|
|
||||||
|
## Testing Conventions
|
||||||
|
|
||||||
|
- All new packages and most new significant functionality must come with unit
|
||||||
|
tests
|
||||||
|
|
||||||
|
- Table-driven tests are preferred for testing multiple scenarios/inputs; for
|
||||||
|
example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
|
||||||
|
|
||||||
|
- Unit tests must pass on macOS and Windows platforms - if you use Linux
|
||||||
|
specific features, your test case must either be skipped on windows or compiled
|
||||||
|
out (skipped is better when running Linux specific commands, compiled out is
|
||||||
|
required when your code does not compile on Windows).
|
||||||
|
|
||||||
|
- Avoid waiting for a short amount of time (or without waiting) and expect an
|
||||||
|
asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
|
||||||
|
running). Wait and retry instead.
|
||||||
|
|
||||||
|
- Significant features should come with integration (test/integration) and/or
|
||||||
|
end-to-end (e2e/) tests.
|
||||||
|
|
||||||
|
- Including new vela cli commands and major features of existing commands
|
||||||
|
|
||||||
|
Please refer to [the principle of test](./principle-of-test) for more details.
|
||||||
|
|
||||||
|
## Directory and file Conventions
|
||||||
|
|
||||||
|
- Avoid package sprawl. Find an appropriate subdirectory for new packages.
|
||||||
|
- Libraries with no more appropriate home belong in new package
|
||||||
|
subdirectories of pkg/util
|
||||||
|
|
||||||
|
- Avoid general utility packages. Packages called "util" are suspect. Instead,
|
||||||
|
derive a name that describes your desired function. For example, the utility
|
||||||
|
functions dealing with waiting for operations are in the "wait" package and
|
||||||
|
include functionality like Poll. So the full name is wait.Poll
|
||||||
|
|
||||||
|
- All filenames should be lowercase
|
||||||
|
|
||||||
|
- Go source files and directories use underscores, not dashes
|
||||||
|
- Package directories should generally avoid using separators as much as
|
||||||
|
possible (when packages are multiple words, they usually should be in nested
|
||||||
|
subdirectories).
|
||||||
|
|
||||||
|
- Document directories and filenames should use dashes rather than underscores
|
||||||
|
|
||||||
|
- Contrived examples that illustrate system features belong in
|
||||||
|
`/docs/user-guide` or `/docs/admin`, depending on whether it is a feature primarily
|
||||||
|
intended for users that deploy applications or cluster administrators,
|
||||||
|
respectively. Actual application examples belong in /examples.
|
||||||
|
- Examples should also illustrate [best practices for configuration and using the system](https://kubernetes.io/docs/concepts/configuration/overview/)
|
||||||
|
|
||||||
|
- Third-party code
|
||||||
|
|
||||||
|
- Go code for normal third-party dependencies is managed using
|
||||||
|
[go modules](https://github.com/golang/go/wiki/Modules)
|
||||||
|
|
||||||
|
- Other third-party code belongs in `/third_party`
|
||||||
|
- forked third party Go code goes in `/third_party/forked`
|
||||||
|
- forked _golang stdlib_ code goes in `/third_party/forked/golang`
|
||||||
|
|
||||||
|
- Third-party code must include licenses
|
||||||
|
|
||||||
|
- This includes modified third-party code and excerpts, as well
|
||||||
|
|
||||||
|
## Logging Conventions
|
||||||
|
|
||||||
|
### Structured logging
|
||||||
|
|
||||||
|
We recommend using `klog.InfoS` to structure the log. The `msg` argument need start from a capital letter.
|
||||||
|
and name arguments should always use lowerCamelCase.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// func InfoS(msg string, keysAndValues ...interface{})
|
||||||
|
klog.InfoS("Reconcile traitDefinition", "traitDefinition", klog.KRef(req.Namespace, req.Name))
|
||||||
|
// output:
|
||||||
|
// I0605 10:10:57.308074 22276 traitdefinition_controller.go:59] "Reconcile traitDefinition" traitDefinition="vela-system/expose"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Use `klog.KObj` and `klog.KRef` for Kubernetes objects
|
||||||
|
|
||||||
|
`klog.KObj` and `klog.KRef` can unify the output of kubernetes object.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// KObj is used to create ObjectRef when logging information about Kubernetes objects
|
||||||
|
klog.InfoS("Start to reconcile", "appDeployment", klog.KObj(appDeployment))
|
||||||
|
// KRef is used to create ObjectRef when logging information about Kubernetes objects without access to metav1.Object
|
||||||
|
klog.InfoS("Reconcile application", "application", klog.KRef(req.Namespace, req.Name))
|
||||||
|
```
|
||||||
|
|
||||||
|
### Logging Level
|
||||||
|
|
||||||
|
[This file](https://github.com/kubevela/kubevela/blob/master/pkg/controller/common/logs.go) contains KubeVela's log level,
|
||||||
|
you can set the log level by `klog.V(level)`.
|
||||||
|
|
||||||
|
```golang
|
||||||
|
// you can use klog.V(common.LogDebug) to print debug log
|
||||||
|
klog.V(common.LogDebug).InfoS("Successfully applied components", "workloads", len(workloads))
|
||||||
|
```
|
||||||
|
|
||||||
|
Looking for more details in [Structured Logging Guide](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md#structured-logging-in-kubernetes).
|
||||||
|
|
||||||
|
|
||||||
|
## Linting and formatting
|
||||||
|
|
||||||
|
To ensure consistency across the Go codebase, we require all code to pass a number of linter checks.
|
||||||
|
|
||||||
|
To run all linters, use the `reviewable` Makefile target:
|
||||||
|
|
||||||
|
```shell script
|
||||||
|
make reviewable
|
||||||
|
```
|
||||||
|
|
||||||
|
The command will clean code along with some lint checks. Please remember to check in all changes after that.
|
||||||
|
|
@ -0,0 +1,53 @@
|
||||||
|
---
|
||||||
|
title: Non-code Contribution Guide
|
||||||
|
---
|
||||||
|
|
||||||
|
You can pick up any of the following ways you're interested to contribute.
|
||||||
|
|
||||||
|
## Contribute Use cases and Samples
|
||||||
|
|
||||||
|
* If you're using KubeVela, the easiest thing to contribute is to [credit the community](https://github.com/kubevela/kubevela/issues/1662).
|
||||||
|
|
||||||
|
* If you are interested, you can also write a [kubevela.io blog](https://kubevela.net/blog) to tell more about the use case.
|
||||||
|
|
||||||
|
* You can also contribute to [KubeVela Official Samples](https://github.com/kubevela/samples).
|
||||||
|
|
||||||
|
|
||||||
|
## Report bugs
|
||||||
|
|
||||||
|
Before submitting a new issue, try to make sure someone hasn't already reported the problem.
|
||||||
|
Look through the [existing issues](https://github.com/kubevela/kubevela/issues) for similar issues.
|
||||||
|
|
||||||
|
Report a bug by submitting a [bug report](https://github.com/kubevela/kubevela/issues/new?assignees=&labels=kind%2Fbug&template=bug_report.md&title=).
|
||||||
|
Make sure that you provide as much information as possible on how to reproduce the bug.
|
||||||
|
|
||||||
|
Follow the issue template and add additional information that will help us replicate the problem.
|
||||||
|
|
||||||
|
### Security issues
|
||||||
|
|
||||||
|
If you believe you've found a security vulnerability, please read our [security policy](https://github.com/kubevela/kubevela/blob/master/SECURITY.md) for more details.
|
||||||
|
|
||||||
|
## Suggest enhancements
|
||||||
|
|
||||||
|
If you have an idea to improve KubeVela, submit an [feature request](https://github.com/kubevela/kubevela/issues/new?assignees=&labels=kind%2Ffeature&template=feature_request.md&title=%5BFeature%5D).
|
||||||
|
|
||||||
|
## Triage issues
|
||||||
|
|
||||||
|
If you don't have the knowledge or time to code, consider helping with _issue triage_. The community will thank you for saving them time by spending some of yours.
|
||||||
|
|
||||||
|
Read more about the ways you can [Triage issues](https://github.com/kubevela/community/blob/main/ISSUE_TRIAGE.md).
|
||||||
|
|
||||||
|
## Answering questions
|
||||||
|
|
||||||
|
If you have a question and you can't find the answer in the [documentation](https://kubevela.io/docs/),
|
||||||
|
the next step is to ask it on the [github discussion](https://github.com/kubevela/kubevela/discussions).
|
||||||
|
|
||||||
|
It's important to us to help these users, and we'd love your help. You can help other KubeVela users by answering [their questions](https://github.com/kubevela/kubevela/discussions).
|
||||||
|
|
||||||
|
## Contribute to the Docs
|
||||||
|
|
||||||
|
Contributing to the docs needs to learn some knowledge about how to make a pull request to Github, I think this won't be hard if you follow the guide.
|
||||||
|
|
||||||
|
* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md)
|
||||||
|
|
||||||
|
For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/).
|
||||||
|
|
@ -1,35 +1,49 @@
|
||||||
---
|
---
|
||||||
title: Developer Guide
|
title: Introduction
|
||||||
---
|
---
|
||||||
|
|
||||||
Welcome developers out there! Please check the [Community Membership](https://github.com/kubevela/community/blob/main/community-membership.md) to start engaging with the community.
|
KubeVela project is initialized and maintained by the cloud native community since day 0 with [bootstrapping contributors from 8+ different organizations](https://github.com/kubevela/community/blob/main/OWNERS.md#bootstrap-contributors). We intend for KubeVela to have an open governance since the very beginning and donate the project to neutral foundation as soon as it's released.
|
||||||
|
|
||||||
## Common Code Contribution Guide
|
To help us create a safe and positive community experience for all, we require all participants adhere to the CNCF Community [Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
|
||||||
|
|
||||||
* [Create a pull request](https://github.com/kubevela/kubevela/blob/master/contribute/create-pull-request.md)
|
This document is a guide to help you through the process of contributing to KubeVela.
|
||||||
* [Developer guide](https://github.com/kubevela/kubevela/blob/master/contribute/developer-guide.md)
|
|
||||||
* [Triage issues](https://github.com/kubevela/kubevela/blob/master/contribute/triage-issues.md)
|
|
||||||
* [Code conventions](https://github.com/kubevela/kubevela/blob/master/contribute/coding-conventions.md)
|
|
||||||
* [Release Process And Cadence](https://github.com/kubevela/kubevela/blob/master/contribute/develop-code-flow.pdf)
|
|
||||||
|
|
||||||
## Contribute Addons
|
## Become a contributor
|
||||||
|
|
||||||
|
You can contribute to KubeVela in several ways including code and non-code contributions,
|
||||||
|
we appreciate every effort you contribute to the community. Here are some examples:
|
||||||
|
|
||||||
|
* Contribute to the codebase and docs.
|
||||||
|
* Report and triage issues.
|
||||||
|
* Organize meetups and user groups in your local area.
|
||||||
|
* Help others by answering questions about KubeVela.
|
||||||
|
|
||||||
|
### Non-code contribution
|
||||||
|
|
||||||
|
The Apache way says "Community Over Code". Although KubeVela is a CNCF/Linux project, we possess a strong resonance to it. To second and stretch this merit deeper, we regard non-coding contribution as equally important with code contribution for the community's very existence and its future growth.
|
||||||
|
|
||||||
|
- Refer to [Non-code Contribution Guide](./non-code-contribute) to know how you could help.
|
||||||
|
|
||||||
|
### Code contribution
|
||||||
|
|
||||||
|
Unsure where to begin contributing to KubeVela codebase? Start by browsing issues labeled `good first issue` or `help wanted`.
|
||||||
|
|
||||||
|
- [Good first issue](https://github.com/kubevela/kubevela/labels/good%20first%20issue) issues are generally straightforward to complete.
|
||||||
|
- [Help wanted](https://github.com/kubevela/kubevela/labels/help%20wanted) issues are problems we would like the community to help us with regardless of complexity.
|
||||||
|
- Refer to [Code Contribution Guide](./code-contribute) for more details.
|
||||||
|
|
||||||
|
Learn the [Release Process And Cadence](https://github.com/kubevela/kubevela/blob/master/contribute/develop-code-flow.pdf) to know when your code changes will be released.
|
||||||
|
|
||||||
|
|
||||||
|
## Become a community member
|
||||||
|
|
||||||
|
If you're interested to become a community member or learn more about the governance, please check the [community membership](https://github.com/kubevela/community/blob/main/community-membership.md) for details.
|
||||||
|
|
||||||
|
|
||||||
|
## Contribute Addons and related projects
|
||||||
|
|
||||||
* [Build Your Own Addon](../platform-engineers/addon/intro)
|
* [Build Your Own Addon](../platform-engineers/addon/intro)
|
||||||
* [Addon Repository](https://github.com/kubevela/catalog)
|
* [Addon Repository](https://github.com/kubevela/catalog)
|
||||||
|
|
||||||
## Contribute to the Docs & Website
|
|
||||||
|
|
||||||
* [kubevela.io Developer Guide](https://github.com/kubevela/kubevela.io/blob/main/README.md)
|
|
||||||
* [Update KubeVela.io CLI Reference Doc](./cli-ref-doc)
|
|
||||||
|
|
||||||
## Contribute use cases and more samples
|
|
||||||
|
|
||||||
* [Credit the community](https://github.com/kubevela/kubevela/issues/1662)
|
|
||||||
* [KubeVela Official Samples](https://github.com/kubevela/samples)
|
|
||||||
* [Add a blog](https://kubevela.net/blog)
|
|
||||||
|
|
||||||
## Other Projects
|
|
||||||
|
|
||||||
* [VelaUX Developer Guide](https://github.com/kubevela/velaux/blob/main/CONTRIBUTING.md)
|
* [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)
|
* [Terraform Controller Developer Guide](https://github.com/oam-dev/terraform-controller/blob/master/CONTRIBUTING.md)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,97 @@
|
||||||
|
---
|
||||||
|
title: Principle of Test
|
||||||
|
---
|
||||||
|
|
||||||
|
## Definition of concept
|
||||||
|
|
||||||
|
Generally, there are three types of test cases:
|
||||||
|
|
||||||
|
- unit test
|
||||||
|
- integration test, with mocking api for test
|
||||||
|
- end to end(e2e) test
|
||||||
|
|
||||||
|
Each of them brings us different gains and pains. We should follow the principles below for better development life.
|
||||||
|
|
||||||
|
## Unit Test
|
||||||
|
|
||||||
|
The main purposes of writing and maintaining unit tests are:
|
||||||
|
|
||||||
|
- Explicit: ensure that the function behavior meets the design expectations.
|
||||||
|
- Implicit: facilitates more reasonable code structure and interface-oriented programming.
|
||||||
|
|
||||||
|
Test target of a unit test is a class or a segment of algorithm code. In theory, functions with relatively independent logic should has at least one unit test case (except for getter and setter).
|
||||||
|
|
||||||
|
Basic principles for writing a single test are:
|
||||||
|
|
||||||
|
- Keep It Simple and Stupid.
|
||||||
|
- One case covers only one scenario.
|
||||||
|
- Mock tools (such as golang/mock) are powerful, but **NOT recommended**. When you think you have to introduce mocking to unit test, what you really need is Integration test or event e2e test。
|
||||||
|
|
||||||
|
Single test requires high efficiency. For example, during code refactoring, after a function logic is modified, unit test of the entire module may be triggered to ensure that the modification meets expectations.
|
||||||
|
|
||||||
|
## Integration Test
|
||||||
|
|
||||||
|
The propose of integration test is to setup parts of highly associated modules in a system, test is to ensure the interaction between modules within expectations.
|
||||||
|
|
||||||
|
Let's use an example to learn how it works. In KubeVela project, integration tests are mainly divided into two categories:
|
||||||
|
|
||||||
|
- The vela core controller. You need to add corresponding tests for major processes such as render, orchestrate, and deploy the CRD results into Kubernetes. In this case, you will have a mock server for Kubernetes API, then you can add tests to cover all these automated logic without the real Kubernetes and the other CRD controllers running.
|
||||||
|
- Addons, such as velaux, apiserver and cli. You can add corresponding tests like creating, destroying, and updating an Application without the controller really acting.
|
||||||
|
|
||||||
|
Integration test of the core part don't care about how CRD working. Therefore, it can mock the CRD controller behavior to speed up the test efficiency. While the outside CLI don't care about how applications acted, they just not to ensure the application has the correct spec.
|
||||||
|
|
||||||
|
## E2E Test
|
||||||
|
|
||||||
|
The propose of e2e test is to simulate the user's real behavior, suitable for verification of the whole project.
|
||||||
|
|
||||||
|
We recommend e2e test to be added in the following situations:
|
||||||
|
|
||||||
|
- To interact with upstream and downstream projects, for example:
|
||||||
|
1. The application controller should interact with rollout and workload for progressive rollout.
|
||||||
|
1. The CLI relies on the controller to response for next actions in one command.
|
||||||
|
- Core Feature/Scenario: each core feature or scenario must has at least one e2e test case.
|
||||||
|
|
||||||
|
## Best Practice
|
||||||
|
|
||||||
|
The purpose of the test is to ensure the quality of continuous software delivery, with emphasis on the word "continuous". It is necessary to ensure not only the quality of the current delivery, but also the quality of future software delivery. It is particularly important to make good use of the respective advantages of the three test types and combine them to ensure the overall quality of the software.
|
||||||
|
|
||||||
|
| | Time consumed Running | Test Stability | Can simulate User behavior |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| unittest | minimal | high | no |
|
||||||
|
| integration test | middium | middium | almost |
|
||||||
|
| e2e test | much | low | yes |
|
||||||
|
|
||||||
|
Time consumed running is easy to understand here. A larger scale of software ability one test covering, the more time environment preparation and case running will cost. As a result, the testing efficiency is also lower.
|
||||||
|
In terms of stability, the larger the case coverage scale is, the more problems it may encounter, and some of the problems are not the real bugs we want to discover, but merely noises. In simulating real user behavior, only e2e can cover end-to-end to ensure that the entire link can work together.
|
||||||
|
|
||||||
|
As for the long-term value, it refers to the value of the existing case in the continuous software iteration process. For unit test, during code refactoring, it is adjusted with the adjustment of class and function, the code base is consistent with the hot spots in software iteration and continues to evolve.
|
||||||
|
|
||||||
|
However, integration/e2e test is usually split into subsystem boundaries, whose external interfaces are relatively stable (there are very few functional changes during the software iteration of distributed systems, generally forward compatibility), integration/e2e test code base is relatively stable, which is very important in the future evolution of the system. It can timely discover whether new functions damage existing functions.
|
||||||
|
|
||||||
|
|
||||||
|
Combined with the characteristics of all three, the best way to balance is to comply with the pyramid model. The chassis is unittest, the middle is integration test, and the top layer is e2e.
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
\
|
||||||
|
/ \
|
||||||
|
/ \
|
||||||
|
/ \
|
||||||
|
/ e2e \
|
||||||
|
/----------
|
||||||
|
/ \
|
||||||
|
/intergeration\
|
||||||
|
/ \
|
||||||
|
/-----------------\
|
||||||
|
/ \
|
||||||
|
/ unit-test \
|
||||||
|
/ \
|
||||||
|
---------------------------
|
||||||
|
```
|
||||||
|
|
||||||
|
KubeVela would like to follow the 70/20/10 principle. that is, 70% unittest,20% integration test, and 10% e2e test. Each module has some differences. However, the higher the upper layer, the larger the test coverage, but the smaller the test case set. This pyramid model remains unchanged. The following situations need to be avoided:
|
||||||
|
|
||||||
|
- Inverted pyramid, all rely on e2e to build the test
|
||||||
|
- Funnel model, a large number of unit + e2e test, but no integration test
|
||||||
|
|
||||||
|
It's hard to keep the test quality as we mainly focus on features instead of the stability. But for all of our maintainers, it's our duty to keep the test in good quality to make the community running well in the long term.
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
---
|
||||||
|
title: Release Process And Cadence
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,5 +1,103 @@
|
||||||
---
|
---
|
||||||
title: Distributed External Kubernetes Objects
|
title: Multi-cluster Distribution
|
||||||
---
|
---
|
||||||
|
|
||||||
This docs has been migrated, please refer to the [k8s-objects docs](../../tutorials/k8s-object#distributed-external-kubernetes-objects).
|
> This section requires you to know the basics about how to deploy multi-cluster application with policy and workflow. You can refer to [Multi-cluster Delivery](../../case-studies/multi-cluster) for container images, they're working in the same way.
|
||||||
|
|
||||||
|
You can reference and distribute existing Kubernetes objects with KubeVela in the following scenarios:
|
||||||
|
|
||||||
|
- Copying secrets from the hub cluster into managed clusters.
|
||||||
|
- Promote deployments from canary clusters into production clusters.
|
||||||
|
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Refer to Existing Kubernetes Objects in Component
|
||||||
|
|
||||||
|
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-example
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: image-pull-secrets
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: secret
|
||||||
|
name: image-credential-to-copy
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-clusters
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusterLabelSelector:
|
||||||
|
region: hangzhou
|
||||||
|
```
|
||||||
|
|
||||||
|
### Details for the *ref-objects* typed component
|
||||||
|
|
||||||
|
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
|
||||||
|
|
||||||
|
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
|
||||||
|
|
||||||
|
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-duplicate-deployments
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: duplicate-deployment
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: deployment
|
||||||
|
cluster: hangzhou-1
|
||||||
|
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
|
||||||
|
labelSelector:
|
||||||
|
need-duplicate: "true"
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-2
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusters: ["hangzhou-2"]
|
||||||
|
```
|
||||||
|
|
||||||
|
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
|
||||||
|
|
||||||
|
### Working with Trait
|
||||||
|
|
||||||
|
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: core.oam.dev/v1beta1
|
||||||
|
kind: Application
|
||||||
|
metadata:
|
||||||
|
name: ref-objects-multiple-resources
|
||||||
|
namespace: examples
|
||||||
|
spec:
|
||||||
|
components:
|
||||||
|
- name: nginx-ref-multiple-resources
|
||||||
|
type: ref-objects
|
||||||
|
properties:
|
||||||
|
objects:
|
||||||
|
- resource: deployment
|
||||||
|
- resource: service
|
||||||
|
traits:
|
||||||
|
- type: scaler
|
||||||
|
properties:
|
||||||
|
replicas: 3
|
||||||
|
policies:
|
||||||
|
- name: topology-hangzhou-clusters
|
||||||
|
type: topology
|
||||||
|
properties:
|
||||||
|
clusterLabelSelector:
|
||||||
|
region: hangzhou
|
||||||
|
```
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
title: Create Application
|
title: Lifecycle of Application
|
||||||
description: create an application by kubevela dashboard
|
description: lifecycle of an application by kubevela dashboard
|
||||||
---
|
---
|
||||||
|
|
||||||
### Configure the basic information
|
### Configure the basic information
|
||||||
|
|
@ -30,8 +30,156 @@ Different component types are different significantly, you can fill in the forms
|
||||||
|
|
||||||
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
|
After you finished configuring the application, click "Submit" to create the application. This means the application configuration was saved.
|
||||||
|
|
||||||
You need to [bind environment](./bind-new-environment) for real deployment.
|
### Bind Application with Environment
|
||||||
|
|
||||||
### Next Step
|
We can specify bind with one or more environments before deploy.
|
||||||
|
|
||||||
* [Bind Application with Environment](./bind-new-environment)
|
After we have created application and configured the baseline well, we can bind an application with environment to deploy.
|
||||||
|
|
||||||
|
You can bind with one environment as `dev` environment for develop and debug. When everything works well, you can bind with the production environment.
|
||||||
|
|
||||||
|
The operation likes below:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, in the application management page, click `Bind Environment`, choose the environment prepared.
|
||||||
|
|
||||||
|
If there's no environment, you can click the `Create new environment` for creation.
|
||||||
|
|
||||||
|
After choose well, click the `submit` button, it will show the new environment created on the right side of the baseline config as a tab.
|
||||||
|
|
||||||
|
KubeVela will automatically generate the deploy workflow for the newly created environments.
|
||||||
|
|
||||||
|
In the environment tab, you can click `Deploy` button to deploy the application.
|
||||||
|
|
||||||
|
### Deploy Application
|
||||||
|
|
||||||
|
|
||||||
|
After application created and bond with an environment, you can deploy the application instance.
|
||||||
|
|
||||||
|
#### First time deploy
|
||||||
|
|
||||||
|
You can view the application detail page by click the application name or the UI card.
|
||||||
|
|
||||||
|
The tabs on the right side of the `Baseline Config` are environments which bond by the application. Choose one of the environment you want to deploy. Click that tab, you'll see the picture below.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
If this is the first time deploy, you'll see the Deploy button in the middle of the environment page, just click the `Deploy` button to deploy.
|
||||||
|
|
||||||
|
Then the workflow start to running, you can see the workflow status on the top right corner.
|
||||||
|
|
||||||
|
If you have configured a suspend workflow step, it will run and stop in that state. It will wait until you have checked your application well and click the approve button.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
If there's something wrong with the workflow step, the workflow node will become red. Move your mouse to hover that area, you'll see the error reason.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Upgrade the application
|
||||||
|
|
||||||
|
There's a `Deploy` button on the top right corner, you can click that for deploy. On the right side of the button, there's detail button, you can choose which workflow to run if there's multiple environments configured.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
You can upgrade the application in any state, as KubeVela is a declarative system. There will be a kindly reminder for you if the workflow is running when you want to upgrade.
|
||||||
|
|
||||||
|
### Check Application State
|
||||||
|
|
||||||
|
Different tabs of environment will show different application instances inside.
|
||||||
|
|
||||||
|
By default, it will display all instances deployed in the environment, you can filter the status by select targets.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, check the application pod details by click the expand button("+") on the left. You can view the pod status including the events and error message about it.
|
||||||
|
|
||||||
|
For cloud resources, there will be a link to the cloud console for management.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### View Application Logs
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
You can view the logs of application in the environment tab.
|
||||||
|
|
||||||
|
By default, the logs will refresh every 5s. If your logs didn't have timestamp, you can click the `Show timestamps` to see.
|
||||||
|
|
||||||
|
You can also view logs from command line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
vela logs <app_name> -n <namespace>
|
||||||
|
```
|
||||||
|
|
||||||
|
Select a workload to view the logs.
|
||||||
|
|
||||||
|
|
||||||
|
### Expose your application for public access
|
||||||
|
|
||||||
|
You can configure your application for public access.
|
||||||
|
|
||||||
|
There're mainly three ways to expose your service.
|
||||||
|
|
||||||
|
1. Choose `webservice` Type and configure the service type to be `LoadBalancer` or `NodePort`.
|
||||||
|
2. Configure `gateway` trait, it works for `webservice`, `worker` and `task` component types. `gateway` trait must configure a domain and works only for HTTP/HTTPs protocols.
|
||||||
|
3. Case by case component configurations.
|
||||||
|
|
||||||
|
#### Expose service for `webservice` typed component
|
||||||
|
|
||||||
|
You can modify `ExposeType` to choose the way, and you should configure the `Service Ports` to listen the ports and turn on the `Expose` radio.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Add `gateway` trait
|
||||||
|
|
||||||
|
The `gateway` trait requires you have `Ingress Controller` available in your cluster. You can add this trait to expose your service and configure a domain.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, the `Domain` field configure your domain, please configure your DNS for domain to route to the Kubernetes cluster gateway IP.
|
||||||
|
|
||||||
|
In the `Http` section, you can configure the routing rules. For example, set `/`:`80` means the domain index page will route to the port `80`. You can configure this rule as you need.
|
||||||
|
|
||||||
|
Other component types can also be able to configure the service expose, but they're usually case by case, especially for helm charts.
|
||||||
|
|
||||||
|
### Get the service endpoint
|
||||||
|
|
||||||
|
After the application deployed with service exposed configuration, you can see a `Service Endpoint` button on the left of the `Recycle` button. You'll see the endpoint when hover your mouse there.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### List Resources Created
|
||||||
|
|
||||||
|
If you want to learn the resources created by the applications, you can open the environment status page.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
There're three kinds of information including `Applied Resources`,`Conditions` and `Component Status`. The `Applied Resources` are all resources created by the applications.
|
||||||
|
|
||||||
|
You can also list resources from command line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela status <app_name> -n <namespace> --tree
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recycle Application Instance
|
||||||
|
|
||||||
|
When you want to delete the application instance in some environment, you can click the `Recycle` button in that environment.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
It will delete the whole application instance with related resources.
|
||||||
|
|
||||||
|
> Note that recycle means delete an application, data can't be recovered automatically. Please make sure you have back up all the important data of this instance before recycle it.
|
||||||
|
|
||||||
|
### Delete Application
|
||||||
|
|
||||||
|
After all application instance were recycled, you can click `Remove` for deletion.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
As the picture shows, the `Remove` button is hidden in the application detail.
|
||||||
|
|
||||||
|
Now you have learned the basic lifecycle of an application.
|
||||||
|
|
@ -15,33 +15,63 @@ For connecting the ACK clusters, the platform will save some cloud info, Region,
|
||||||
|
|
||||||
## Manage the cluster via CLI
|
## Manage the cluster via CLI
|
||||||
|
|
||||||
### vela cluster list
|
|
||||||
|
|
||||||
This command could list all clusters managed by KubeVela currently.
|
|
||||||
```bash
|
|
||||||
$ vela cluster list
|
|
||||||
CLUSTER TYPE ENDPOINT
|
|
||||||
CLUSTER ALIAS TYPE ENDPOINT ACCEPTED LABELS
|
|
||||||
local Internal - true
|
|
||||||
ask-beijing X509Certificate https://*.*.*.*:6443 true
|
|
||||||
```
|
|
||||||
|
|
||||||
### vela cluster join
|
### vela cluster join
|
||||||
|
|
||||||
This command can join new cluster into KubeVela and name it as `cluster-prod`. The joined cluster can be used in [Multi-Environment Deployment](../../end-user/policies/envbinding).
|
You can simply join an existing cluster into KubeVela by specifying its KubeConfig as below
|
||||||
|
|
||||||
```shell script
|
```shell script
|
||||||
$ vela cluster join example-cluster.kubeconfig --name cluster-prod
|
vela cluster join <your kubeconfig path>
|
||||||
|
```
|
||||||
|
|
||||||
|
It will use the field `context.cluster` in KubeConfig as the cluster name automatically,
|
||||||
|
you can also specify the name by `--name` parameter. For example:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ vela cluster join beijing.kubeconfig --name beijing
|
||||||
|
$ vela cluster join hangzhou-1.kubeconfig --name hangzhou-1
|
||||||
|
$ vela cluster join hangzhou-2.kubeconfig --name hangzhou-2
|
||||||
|
```
|
||||||
|
|
||||||
|
### vela cluster list
|
||||||
|
|
||||||
|
After clusters joined, you could list all clusters managed by KubeVela.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela cluster list
|
||||||
|
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
||||||
|
local Internal - true
|
||||||
|
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
||||||
|
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true
|
||||||
|
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true
|
||||||
|
```
|
||||||
|
|
||||||
|
> By default, the hub cluster where KubeVela locates is registered as the `local` cluster. You can use it like a managed cluster in spite that you cannot detach it or modify it.
|
||||||
|
|
||||||
|
### label your cluster
|
||||||
|
|
||||||
|
You can also give labels to your clusters, which helps you select clusters for deploying applications.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$ vela cluster labels add cluster-hangzhou-1 region=hangzhou
|
||||||
|
$ vela cluster labels add cluster-hangzhou-2 region=hangzhou
|
||||||
|
$ vela cluster list
|
||||||
|
CLUSTER TYPE ENDPOINT ACCEPTED LABELS
|
||||||
|
local Internal - true
|
||||||
|
cluster-beijing X509Certificate <ENDPOINT_BEIJING> true
|
||||||
|
cluster-hangzhou-1 X509Certificate <ENDPOINT_HANGZHOU_1> true region=hangzhou
|
||||||
|
cluster-hangzhou-2 X509Certificate <ENDPOINT_HANGZHOU_2> true region=hangzhou
|
||||||
```
|
```
|
||||||
|
|
||||||
### vela cluster detach
|
### vela cluster detach
|
||||||
|
|
||||||
This command can be used to detach cluster from KubeVela.
|
You can also detach a cluster if you do not want to use it anymore.
|
||||||
|
|
||||||
```shell script
|
```shell script
|
||||||
$ vela cluster detach cluster-prod
|
$ vela cluster detach beijing
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> It is dangerous to detach a cluster that is still in-use. But if you want to do modifications to the held cluster credential, like rotating certificates, it is possible to do so.
|
||||||
|
|
||||||
### vela cluster rename
|
### vela cluster rename
|
||||||
|
|
||||||
This command can rename cluster managed by KubeVela.
|
This command can rename cluster managed by KubeVela.
|
||||||
|
|
|
||||||
|
|
@ -128,7 +128,3 @@ Services:
|
||||||
```
|
```
|
||||||
|
|
||||||
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
|
At this point, Helm Chart in KubeVela is no stranger to you, go ahead and try more!
|
||||||
|
|
||||||
## Next step
|
|
||||||
|
|
||||||
- [Deploy Kubernetes Objects](./k8s-object)
|
|
||||||
|
|
|
||||||
|
|
@ -11,13 +11,6 @@ KubeVela supports you to render, orchestrate and deploy Kubernetes objects. The
|
||||||
3. Multi-env/cluster in application delivery.
|
3. Multi-env/cluster in application delivery.
|
||||||
4. The control loop of application deployment: Rollback, Terminate and Continue.
|
4. The control loop of application deployment: Rollback, Terminate and Continue.
|
||||||
|
|
||||||
What's more, you can even distribute existing Kubernetes objects with KubeVela in the following scenarios:
|
|
||||||
|
|
||||||
- Copying secrets from the hub cluster into managed clusters.
|
|
||||||
- Promote deployments from canary clusters into production clusters.
|
|
||||||
- Using Kubernetes apiserver as the control plane and storing all Kubernetes objects data in external databases. Then dispatch those data into real Kuberenetes managed clusters.
|
|
||||||
|
|
||||||
|
|
||||||
## Before starting
|
## Before starting
|
||||||
|
|
||||||
- Prepare a Deployment+Service yaml config resource.
|
- Prepare a Deployment+Service yaml config resource.
|
||||||
|
|
@ -197,104 +190,4 @@ $ vela up -f https://kubevela.io/example/applications/app-with-k8s-objects.yaml
|
||||||
$ vela workflow resume app-with-k8s-objects
|
$ vela workflow resume app-with-k8s-objects
|
||||||
```
|
```
|
||||||
|
|
||||||
## Distributed External Kubernetes Objects
|
|
||||||
|
|
||||||
> This section requires you to know how to deploy multi-cluster application with policy and workflow first. You can refer to [Multi-cluster Application Delivery](../case-studies/multi-cluster) for details.
|
|
||||||
|
|
||||||
|
|
||||||
### Refer to Existing Kubernetes Objects in Component
|
|
||||||
|
|
||||||
To use existing Kubernetes objects in the component, you need to use the `ref-objects` typed component and declare which resources you want to refer to. For example, in the following example, the secret `image-credential-to-copy` in namespace `examples` will be taken as the source object for the component. Then you can use the topology policy to dispatch it into hangzhou clusters.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-example
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: image-pull-secrets
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: secret
|
|
||||||
name: image-credential-to-copy
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-clusters
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusterLabelSelector:
|
|
||||||
region: hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
### Details for the *ref-objects* typed component
|
|
||||||
|
|
||||||
The most simple way to specify resources is to directly use `resource: secret` or `resource: deployment` to describe the kind of resources. If no `name` or `labelSelector` is set, the application will try to find the resource with the same name as the component name in the application's namespace. You can also explicitly specify `name` and `namespace` for the target resource as well.
|
|
||||||
|
|
||||||
In addition to `name` and `namespace`, you can also specify the `cluster` field to let the application component refer to resources in managed clusters. You can also use the `labelSelector` to select resources in replace of finding resources by names.
|
|
||||||
|
|
||||||
In the following example, the application will select all deployments in the *hangzhou-1* cluster inside the *examples* namespace, which matches the desided labels. Then the application will copy these deployments into *hangzhou-2* cluster.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-duplicate-deployments
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: duplicate-deployment
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: deployment
|
|
||||||
cluster: hangzhou-1
|
|
||||||
# select all deployment in the `examples` namespace in cluster `hangzhou-1` that matches the labelSelector
|
|
||||||
labelSelector:
|
|
||||||
need-duplicate: "true"
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-2
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusters: ["hangzhou-2"]
|
|
||||||
```
|
|
||||||
|
|
||||||
> In some cases, you might want to restrict the scope for the application to access resources. You can set the `--ref-objects-available-scope` to `namespace` or `cluster` in KubeVela controller's bootstrap parameter, to retrict the application to be only able to refer to the resources inside the same namespace or the same cluster.
|
|
||||||
|
|
||||||
### Working with Trait
|
|
||||||
|
|
||||||
The *ref-objects* typed component can also be used together with traits. The implicit main workload is the first referenced object and trait patch will be applied on it. The following example demonstrate how to set the replica number for the referenced deployment while deploying it in hangzhou clusters.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: core.oam.dev/v1beta1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: ref-objects-multiple-resources
|
|
||||||
namespace: examples
|
|
||||||
spec:
|
|
||||||
components:
|
|
||||||
- name: nginx-ref-multiple-resources
|
|
||||||
type: ref-objects
|
|
||||||
properties:
|
|
||||||
objects:
|
|
||||||
- resource: deployment
|
|
||||||
- resource: service
|
|
||||||
traits:
|
|
||||||
- type: scaler
|
|
||||||
properties:
|
|
||||||
replicas: 3
|
|
||||||
policies:
|
|
||||||
- name: topology-hangzhou-clusters
|
|
||||||
type: topology
|
|
||||||
properties:
|
|
||||||
clusterLabelSelector:
|
|
||||||
region: hangzhou
|
|
||||||
```
|
|
||||||
|
|
||||||
Congrats! Now you've learned how to deploy Kubernetes objects.
|
Congrats! Now you've learned how to deploy Kubernetes objects.
|
||||||
|
|
||||||
## Next step
|
|
||||||
|
|
||||||
- [Deploy Cloud Service](./consume-cloud-services)
|
|
||||||
- [Distributed External Kubernetes Objects](../end-user/components/ref-objects)
|
|
||||||
|
|
|
||||||
|
|
@ -119,7 +119,3 @@ Services:
|
||||||
|
|
||||||
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
|
* Refer to [webservice details](../end-user/components/references#webservice) to know usage of full fields.
|
||||||
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
|
* Refer to [trait reference](../end-user/traits/references) to know which traits can be used for webservice.
|
||||||
|
|
||||||
## Next Step
|
|
||||||
|
|
||||||
[Learn to deploy Helm Chart](./helm)
|
|
||||||
|
|
|
||||||
|
|
@ -67,10 +67,6 @@
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/end-user/traits/sidecar"
|
"id": "version-v1.3/end-user/traits/sidecar"
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/tutorials/k8s-object"
|
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|
@ -120,6 +116,10 @@
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/tutorials/k8s-object"
|
"id": "version-v1.3/tutorials/k8s-object"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/end-user/components/ref-objects"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|
@ -149,63 +149,16 @@
|
||||||
{
|
{
|
||||||
"collapsed": true,
|
"collapsed": true,
|
||||||
"type": "category",
|
"type": "category",
|
||||||
"label": "How-to manage the applications",
|
"label": "General CD Features",
|
||||||
"items": [
|
"items": [
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/how-to/dashboard/application/create-application"
|
"id": "version-v1.3/how-to/dashboard/application/create-application"
|
||||||
},
|
},
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/bind-new-environment"
|
|
||||||
},
|
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/tutorials/workflows"
|
"id": "version-v1.3/tutorials/workflows"
|
||||||
},
|
},
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/deploy-application"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/get-application-instance"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/tutorials/scaler"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/get-application-log"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/get-application-endpoint"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/view-application-resource"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/get-application-revision"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/recycle-environment"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "doc",
|
|
||||||
"id": "version-v1.3/how-to/dashboard/application/delete-application"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"collapsed": true,
|
|
||||||
"type": "category",
|
|
||||||
"label": "Advanced Features",
|
|
||||||
"items": [
|
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/end-user/workflow/component-dependency-parameter"
|
"id": "version-v1.3/end-user/workflow/component-dependency-parameter"
|
||||||
|
|
@ -432,10 +385,37 @@
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"collapsed": true,
|
||||||
|
"type": "category",
|
||||||
|
"label": "Developer Guide",
|
||||||
|
"items": [
|
||||||
{
|
{
|
||||||
"type": "doc",
|
"type": "doc",
|
||||||
"id": "version-v1.3/contributor/overview"
|
"id": "version-v1.3/contributor/overview"
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/contributor/non-code-contribute"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/contributor/code-contribute"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/contributor/release-process"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/contributor/code-conventions"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "doc",
|
||||||
|
"id": "version-v1.3/contributor/principle-of-test"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"collapsed": true,
|
"collapsed": true,
|
||||||
"type": "category",
|
"type": "category",
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue