diff --git a/docsite/docs/developer/contributor-guidance.md b/docsite/docs/developer/contributor-guidance.md index 03333938a..c202b086b 100644 --- a/docsite/docs/developer/contributor-guidance.md +++ b/docsite/docs/developer/contributor-guidance.md @@ -20,7 +20,7 @@ To get started with developing for our project, please refer to our [Development ## Deploying Changes -If you are working on changes that require deployment, look at our [Deployment Guide](develop-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated. +If you are working on changes that require deployment, look at our [Deployment Guide](deploy-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated. ## How to Contribute diff --git a/docsite/docs/developer/develop-locally.md b/docsite/docs/developer/develop-locally.md index ab39f6d76..0267870a9 100644 --- a/docsite/docs/developer/develop-locally.md +++ b/docsite/docs/developer/develop-locally.md @@ -1,16 +1,76 @@ # Develop ob-operator locally -Tips: In this tutorial, we'll disable webhook validation and run manager controller on our laptop. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file. - -## Background +## Introduction ob-operator depends on [kubebuilder](https://kubebuilder.io/introduction), an operator framework maintained by kubernetes SIGS. It offers convenient utilities to bootstrap an operator and manage API types in it. Like other operator frameworks, kubebuilder depends on kubernetes [controller runtime](https://github.com/kubernetes-sigs/controller-runtime) either, which is an excellent reference to know how kubernetes dispatch events and reconcile resources. -## Disable Webhook and CertManager +## Requirements + +- Go 1.22 or above is required to build ob-operator, you can refer to the [official website](https://go.dev/) to setup go environment. +- [make](https://www.gnu.org/software/make/) is used for a variety of build and test actions. +- kubebuilder is used as k8s operator framework. it's highly recommended to read [kubebuilder books](https://book.kubebuilder.io/). +- Access to a kubernetes cluster is required to develop and test the operator. You can use [minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [k3s](https://k3s.io/) to create a local kubernetes cluster. + +## Modify and Apply CRDs + +### Modify definition of CRDs + +`ob-operator` uses kubebuilder as operator framework, which generates CRDs in YAML format from Go code lies in `api/v1alpha1` directory. If you have modified the Go code, for example adding a new field to `OBClusterSpec` in `api/v1alpha1/obcluster_types.go`, you need to regenerate the CRDs by running `make generate manifests fmt`. Then you will see changes in `config/crd/bases/oceanbase.oceanbase.com_xxx.yaml` files. + +### Apply the Changes + +You can apply the changes of CRDs to kubernetes cluster by running `make install`. This command will apply the CRDs to the kubernetes cluster. + +You will see output like the following after executing `kubectl get crds` command if the CRDs are successfully applied: + +```shell +$ kubectl get crds | grep oceanbase.oceanbase.com +obclusters.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obparameters.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obresourcerescues.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +observers.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantbackuppolicies.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantbackups.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantoperations.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obclusteroperations.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantrestores.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenants.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obzones.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +``` + +## Modify and Run ob-operator + +ob-operator acts as a controller manager, which watches the resources in kubernetes cluster and reconciles them. The controller manager is generated by kubebuilder, and the main logic lies in `internal/{controller,resource}` and `pkg/coordinator` directories. + +### Build and Deploy + +After modifying the code, you can build the docker image by running `make docker-build docker-push IMG=`. Then you can deploy the controller manager to the kubernetes cluster by running `make deploy IMG=`. + +If the docker need root permission to build, you can run building command with `sudo`, like + +```bash +sudo make docker-build IMG= +make docker-push IMG= # If you need to push the image to a registry +make deploy IMG= +``` + +:::tip +If the developing machine and the deploying machine is the same one, you can skip the pushing step `make docker-push`. +::: + +### Run locally + +Building docker image and pushing it to a registry is time-consuming, especially when you are developing and debugging. You can run controller manager locally to accelerate the development process. + +:::tip +In this step, we'll disable webhook validation and run controller manager on the developing machine. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file. +::: + +#### Disable Webhook and CertManager There are many configuration items that marked by `[CERTMANAGER]` and `[WEBHOOK]` in the two files `config/crd/kustomization.yaml` and `config/default/kustomization.yaml`. They are used to enable and configure webhooks in real kubernetes deployment. Because we want to run controller manager locally, we need to disable them. -You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled. +You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled. ```shell kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io oceanbase-validating-webhook-configuration @@ -19,7 +79,7 @@ kubectl delete -n oceanbase-system svc oceanbase-webhook-service kubectl delete -n oceanbase-system deployments.apps oceanbase-controller-manager ``` -## Self-signed Certificate +#### Generate Self-signed Certificates It's necessary for node hosting controller manager to have a TLS certificate. In the real kubernetes cluster, the cert-manager will inject the sign into the controller manager pod. On our laptop, we need self-sign one: @@ -30,9 +90,9 @@ openssl req -new -key /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8 openssl x509 -req -days 365 -in /tmp/k8s-webhook-server/serving-certs/tls.csr -signkey /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8s-webhook-server/serving-certs/tls.crt ``` -## Run locally +#### Run ob-operator on Your Machine -There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience, +There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience, ```shell # print log to stdout @@ -41,11 +101,11 @@ make run-local make run-local &> bin/run.log ``` -## Debug locally +### Debugging Though print debugging is enough for most cases, there are quite some cases that are not obvious from printed information. We could debug with go debugging tool [delve](https://github.com/go-delve/delve). -`install-delve` command is declared in `make/debug.mk`, we can type `make install-delve` to get it. The help message of it can be glanced, +`install-delve` command is declared in `make/debug.mk`, you can type `make install-delve` to get it. The help message of it can be glanced, ```shell dlv help Delve is a source level debugger for Go programs. @@ -81,13 +141,13 @@ Additional help topics: dlv redirect Help about file redirection. ``` -## Start debugging +#### Start delve Debug Server -Run `make run-delve` to start debugging server. +Run `make run-delve` simply to start debugging server. -### Debug in terminal +#### Debug in Terminal -If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below, +If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below, ```shell (dlv) help @@ -158,7 +218,7 @@ Other commands: Type help followed by a command for full documentation. ``` -### In VSCode +#### Debug in VSCode If you are first to debugging in VSCode, enter `Cmd+Shift+P` to open commands panel. Then, type `Debug: Add Configuration...` and create debugging task for Go. After creating task successfully, open commands panel and type `Debug: Start Debugging`/`Debug: Select and Start Debugging` to start debugging. diff --git a/docsite/docs/developer/development.md b/docsite/docs/developer/development.md deleted file mode 100644 index 397efab51..000000000 --- a/docsite/docs/developer/development.md +++ /dev/null @@ -1,70 +0,0 @@ -# Developing ob-operator - -## environment-setup -1. go -ob-operator requires [go 1.20 or above](https://go.dev/doc/install) to build, you can refer to the official document to setup go environment. - -2. make -ob-operator uses [make](https://www.gnu.org/software/make/) for a variety of build and test actions, it's need to be installed before you go. - -3. kubebuilder -ob-operator uses kubebuilder as operator framework, before you dive into the code, it's highly recommended to read [kubebuilder books](https://book.kubebuilder.io). - -## build ob-operator - -1. build docker image -use the following command to build docker image -``` -make docker-build -``` - -2. push docker image to repository -use the following command to push docker image -``` -make docker-push -``` - -## deploy - -1. install crd to K8s cluster -use the following command to generate crd and install to K8s cluster -``` -make install -``` -if you wish to save the crd as yaml format config file, you can run the following command -``` -make export-crd -``` -the generated file will be placed under deploy directory and named crd.yaml - -2. deploy controller-manager to K8s cluster -use the following command to generate controller-manager config and deploy to K8s cluster -``` -make deploy -``` -if you wish to save the controller-manager deployment config as yaml format config file, you can run the following command -``` -make export-operator -``` -the generated file will be placed under deploy directory and named operator.yaml - -After the above steps, CRDs and controller-manager are deployed to K8s cluster, to check the deployments are successful, you can check with the following command -``` -# check crds -kubectl get crds - -# check controller-manager -kubectl get pods -n oceanbase-system -``` -you will get something like the following -![crd](/img/crd.jpg "crd") -![controller-manager](/img/controller-manager.jpg "controller-manager") - -## check logs -After deploying the crds and controller-manager, ob-operator will handle OceanBase related objects lifecycle management, you may test your own business by create a cr and make some modifications, ob-operator will handle the certain event. To test everything works properly, you can use the following command to check log message. -``` -kubectl logs oceanbase-controller-manager-xxx -c manager -n oceanbase-system -``` - -`oceanbase-controller-manager-xxx` should be replaced by the real pod name - diff --git a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/contributor-guidance.md b/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/contributor-guidance.md index c3fbfdbae..07e7c78f6 100644 --- a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/contributor-guidance.md +++ b/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/contributor-guidance.md @@ -16,7 +16,7 @@ To get started with developing for our project, please refer to our [Development ## Deploying Changes -If you are working on changes that require deployment, look at our [Deployment Guide](develop-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated. +If you are working on changes that require deployment, look at our [Deployment Guide](deploy-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated. ## How to Contribute diff --git a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/develop-locally.md b/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/develop-locally.md index ab39f6d76..0267870a9 100644 --- a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/develop-locally.md +++ b/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/develop-locally.md @@ -1,16 +1,76 @@ # Develop ob-operator locally -Tips: In this tutorial, we'll disable webhook validation and run manager controller on our laptop. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file. - -## Background +## Introduction ob-operator depends on [kubebuilder](https://kubebuilder.io/introduction), an operator framework maintained by kubernetes SIGS. It offers convenient utilities to bootstrap an operator and manage API types in it. Like other operator frameworks, kubebuilder depends on kubernetes [controller runtime](https://github.com/kubernetes-sigs/controller-runtime) either, which is an excellent reference to know how kubernetes dispatch events and reconcile resources. -## Disable Webhook and CertManager +## Requirements + +- Go 1.22 or above is required to build ob-operator, you can refer to the [official website](https://go.dev/) to setup go environment. +- [make](https://www.gnu.org/software/make/) is used for a variety of build and test actions. +- kubebuilder is used as k8s operator framework. it's highly recommended to read [kubebuilder books](https://book.kubebuilder.io/). +- Access to a kubernetes cluster is required to develop and test the operator. You can use [minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [k3s](https://k3s.io/) to create a local kubernetes cluster. + +## Modify and Apply CRDs + +### Modify definition of CRDs + +`ob-operator` uses kubebuilder as operator framework, which generates CRDs in YAML format from Go code lies in `api/v1alpha1` directory. If you have modified the Go code, for example adding a new field to `OBClusterSpec` in `api/v1alpha1/obcluster_types.go`, you need to regenerate the CRDs by running `make generate manifests fmt`. Then you will see changes in `config/crd/bases/oceanbase.oceanbase.com_xxx.yaml` files. + +### Apply the Changes + +You can apply the changes of CRDs to kubernetes cluster by running `make install`. This command will apply the CRDs to the kubernetes cluster. + +You will see output like the following after executing `kubectl get crds` command if the CRDs are successfully applied: + +```shell +$ kubectl get crds | grep oceanbase.oceanbase.com +obclusters.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obparameters.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obresourcerescues.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +observers.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantbackuppolicies.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantbackups.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantoperations.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obclusteroperations.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenantrestores.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obtenants.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +obzones.oceanbase.oceanbase.com 2024-01-01T00:00:00Z +``` + +## Modify and Run ob-operator + +ob-operator acts as a controller manager, which watches the resources in kubernetes cluster and reconciles them. The controller manager is generated by kubebuilder, and the main logic lies in `internal/{controller,resource}` and `pkg/coordinator` directories. + +### Build and Deploy + +After modifying the code, you can build the docker image by running `make docker-build docker-push IMG=`. Then you can deploy the controller manager to the kubernetes cluster by running `make deploy IMG=`. + +If the docker need root permission to build, you can run building command with `sudo`, like + +```bash +sudo make docker-build IMG= +make docker-push IMG= # If you need to push the image to a registry +make deploy IMG= +``` + +:::tip +If the developing machine and the deploying machine is the same one, you can skip the pushing step `make docker-push`. +::: + +### Run locally + +Building docker image and pushing it to a registry is time-consuming, especially when you are developing and debugging. You can run controller manager locally to accelerate the development process. + +:::tip +In this step, we'll disable webhook validation and run controller manager on the developing machine. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file. +::: + +#### Disable Webhook and CertManager There are many configuration items that marked by `[CERTMANAGER]` and `[WEBHOOK]` in the two files `config/crd/kustomization.yaml` and `config/default/kustomization.yaml`. They are used to enable and configure webhooks in real kubernetes deployment. Because we want to run controller manager locally, we need to disable them. -You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled. +You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled. ```shell kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io oceanbase-validating-webhook-configuration @@ -19,7 +79,7 @@ kubectl delete -n oceanbase-system svc oceanbase-webhook-service kubectl delete -n oceanbase-system deployments.apps oceanbase-controller-manager ``` -## Self-signed Certificate +#### Generate Self-signed Certificates It's necessary for node hosting controller manager to have a TLS certificate. In the real kubernetes cluster, the cert-manager will inject the sign into the controller manager pod. On our laptop, we need self-sign one: @@ -30,9 +90,9 @@ openssl req -new -key /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8 openssl x509 -req -days 365 -in /tmp/k8s-webhook-server/serving-certs/tls.csr -signkey /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8s-webhook-server/serving-certs/tls.crt ``` -## Run locally +#### Run ob-operator on Your Machine -There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience, +There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience, ```shell # print log to stdout @@ -41,11 +101,11 @@ make run-local make run-local &> bin/run.log ``` -## Debug locally +### Debugging Though print debugging is enough for most cases, there are quite some cases that are not obvious from printed information. We could debug with go debugging tool [delve](https://github.com/go-delve/delve). -`install-delve` command is declared in `make/debug.mk`, we can type `make install-delve` to get it. The help message of it can be glanced, +`install-delve` command is declared in `make/debug.mk`, you can type `make install-delve` to get it. The help message of it can be glanced, ```shell dlv help Delve is a source level debugger for Go programs. @@ -81,13 +141,13 @@ Additional help topics: dlv redirect Help about file redirection. ``` -## Start debugging +#### Start delve Debug Server -Run `make run-delve` to start debugging server. +Run `make run-delve` simply to start debugging server. -### Debug in terminal +#### Debug in Terminal -If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below, +If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below, ```shell (dlv) help @@ -158,7 +218,7 @@ Other commands: Type help followed by a command for full documentation. ``` -### In VSCode +#### Debug in VSCode If you are first to debugging in VSCode, enter `Cmd+Shift+P` to open commands panel. Then, type `Debug: Add Configuration...` and create debugging task for Go. After creating task successfully, open commands panel and type `Debug: Start Debugging`/`Debug: Select and Start Debugging` to start debugging. diff --git a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/development.md b/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/development.md deleted file mode 100644 index 397efab51..000000000 --- a/docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/development.md +++ /dev/null @@ -1,70 +0,0 @@ -# Developing ob-operator - -## environment-setup -1. go -ob-operator requires [go 1.20 or above](https://go.dev/doc/install) to build, you can refer to the official document to setup go environment. - -2. make -ob-operator uses [make](https://www.gnu.org/software/make/) for a variety of build and test actions, it's need to be installed before you go. - -3. kubebuilder -ob-operator uses kubebuilder as operator framework, before you dive into the code, it's highly recommended to read [kubebuilder books](https://book.kubebuilder.io). - -## build ob-operator - -1. build docker image -use the following command to build docker image -``` -make docker-build -``` - -2. push docker image to repository -use the following command to push docker image -``` -make docker-push -``` - -## deploy - -1. install crd to K8s cluster -use the following command to generate crd and install to K8s cluster -``` -make install -``` -if you wish to save the crd as yaml format config file, you can run the following command -``` -make export-crd -``` -the generated file will be placed under deploy directory and named crd.yaml - -2. deploy controller-manager to K8s cluster -use the following command to generate controller-manager config and deploy to K8s cluster -``` -make deploy -``` -if you wish to save the controller-manager deployment config as yaml format config file, you can run the following command -``` -make export-operator -``` -the generated file will be placed under deploy directory and named operator.yaml - -After the above steps, CRDs and controller-manager are deployed to K8s cluster, to check the deployments are successful, you can check with the following command -``` -# check crds -kubectl get crds - -# check controller-manager -kubectl get pods -n oceanbase-system -``` -you will get something like the following -![crd](/img/crd.jpg "crd") -![controller-manager](/img/controller-manager.jpg "controller-manager") - -## check logs -After deploying the crds and controller-manager, ob-operator will handle OceanBase related objects lifecycle management, you may test your own business by create a cr and make some modifications, ob-operator will handle the certain event. To test everything works properly, you can use the following command to check log message. -``` -kubectl logs oceanbase-controller-manager-xxx -c manager -n oceanbase-system -``` - -`oceanbase-controller-manager-xxx` should be replaced by the real pod name - diff --git a/docsite/static/img/controller-manager.jpg b/docsite/static/img/controller-manager.jpg deleted file mode 100644 index 190216e41..000000000 Binary files a/docsite/static/img/controller-manager.jpg and /dev/null differ diff --git a/docsite/static/img/crd.jpg b/docsite/static/img/crd.jpg deleted file mode 100644 index dbbd4e64e..000000000 Binary files a/docsite/static/img/crd.jpg and /dev/null differ