|
1 | | ---- |
2 | | -title: CustomResources |
3 | | ---- |
4 | | - |
5 | | -import Tabs from '@theme/Tabs'; |
6 | | -import TabItem from '@theme/TabItem'; |
7 | | -import useBaseUrl from '@docusaurus/useBaseUrl'; |
8 | | - |
9 | | -## Develop CustomResources |
10 | | -Nocalhost not only support developing the built-in resources such as Deployment, StatefulSet and Job, but also support developing the [CustomResources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources). |
11 | | - |
12 | | -### How it works |
13 | | -Under the hood, Nocalhost replace the container images controlled by [K8s Controller](https://kubernetes.io/docs/concepts/architecture/controller/) with developing container images and upload local source code into the developing container to achieve the developing of Kubernetes resources. When develop a specific kind of Controller (including both Built-in Resources and CustomResources), Nocalhost require the following three aspects of informations: |
14 | | -- Pod template path in the Controller's definition. For instance, the template path of the Deployment built-in type is `/spec/template`. Nocalhost could use that path to get the Pod template and modify that template by replacing the working images with developing images. |
15 | | -- Do you want Nocalhost to modify the Controller's original Pod template definition or to create a new Deployment based on the original Pod template definition. Since not all of the Controller's Pod template definition could be modified. Job, for example, is unmodifiable. In such a condition, Nocalhost create a new Deployment with the original Pod template definition(which is transparent to users). The Pod template of the newly created Deployment use the developing image instead of the original image. Local source code will be uploaded into that Pod. |
16 | | -- How to make sure the cluster's traffic only visit the developing image in DevMod? A Controller usually manage many Pods. If there are still many Pods after entering DevMode, Nocalhost couldn't make sure that all the cluster's traffic goes through the developing Pod. Hence Nocalhost will reduce the amount of Pod replicas into 1. What's more, in terms of the Custom Resources that need to create new Deployment for developing, Nocalhost will reduce the number of the Pod replicas in the original Controller into 0. Take DaemonSet as an example. Nocalhost will delete DaemonSet's Pods altogether through setting the NodeName of DaemonSet's Pods into a non-existent Node. |
17 | | - |
18 | | -Nocalhost define how to develop CustomResources by `DevModeAction`. The three fields of `DevModeAction` offer the above three aspects of information. Users can add `DevModeAction` in `~/.nh/nhctl/config` to empower Nocalhost with the ablity of developing specific CustomResources. An example of how to configuring `~/.nh/nhctl/config` is shown below: |
19 | | - |
20 | | -```yaml |
21 | | -crdDevModeActions: |
22 | | -- crdType: statefulsets.v1beta1.apps.kruise.io |
23 | | - devModeAction: |
24 | | - podTemplatePath: /spec/template |
25 | | - create: false |
26 | | - scalePatches: |
27 | | - - type: json |
28 | | - patch: '[{"op":"replace","path":"/spec/replicas","value":1}]' |
29 | | -``` |
30 | | -
|
31 | | -notes: |
32 | | -- crdType: The form is `resource.version.group`. The resource/version/group are the resource/version/group of CustomResources respectively, namely GVR in reverse, which is used to specify the corresponding CustomResources type of `DevModeAction`. |
33 | | -- devModeAction: Used to controll the actions to take when specific CustomResources objects enter `DevMode` |
34 | | - - podTemplatePath: Specify the path of Pod template definition. Nocalhost will modify that template. For example, replace the containers' image with develop image, add sidcar containers, etc. |
35 | | - - create: Specify if a new Deployment is created in order to develop when CustomResources objects enter `DevMode`. |
36 | | - - If it's set into `true`, Nocalhost will use the Pod template definition in `podTemplatePath` to create a new Deployment. All of the operations in `DevMode` will be done in that Deployment. |
37 | | - - If it's set into `false`, Nocalhost will modify the Pod template definition of the CustomResources object directly. All of the operations done in `DevMode` will be applied to the CustomeResources object. |
38 | | - - scalePatches: It specifies the patch that configure the CustomResources object to reduce the amount of replicas into 1 before entering `DevMode`. If the amount of replicas has already been 1 or you don't mean to reduce the amount, then you can ignore this piece of config(refering to `How to make sure the cluster's traffic only visit the developing image in DevMod?`). |
39 | | - |
40 | | -Besides, Nocalhost also has built-in support for several common open-source CustomResources, which includes [CloneSet](https://openkruise.io/docs/user-manuals/cloneset/) of [Kruise](https://github.com/openkruise/kruise), [Advanced StatefulSet](https://openkruise.io/docs/user-manuals/advancedstatefulset), [Advanced DaemonSet](https://openkruise.io/docs/user-manuals/advanceddaemonset) etc. You can use Nocalhost to develop these CustomResources without configuration. |
41 | | - |
42 | | - |
43 | | -### How to use |
44 | | -Find the `CustomResources` tab in Nocalhost IDE plugin. Expand that tab and you will see the `CustomResources` list. |
45 | | - |
46 | | - |
47 | | -Right click the `CustomeResources` that you want to develop. A selection box will pop up. Click the `Start DevMode` to develop: |
48 | | - |
49 | | -> The operations of CustomResources objects are in line with built-in resources in Workloads like Deployment/StatefulSet etc. |
| 1 | +--- |
| 2 | +title: CustomResources |
| 3 | +--- |
| 4 | + |
| 5 | +import Tabs from '@theme/Tabs'; |
| 6 | +import TabItem from '@theme/TabItem'; |
| 7 | +import useBaseUrl from '@docusaurus/useBaseUrl'; |
| 8 | + |
| 9 | +## CustomResources 开发支持 |
| 10 | +Nocalhost 除了支持对 Deployment/StatefulSet/Job 等内置资源进行开发，也支持对 [CustomResources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources) 进行开发。 |
| 11 | + |
| 12 | +### How it works |
| 13 | +Nocalhost 对 K8s 资源对象的开发本质上是将 [K8s Controller](https://kubernetes.io/docs/concepts/architecture/controller/) 控制的 Pod 的业务容器镜像替换为开发容器镜像，再将本地的源代码同步到开发容器中去。在对某种特定类型的控制器（包括内置类型和 CustomResources 类型）进行开发时，Nocalhost 需要知道以下 3 个信息： |
| 14 | +- Pod 模板定义在 Controller 定义中的路径。如内置类型的 Deployment 的 Pod 模板定义路径为 `/spec/template`，Nocalhost 通过该路径可以获取到 Pod 模板并对模板进行修改，将业务容器镜像替换成开发容器镜像 |
| 15 | +- 是在原 Controller 的 Pod 模板定义上直接修改，还是使用该 Pod 模板定义创建一个新的 Deployment。这是因为并不是所有 Controller 的 Pod 模板都是可以修改的，如 Job，在这种场景下，Nocalhost 使用原 Controller 的 Pod 模板定义创建一个新的 Deployment（该 Deployment 对用户透明），该 Deployment 的 Pod 模板定义的容器镜像会被修改为开发容器镜像，本地的源代码也会被同步到该 Pod 里。 |
| 16 | +- 如何保证进入开发模式之后集群流量只会访问到开发容器。Controller 常常会管理多个 Pod，如果进入开发模式之后还存在多个 Pod 的话，我们无法保证集群的流量都只访问正在开发中的那个 Pod，所以一般我们需要将 Pod 的副本数缩减为 1。另外，对于创建新的 Deployment 进行开发的 CustomResources，则需要让原 Controller 的 Pod 副本数缩减为 0，如 DaemonSet,我们可以通过将 Pod 的 NodeName 指定为一个不存在的 Node 来将 DaemonSet 管理的 Pod 全部删掉。 |
| 17 | + |
| 18 | +Nocalhost 通过 `DevModeAction` 来定义如何对 CustomResources 进行开发，`DevModeAction` 的三个字段分别向 Nocalhost 提供了上述 3 个信息。用户可以通过在 `~/.nh/nhctl/config` 中添加 `DevModeAction` 来使 Nocalhost 获得开发指定 CustomResources 的能力， `~/.nh/nhctl/config` 的配置样例如下： |
| 19 | + |
| 20 | +```yaml |
| 21 | +crdDevModeActions: |
| 22 | +- crdType: statefulsets.v1beta1.apps.kruise.io |
| 23 | + devModeAction: |
| 24 | + podTemplatePath: /spec/template |
| 25 | + create: false |
| 26 | + scalePatches: |
| 27 | + - type: json |
| 28 | + patch: '[{"op":"replace","path":"/spec/replicas","value":1}]' |
| 29 | +``` |
| 30 | +
|
| 31 | +其中： |
| 32 | +- crdType: 为 `resource.version.group` 的形式，resource/version/group 分别是 CustomResources 的 Resource/Version/Group，即 GVR 反过来写，指定该 `DevModeAction` 对应的 CustomResources 类型 |
| 33 | +- devModeAction: 用于控制 Nocalhost 让指定 CustomResources 对象进入 `DevMode` 时的行为 |
| 34 | + - podTemplatePath: 指定 Pod 模板定义所在的路径，Nocalhost 会修改该模板，如将容器镜像修改成开发镜像，添加 sidecar 容器等 |
| 35 | + - create: 指明 CustomResources 对象在进入 `DevMode` 时，是否需要创建一个新的 Deployment，在该 Deployment 上进行开发 |
| 36 | + - 如果为 `true`，Nocalhost 会使用在 `podTemplatePath` 中找到的 Pod 模板定义来创建一个 Deployment，`DevMode` 下的所有操作都在改 Deployment 中进行 |
| 37 | + - 如果为 `false`，Nocalhost 会直接修改 CustomResources 对象的 Pod 模板定义，`DevMode` 下的所有操作都在该 CustomResources 对象上进行 |
| 38 | + - scalePatches: 一般为配置 CustomResources 对象在进入开发模式前将副本数缩为 1 的 patch，如果副本数已经为 1 或不需要将副本数缩为 1，此项可不配置 (参考上述关于 `如何保证进入开发模式之后集群流量只会访问到开发容器` 的说明) |
| 39 | + |
| 40 | +另外，Nocalhost 对常见的开源 CustomResources 进行了内置支持，如 [Kruise](https://github.com/openkruise/kruise) 的 [CloneSet](https://openkruise.io/docs/user-manuals/cloneset/)、[Advanced StatefulSet](https://openkruise.io/docs/user-manuals/advancedstatefulset) 、 [Advanced DaemonSet](https://openkruise.io/docs/user-manuals/advanceddaemonset) 等，对于内置支持的 CustomResources，无需进行配置便直接使用 Nocalhost 对其进行开发。 |
| 41 | + |
| 42 | + |
| 43 | +### How to use |
| 44 | +在 IDE 插件中找到 `CustomResources` 选项卡，展开该选项卡可以查看 `CustomResources` 资源列表： |
| 45 | + |
| 46 | + |
| 47 | +在要开发的 `CustomResources` 资源对象上点击右键，弹出选项框，点击 `Start DevMode` 或 `Start DevMode(Duplicate)` 即可进入开发模式： |
| 48 | + |
| 49 | +> CustomResources 对象的各个操作和 Workloads 中的 Deployment/StatefulSet 等 K8s 内置资源对象基本一致 |
0 commit comments