Add operator port (#2320)

* Add operator port * Update port desc * Update docs-2.0-zh/nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md * Update port --------- Co-authored-by: abby.huang <[email protected]>
vesoft-inc · Oct 31, 2023 · 67588ee · 67588ee
1 parent f488eba
commit 67588ee
Show file tree

Hide file tree

Showing 3 changed files with 210 additions and 15 deletions.
diff --git a/...en/nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md b/...en/nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md
@@ -1,6 +1,6 @@
-# Customize configuration parameters for a NebulaGraph cluster
+# Customize parameters for a NebulaGraph cluster
 
-Meta, Storage, and Graph services in a NebulaGraph Cluster have their own configuration settings, which are defined in the YAML file of the NebulaGraph cluster instance as `config`. These settings are mapped and loaded into the corresponding service's ConfigMap in Kubernetes. At the time of startup, the configuration present in the ConfigMap is mounted onto the directory `/usr/local/nebula/etc/` for every service.
+Meta, Storage, and Graph services in a NebulaGraph cluster have their own configuration settings, which are defined in the YAML file of the NebulaGraph cluster instance as `config`. These settings are mapped and loaded into the corresponding service's ConfigMap in Kubernetes. At the time of startup, the configuration present in the ConfigMap is mounted onto the directory `/usr/local/nebula/etc/` for every service.
 
 !!! note
 
@@ -11,6 +11,7 @@ The structure of `config` is as follows.
 ```go
 Config map[string]string `json:"config,omitempty"`
 ```
+
 ## Prerequisites
 
 You have created a NebulaGraph cluster. For how to create a cluster with Kubectl, see [Create a cluster with Kubectl](../3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md). 
@@ -25,7 +26,7 @@ The following example uses a cluster named `nebula` and the cluster's configurat
   kubectl edit nebulaclusters.apps.nebula-graph.io nebula
   ```
 
-2. Add `enable_authorize` and `auth_type` under `spec.graphd.config`.
+2. Customize parameters under the `spec.graphd.config` field. In the following sample, the `enable_authorize` and `auth_type` parameters are used for demonstration purposes.
 
   ```yaml
   apiVersion: apps.nebula-graph.io/v1alpha1
@@ -55,20 +56,118 @@ The following example uses a cluster named `nebula` and the cluster's configurat
         "auth_type": "password"
   ...
   ```
+
+  The parameters that can be added under the `config` field are listed in detail in the [Meta service configuration parameters](../../5.configurations-and-logs/1.configurations/2.meta-config.md), [Storage service configuration parameters](../../5.configurations-and-logs/1.configurations/4.storage-config.md), and [Graph service configuration parameters](../../5.configurations-and-logs/1.configurations/3.graph-config.md) topics.
+
+  !!! note
+
+      * To update cluster configurations without incurring pod restart, ensure that all parameters added under the `config` field support runtime dynamic modification. Check the **Whether supports runtime dynamic modifications** column of the parameter tables on the aforementioned parameter details pages to see if a parameter supports runtime dynamic modification.
+      * If one or more parameters that do not support runtime dynamic modification are added under the `config` field, pod restart is required for the parameters to take effect.
+
 
   To add the `config` for the Meta and Storage services, add `spec.metad.config` and `spec.storaged.config` respectively.
 
 3. Run `kubectl apply -f nebula_cluster.yaml` to push your configuration changes to the cluster.
 
-  After customizing the parameters `enable_authorize` and `auth_type`, the configurations in the corresponding ConfigMap (`nebula-graphd`) of the Graph service will be overwritten.
+  After customizing the parameters, the configurations in the corresponding ConfigMap (`nebula-graphd`) of the Graph service will be overwritten.
+
+
+## Customize port configurations
 
-## Modify cluster configurations online
+You can add the `port` and `ws_http_port` parameters under the `config` field to customize port configurations. For details about these two parameters, see the Networking configurations section in [Meta service configuration parameters](../../5.configurations-and-logs/1.configurations/2.meta-config.md), [Storage service configuration parameters](../../5.configurations-and-logs/1.configurations/4.storage-config.md), and [Graph service configuration parameters](../../5.configurations-and-logs/1.configurations/3.graph-config.md). 
 
-Cluster configurations are modified online by calling the HTTP interface, without the need to restart the cluster Pod.
+!!! note
+
+    * Pod restart is required for the `port` and `ws_http_port` parameters to take effect. 
+    * It is NOT recommnended to modify the `port` parameter after the cluster is started.
+
+1. Modifiy the cluster configuration file.
+
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    graphd:
+      config:
+        port: "3669"
+        ws_http_port: "8080"
+      resources:
+        requests:
+          cpu: "200m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-graphd
+      version: {{nebula.tag}}
+    metad:
+      config:
+        ws_http_port: 8081
+      resources:
+        requests:
+          cpu: "300m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-metad
+      version: {{nebula.tag}}
+      dataVolumeClaim:
+        resources:
+          requests:
+            storage: 2Gi
+        storageClassName: local-path
+    storaged:
+      config:
+        ws_http_port: 8082
+      resources:
+        requests:
+          cpu: "300m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-storaged
+      version: {{nebula.tag}}
+      dataVolumeClaims:
+      - resources:
+          requests:
+            storage: 2Gi
+        storageClassName: local-path
+      enableAutoBalance: true
+    reference:
+      name: statefulsets.apps
+      version: v1
+    schedulerName: default-scheduler
+    imagePullPolicy: IfNotPresent
+    imagePullSecrets:
+    - name: nebula-image
+    enablePVReclaim: true
+    topologySpreadConstraints:
+    - topologyKey: kubernetes.io/hostname
+      whenUnsatisfiable: "ScheduleAnyway"
+  ```
 
-It should be noted that only when all configuration items in `config` are the parameters that can be dynamically modified at runtime, can the operation of online modifications be triggered. If the configuration items in `config` contain parameters that cannot be dynamically modified, then the cluster configuration will be updated by restarting the Pod.
+2. Run the `kubectl apply -f nebula_cluster.yaml` to push your configuration changes to the cluster.
 
-For information about the parameters that can be dynamically modified for each service, see the parameter table column of **Whether supports runtime dynamic modifications** in [Meta service configuration parameters](../../5.configurations-and-logs/1.configurations/2.meta-config.md), [Storage service configuration parameters](../../5.configurations-and-logs/1.configurations/4.storage-config.md), and [Graph service configuration parameters](../../5.configurations-and-logs/1.configurations/3.graph-config.md), respectively.
+3. Verify that the configuration takes effect.
 
+  ```bash
+  kubectl get svc
+  ```
 
+  Sample response:
 
+  ```
+  NAME                        TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE
+  nebula-graphd-headless      ClusterIP   None             <none>        3669/TCP,8080/TCP            10m
+  nebula-graphd-svc           ClusterIP   10.102.13.115    <none>        3669/TCP,8080/TCP            10m
+  nebula-metad-headless       ClusterIP   None             <none>        9559/TCP,8081/TCP            11m
+  nebula-storaged-headless    ClusterIP   None             <none>        9779/TCP,8082/TCP,9778/TCP   11m
+  ```
diff --git a/...zh/nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md b/...zh/nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md
@@ -26,7 +26,7 @@ Config map[string]string `json:"config,omitempty"`
   kubectl edit nebulaclusters.apps.nebula-graph.io nebula
   ```
 
-2. 在 YAML 文件的`spec.graphd.config`配置项中，添加`enable_authorize`和`auth_type`。
+2. 在 YAML 文件的`spec.graphd.config`配置项中，添加需要修改的参数。下文以 `enable_authorize`和`auth_type`为例。
 
   ```yaml
   apiVersion: apps.nebula-graph.io/v1alpha1
@@ -56,19 +56,115 @@ Config map[string]string `json:"config,omitempty"`
         "auth_type": "password"
   ...
   ```
+  在`config`字段下可配置的参数详情，请分别参见 [Meta 服务配置参数](../../5.configurations-and-logs/1.configurations/2.meta-config.md)、[Storage 服务配置参数](../../5.configurations-and-logs/1.configurations/4.storage-config.md)、[Graph 服务配置参数](../../5.configurations-and-logs/1.configurations/3.graph-config.md)。
+
+  !!! note
+
+      * 若要在集群运行时动态修改参数配置且不触发 Pod 重启，请确保当前修改的参数全部支持运行时动态修改。参数是否支持运行时动态修改，请查看上述参数详情页各个表格中**是否支持运行时动态修改**一列。
+      * 若本次修改的参数包含一个或多个不支持运行时动态修改的参数，则会触发 Pod 重启。
 
   如果需要为 Meta 服务和 Storage 服务配置`config`，则在`spec.metad.config`和`spec.storaged.config`中添加对应的配置项。
 
 3. 执行`kubectl apply -f nebula_cluster.yaml`使上述更新生效。
 
-  在自定义参数`enable_authorize`和`auth_type`后，Graph 服务对应的 ConfigMap（`nebula-graphd`）中的配置将被覆盖。
+  在修改参数值后，Graph 服务对应的 ConfigMap（`nebula-graphd`）中的配置将被覆盖。
 
+### 配置自定义端口
 
-## 在线修改集群配置
+您可以在`config`字段中添加`port`和`ws_http_port`参数，从而配置自定义的端口。这两个参数的详细信息，请参见[Meta 服务配置参数](../../5.configurations-and-logs/1.configurations/2.meta-config.md)、[Storage 服务配置参数](../../5.configurations-and-logs/1.configurations/4.storage-config.md)、[Graph 服务配置参数](../../5.configurations-and-logs/1.configurations/3.graph-config.md)的 networking 配置一节。
 
-在线修改集群配置主要通过调用`HTTP`接口对集群的配置参数进行修改，而无需重启集群 Pod。
+!!! note
 
-需要注意的是，只有当`config`中的配置项均为可在运行时动态修改的参数时，才能触发在线修改集群配置操作。如果`config`中的配置项包含不可动态修改的参数，那么集群配置将通过重启 Pod 的方式进行更新。
+    * 自定义`port`和`ws_http_port`参数配置后，会触发 Pod 重启，并在重启后生效。 
+    * 在集群启动后，不建议修改`port`参数。
 
-关于各个服务可动态修改的参数，分别参见 [Meta 服务配置参数](../../5.configurations-and-logs/1.configurations/2.meta-config.md)、[Storage 服务配置参数](../../5.configurations-and-logs/1.configurations/4.storage-config.md)、[Graph 服务配置参数](../../5.configurations-and-logs/1.configurations/3.graph-config.md)的配置参数表格中**是否支持运行时动态修改**一列。
+1. 修改集群配置文件。
 
+  ```yaml
+  apiVersion: apps.nebula-graph.io/v1alpha1
+  kind: NebulaCluster
+  metadata:
+    name: nebula
+    namespace: default
+  spec:
+    graphd:
+      config:
+        port: "3669"
+        ws_http_port: "8080"
+      resources:
+        requests:
+          cpu: "200m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-graphd
+      version: {{nebula.tag}}
+    metad:
+      config:
+        ws_http_port: 8081
+      resources:
+        requests:
+          cpu: "300m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-metad
+      version: {{nebula.tag}}
+      dataVolumeClaim:
+        resources:
+          requests:
+            storage: 2Gi
+        storageClassName: local-path
+    storaged:
+      config:
+        ws_http_port: 8082
+      resources:
+        requests:
+          cpu: "300m"
+          memory: "500Mi"
+        limits:
+          cpu: "1"
+          memory: "1Gi"
+      replicas: 1
+      image: vesoft/nebula-storaged
+      version: {{nebula.tag}}
+      dataVolumeClaims:
+      - resources:
+          requests:
+            storage: 2Gi
+        storageClassName: local-path
+      enableAutoBalance: true
+    reference:
+      name: statefulsets.apps
+      version: v1
+    schedulerName: default-scheduler
+    imagePullPolicy: IfNotPresent
+    imagePullSecrets:
+    - name: nebula-image
+    enablePVReclaim: true
+    topologySpreadConstraints:
+    - topologyKey: kubernetes.io/hostname
+      whenUnsatisfiable: "ScheduleAnyway"
+  ```
+
+2. 执行`kubectl apply -f nebula_cluster.yaml`使上述更新生效。
+
+3. 验证配置已经生效。
+
+  ```bash
+  kubectl get svc
+  ```
+
+  返回示例：
+
+  ```
+  NAME                        TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE
+  nebula-graphd-headless      ClusterIP   None             <none>        3669/TCP,8080/TCP            10m
+  nebula-graphd-svc           ClusterIP   10.102.13.115    <none>        3669/TCP,8080/TCP            10m
+  nebula-metad-headless       ClusterIP   None             <none>        9559/TCP,8081/TCP            11m
+  nebula-storaged-headless    ClusterIP   None             <none>        9779/TCP,8082/TCP,9778/TCP   11m
+  ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -582,7 +582,7 @@ nav:
         - Deploy clusters with Helm: nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md
       - Connect to NebulaGraph databases: nebula-operator/4.connect-to-nebula-graph-service.md
       - Configure clusters:
-        - Custom configuration parameters for a NebulaGraph cluster: nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md
+        - Customize parameters for a NebulaGraph cluster: nebula-operator/8.custom-cluster-configurations/8.1.custom-conf-parameter.md
         - Storage:
           - Dynamically expand persistent volumes: nebula-operator/8.custom-cluster-configurations/storage/8.6.dynamic-expand-pv.md 
           - Reclaim PVs: nebula-operator/8.custom-cluster-configurations/storage/8.2.pv-reclaim.md