Add contributing and debug docs (#131)
* add contributing and debug docs Signed-off-by: mingzhou.swx <mingzhou.swx@alibaba-inc.com> * add contributing and debug docs Signed-off-by: mingzhou.swx <mingzhou.swx@alibaba-inc.com> --------- Signed-off-by: mingzhou.swx <mingzhou.swx@alibaba-inc.com> Co-authored-by: mingzhou.swx <mingzhou.swx@alibaba-inc.com>
This commit is contained in:
Wei-Xiang Sun
GitHub
parent
77e4b8dc2e
commit
5807b5b299
|
|
@ -0,0 +1,133 @@
|
|||
# Contributing to Openkruise
|
||||
|
||||
Welcome to Openkruise! Openkruise consists several repositories under the organization.
|
||||
We encourage you to help out by reporting issues, improving documentation, fixing bugs, or adding new features.
|
||||
Please also take a look at our code of conduct, which details how contributors are expected to conduct themselves as part of the Openkruise community.
|
||||
|
||||
## Reporting issues
|
||||
|
||||
To be honest, we regard every user of Openkruise as a very kind contributor.
|
||||
After experiencing Openkruise, you may have some feedback for the project.
|
||||
Then feel free to open an issue.
|
||||
|
||||
There are lot of cases when you could open an issue:
|
||||
|
||||
- bug report
|
||||
- feature request
|
||||
- performance issues
|
||||
- feature proposal
|
||||
- feature design
|
||||
- help wanted
|
||||
- doc incomplete
|
||||
- test improvement
|
||||
- any questions on project
|
||||
- and so on
|
||||
|
||||
Also we must remind that when filing a new issue, please remember to remove the sensitive data from your post.
|
||||
Sensitive data could be password, secret key, network locations, private business data and so on.
|
||||
|
||||
## Code and doc contribution
|
||||
|
||||
Every action to make Openkruise better is encouraged.
|
||||
On GitHub, every improvement for Openkruise could be via a PR (short for pull request).
|
||||
|
||||
- If you find a typo, try to fix it!
|
||||
- If you find a bug, try to fix it!
|
||||
- If you find some redundant codes, try to remove them!
|
||||
- If you find some test cases missing, try to add them!
|
||||
- If you could enhance a feature, please DO NOT hesitate!
|
||||
- If you find code implicit, try to add comments to make it clear!
|
||||
- If you find code ugly, try to refactor that!
|
||||
- If you can help to improve documents, it could not be better!
|
||||
- If you find document incorrect, just do it and fix that!
|
||||
- ...
|
||||
|
||||
### Workspace Preparation
|
||||
|
||||
To put forward a PR, we assume you have registered a GitHub ID.
|
||||
Then you could finish the preparation in the following steps:
|
||||
|
||||
1. **Fork** Fork the repository you wish to work on. You just need to click the button Fork in right-left of project repository main page. Then you will end up with your repository in your GitHub username.
|
||||
2. **Clone** your own repository to develop locally. Use `git clone https://github.com/<your-username>/<project>.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make.
|
||||
3. **Set remote** upstream to be `https://github.com/openkruise/<project>.git` using the following two commands:
|
||||
|
||||
```bash
|
||||
git remote add upstream https://github.com/openkruise/<project>.git
|
||||
git remote set-url --push upstream no-pushing
|
||||
```
|
||||
|
||||
Note: `<project>` above is `rollouts` if you want to contribute codes to Kruise Rollout.
|
||||
|
||||
Adding this, we can easily synchronize local branches with upstream branches.
|
||||
|
||||
4. **Create a branch** to add a new feature or fix issues
|
||||
|
||||
Update local working directory:
|
||||
|
||||
```bash
|
||||
cd <project>
|
||||
git fetch upstream
|
||||
git checkout master
|
||||
git rebase upstream/master
|
||||
```
|
||||
|
||||
Create a new branch:
|
||||
|
||||
```bash
|
||||
git checkout -b <new-branch>
|
||||
```
|
||||
|
||||
Make any change on the new-branch then build and test your codes.
|
||||
|
||||
### PR Description
|
||||
|
||||
PR is the only way to make change to project files.
|
||||
To help reviewers better get your purpose, PR description could not be too detailed.
|
||||
We encourage contributors to follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request.
|
||||
|
||||
### Developing Environment
|
||||
|
||||
As a contributor, if you want to make any contribution to Kruise project, we should reach an agreement on the version of tools used in the development environment.
|
||||
Here are some dependents with specific version:
|
||||
|
||||
- Golang : v1.18+
|
||||
- Kubernetes: v1.19+
|
||||
|
||||
### Developing guide
|
||||
|
||||
There's a `Makefile` in the root folder which describes the options to build and install. Here are some common ones:
|
||||
|
||||
```bash
|
||||
# Generate code and manifests e.g. CRD, RBAC YAML files etc, and build the controller manager binary
|
||||
make build
|
||||
|
||||
# Run the unit tests
|
||||
make test
|
||||
```
|
||||
|
||||
**There are some guide documents for contributors in [./docs/contributing/](./docs/contributing), such as debug guide to help you test your own branch in a Kubernetes cluster.**
|
||||
|
||||
### Proposals
|
||||
|
||||
If you are going to contribute a feature with new API or needs significant effort, please submit a proposal in [./docs/proposals/](./docs/proposals) first.
|
||||
|
||||
## Engage to help anything
|
||||
|
||||
We choose GitHub as the primary place for Openkruise to collaborate.
|
||||
So the latest updates of Openkruise are always here.
|
||||
Although contributions via PR is an explicit way to help, we still call for any other ways.
|
||||
|
||||
- reply to other's issues if you could;
|
||||
- help solve other user's problems;
|
||||
- help review other's PR design;
|
||||
- help review other's codes in PR;
|
||||
- discuss about Openkruise to make things clearer;
|
||||
- advocate Openkruise technology beyond GitHub;
|
||||
- write blogs on Openkruise and so on.
|
||||
|
||||
In a word, **ANY HELP IS CONTRIBUTION**.
|
||||
|
||||
## Join Openkruise as a member
|
||||
|
||||
It is also welcomed to join Openkruise team if you are willing to participate in Openkruise community continuously and keep active.
|
||||
Please read and follow the [Community Membership](https://github.com/openkruise/community/blob/master/community-membership.md).
|
||||
|
|
@ -22,6 +22,9 @@ Kruise Rollouts is a **Bypass** component that offers **Advanced Progressive Del
|
|||
## Quick Start
|
||||
- See [Getting Started](https://openkruise.io/rollouts/introduction/) documents in OpenKruise official website.
|
||||
|
||||
## Contributing
|
||||
You are warmly welcome to hack on Kruise Rollout. We have prepared a detailed guide [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## Community
|
||||
Active communication channels:
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,92 @@
|
|||
# How to Debug Your Kruise Rollout
|
||||
|
||||
## Way 1: Debug your kruise Rollout with Pod (Recommended)
|
||||
### First Step: Start your kubernetes cluster
|
||||
#### Requirements:
|
||||
- Linux system, MacOS, or Windows Subsystem for Linux 2.0 (WSL 2)
|
||||
- Docker installed (follow the [official docker installation guide](https://docs.docker.com/get-docker/) to install if need be)
|
||||
- Kubernetes cluster >= v1.19.0
|
||||
- Kubectl installed and configured
|
||||
|
||||
Kruise Rollout relies on Kubernetes as control plane. The control plane could be any managed Kubernetes offering or your own cluster.
|
||||
|
||||
For local deployment and test, you could use [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/docs/start/). For production usage, you could use Kubernetes services provided by cloud providers.
|
||||
#### Option 1: Start your kubernetes cluster with kind (Recommended)
|
||||
Follow [this guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to install kind.
|
||||
|
||||
Then spins up a kind cluster:
|
||||
```shell
|
||||
cat <<EOF | kind create cluster --image=kindest/node:v1.22.15 --config=-
|
||||
kind: Cluster
|
||||
apiVersion: kind.x-k8s.io/v1alpha4
|
||||
nodes:
|
||||
- role: control-plane
|
||||
- role: worker
|
||||
- role: worker
|
||||
- role: worker
|
||||
EOF
|
||||
```
|
||||
#### Option 2: Start your kubernetes cluster with minikube
|
||||
Follow the [minikube installation guide](https://minikube.sigs.k8s.io/docs/start/).
|
||||
|
||||
Then spins up a MiniKube cluster:
|
||||
```shell
|
||||
minikube start
|
||||
```
|
||||
|
||||
### Second Step (Optional): Install Kruise
|
||||
If you want to use Workload such as CloneSet, Advanced StatefulSet and Advanced DaemonSet, you have to [install Kruise](https://openkruise.io/docs/installation):
|
||||
|
||||
```bash
|
||||
# Firstly add openkruise charts repository if you haven't do this.
|
||||
$ helm repo add openkruise https://openkruise.github.io/charts/
|
||||
|
||||
# [Optional]
|
||||
$ helm repo update
|
||||
|
||||
# Install the latest version.
|
||||
$ helm install kruise openkruise/kruise --version 1.3.0
|
||||
```
|
||||
|
||||
### Third Step: Deploy your kruise Rollout with a deployment
|
||||
#### 1. Generate code and manifests in your branch
|
||||
Make your own code changes and validate the build by running `make build` in rollouts directory.
|
||||
#### 2. Deploy customized controller manager
|
||||
The deployment can be done by following steps.
|
||||
- Prerequisites: prepare an image registry, it can be [docker hub](https://hub.docker.com/) or your private hub.
|
||||
- step 1: `export IMG=<image_name>` to specify the target image name. e.g., `export IMG=$DOCKERID/kruise-rollout:test`;
|
||||
- step 2: `make docker-build` to build the image locally and `make docker-push` to push the image to registry;
|
||||
- step 3: `export KUBECONFIG=<your_k8s_config>` to specify the k8s cluster config. e.g., `export KUBECONFIG=$~/.kube/config`;
|
||||
- step 4:
|
||||
- 4.1: `make deploy` to deploy Rollout to the k8s cluster with the `IMG` you have packaged, if the cluster has not installed Rollout or has installed via `make deploy`;
|
||||
- 4.2: if the cluster has installed Rollout via helm chart, we suggest you just update your `IMG` into it with `kubectl set image -n kruise-rollout deployment kruise-rollout-controller-manager manager=${IMG}`;
|
||||
|
||||
Tips:
|
||||
- You have to run `./scripts/uninstall.sh` to uninstall Rollout if you installed it using `make deploy`.
|
||||
|
||||
#### 3.View logs of your Rollout
|
||||
You can perform manual tests and use `kubectl logs -n kruise-rollout <kruise-rollout-pod-name>` to check controller logs for debugging, and you can see your `<kruise-rollout-pod-name>` by applying `kubectl get pod -n kruise-rollout`.
|
||||
|
||||
## Way 2: Debug your Rollout locally (NOT Recommended)
|
||||
Kubebuilder default `make run` does not work for webhooks since its scaffolding code starts webhook server
|
||||
using kubernetes service and the service usually does not work in local dev environment.
|
||||
|
||||
We workarounds this problem by allowing to start webbook server in local host directly.
|
||||
With this fix, one can start/debug Rollout process locally
|
||||
which connects to a local or remote Kubernetes cluster. Several extra steps are needed to make it work:
|
||||
|
||||
**Setup host and run your Rollout**
|
||||
|
||||
First, make sure your kubernetes cluster is running.
|
||||
|
||||
Second, **make sure `kube-apiserver` could connect to your local machine.**
|
||||
|
||||
Then, run rollout locally with `WEBHOOK_HOST` env:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=${PATH_TO_CONFIG}
|
||||
export WEBHOOK_HOST=${YOUR_LOCAL_IP}
|
||||
|
||||
make install
|
||||
make run
|
||||
```
|
||||
Loading…
Reference in New Issue