From a1c66ec68e2cd96693cf38eb85c53339ff7fdddf Mon Sep 17 00:00:00 2001 From: "abby.huang" <78209557+abby-cyber@users.noreply.github.com> Date: Fri, 24 Sep 2021 16:49:46 +0800 Subject: [PATCH] content for Operator (#981) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * operator document * new for clusters and nebula operator added deploy nebula graph clusters by two ways added how to deploy nebula operator * connect to nebula graph cluster connect to nebula graph cluster * add_failover * updated add-get started with operator and add des for parameters * optimization&test updates * added faq * updates * updates * updates * Update docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md reasonable, accepted。 Co-authored-by: randomJoe211 <69501902+randomJoe211@users.noreply.github.com> * updates * updates Co-authored-by: randomJoe211 <69501902+randomJoe211@users.noreply.github.com> --- docs-2.0/20.appendix/6.eco-tool-version.md | 10 +- .../1.introduction-to-nebula-operator.md | 37 ++++ .../2.deploy-nebula-operator.md | 193 +++++++++++++++++ .../3.1create-cluster-with-kubectl.md | 199 ++++++++++++++++++ .../3.2create-cluster-with-helm.md | 124 +++++++++++ .../4.connect-to-nebula-graph-service.md | 140 ++++++++++++ .../nebula-operator/5.operator-failover.md | 37 ++++ .../6.get-started-with-operator.md | 7 + docs-2.0/nebula-operator/7.operator-faq.md | 17 ++ mkdocs.yml | 35 ++- 10 files changed, 788 insertions(+), 11 deletions(-) create mode 100644 docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md create mode 100644 docs-2.0/nebula-operator/2.deploy-nebula-operator.md create mode 100644 docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md create mode 100644 docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md create mode 100644 docs-2.0/nebula-operator/4.connect-to-nebula-graph-service.md create mode 100644 docs-2.0/nebula-operator/5.operator-failover.md create mode 100644 docs-2.0/nebula-operator/6.get-started-with-operator.md create mode 100644 docs-2.0/nebula-operator/7.operator-faq.md diff --git a/docs-2.0/20.appendix/6.eco-tool-version.md b/docs-2.0/20.appendix/6.eco-tool-version.md index 48a4305b19..fac6caaa31 100644 --- a/docs-2.0/20.appendix/6.eco-tool-version.md +++ b/docs-2.0/20.appendix/6.eco-tool-version.md @@ -48,7 +48,7 @@ Nebula Dashboard（简称Dashboard）是一款用于监控Nebula Graph集群中 ## Nebula Explorer -Nebula Explorer（简称 Explorer）是一款可以通过 Web 访问的图探索可视化工具，搭配 Nebula Graph 内核使用，用于与图数据进行可视化交互。即使没有图数据操作经验，用户也可以快速成为图专家。详情参见[什么是Nebula Explorer](../nebula-explorer/about-explorer/ex-ug-what-is-explorer.md)。 +Nebula Explorer（简称Explorer）是一款可以通过Web访问的图探索可视化工具，搭配Nebula Graph内核使用，用于与图数据进行可视化交互。即使没有图数据操作经验，用户也可以快速成为图专家。详情参见[什么是Nebula Explorer](../nebula-explorer/about-explorer/ex-ug-what-is-explorer.md)。 |Nebula Graph版本|Explorer版本（commit id）| |:---|:---| @@ -62,6 +62,14 @@ Nebula Exchange（简称Exchange）是一款Apache Spark™应用，用于 |:---|:---| | {{ nebula.release }} | {{exchange.release}}（3c0f4c6） | +## Nebula Operator + +Nebula Operator（简称Operator）是用于在Kubernetes系统上自动化部署和运维Nebula Graph集群的工具。依托于Kubernetes扩展机制，Nebula Graph将其运维领域的知识全面注入至Kubernetes系统中，让Nebula Graph成为真正的云原生图数据库。详情请参加[什么是Nebula Operator](nebula-operator/1.introduction-to-nebula-operator.md)。 + +|Nebula Graph版本|Operator版本（commit id）| +|:---|:---| +| {{ nebula.release }} | {{operator.release}}（6d1104e） | + ## Nebula Importer Nebula Importer（简称Importer）是一款Nebula Graph的CSV文件导入工具。Importer可以读取本地的CSV文件，然后导入数据至Nebula Graph图数据库中。详情请参见[什么是Nebula Importer](../nebula-importer/use-importer.md)。 diff --git a/docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md b/docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md new file mode 100644 index 0000000000..80c696fe3e --- /dev/null +++ b/docs-2.0/nebula-operator/1.introduction-to-nebula-operator.md @@ -0,0 +1,37 @@ +# 什么是Nebula Operator + +## 基本概念 + +Nebula Operator是用于在[Kubernetes](https://kubernetes.io)系统上自动化部署和运维[Nebula Graph](https://github.com/vesoft-inc/nebula)集群的工具。依托于Kubernetes扩展机制，Nebula Graph将其运维领域的知识全面注入至Kubernetes系统中，让Nebula Graph成为真正的[云原生图数据库](https://www.nebula-cloud.io/)。 + +## 工作原理 + +对于Kubernetes系统内不存在的资源类型，用户可以通过添加自定义API对象的方式注册，常见的方法是使用[CustomResourceDefinition（CRD）](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) 。 + +Nebula Operator将Nebula Graph集群的部署管理抽象为CRD。通过结合多个内置的API对象，包括StatefulSet、Service和ConfigMap，Nebula Graph集群的日常管理和维护被编码为一个控制循环。在Kubernetes系统内，每一种内置资源对象，都运行着一个特定的控制循环，将它的实际状态通过事先规定好的编排动作，逐步调整为最终的期望状态。当一个CR实例被提交时，Nebula Operator会根据控制流程驱动数据库集群进入最终状态。 + +## 功能介绍 + +Nebula Operator已具备的功能如下： + +- **集群创建和卸载**：Nebula Operator简化了用户部署和卸载集群的过程。用户只需提供对应的CR文件，Nebula Operator即可快速创建或者删除一个对应的Nebula Graph集群。更多信息参考[使用Kubectl部署Nebula Graph集群](3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md)或者[使用Helm部署Nebula Graph集群](3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md)。 + +- **集群扩容和缩容**：通过在控制循环中调用Nebula Graph原生提供的扩缩容接口，Nebula Graph封装Nebula Operator实现了扩缩容的逻辑，用户可以通过YAML配置进行简单的扩缩容，且保证数据的稳定性。更多信息参考[使用Kubeclt扩缩容集群](3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl/#_3)或[使用Helm扩缩容集群](3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm/#_2)。 + +- **故障自愈**：Nebula Operator调用Nebula Graph集群提供的接口，动态地感知服务状态。一旦发现异常，Nebula Operator自动进行容错处理。更多信息参考[故障自愈](5.operator-failover.md)。 + +- **均衡调度**: 基于调度器扩展接口，Nebula Operator提供的调度器可以将应用Pods均匀地分布在Nebula Graph集群中。 + +## 使用限制 + +### 版本限制 + +Nebula Operator不支持v1.x版本的Nebula Graph，其与Nebula Graph版本的对应关系如下： + +| Nebula Operator版本 | Nebula Graph版本 | +| ------------------- | ---------------- | +| {{operator.release}}| {{nebula.release}} | + +### 功能限制 + +目前Nebula Operator只支持手动扩缩容Nebula Graph集群，不支持自动扩缩容Nebula Graph集群。 diff --git a/docs-2.0/nebula-operator/2.deploy-nebula-operator.md b/docs-2.0/nebula-operator/2.deploy-nebula-operator.md new file mode 100644 index 0000000000..045f9dbd82 --- /dev/null +++ b/docs-2.0/nebula-operator/2.deploy-nebula-operator.md @@ -0,0 +1,193 @@ +# 部署Nebula Operator + +用户可使用[Helm](https://helm.sh/)工具部署Nebula Operator。 + +## 背景信息 + +[Nebula Operator](1.introduction-to-nebula-operator.md)为用户管理Nebula Graph集群，使用户无需在生产环境中手动安装、扩展、升级和卸载Nebula Graph，减轻用户管理不同应用版本的负担。 + +## 前提条件 + +### 安装软件 + +安装Nebula Operator前，用户需要安装以下软件并确保安装版本的正确性： + +| 软件 | 版本要求 | +| ------------------------------------------------------------ | --------- | +| [Kubernetes](https://kubernetes.io) | \>= 1.16 | +| [Helm](https://helm.sh) | \>= 3.2.0 | +| [CoreDNS](https://github.com/coredns/coredns) | \>= 1.6.0 | +| [CertManager](https://cert-manager.io) | \>= 1.2.0 | +| [OpenKruise](https://openkruise.io) | \>= 0.8.0 | + +如果使用基于角色的访问控制的策略，用户需开启[RBAC](https://kubernetes.io/docs/admin/authorization/rbac)（可选）。 + +### 软件说明 + +!!! note + + 以下内容为Nebula Operator使用的第三方项目，Nebula Operator不负责处理安装这些软件过程中出现的问题. + +- [CoreDNS](https://coredns.io/) + + CoreDNS是一个灵活的、可扩展的DNS服务器，被[安装](https://github.com/coredns/deployment/tree/master/kubernetes)在集群内作为集群内Pods的DNS服务器。 + + Nebula Graph集群中的每个组件通过DNS解析类似`x.default.svc.cluster.local`这样的域名相互通信。 + +- [cert-manager](https://cert-manager.io/) + + !!! note + + 如果用户已将Nebula Operator配置项`admissionWebhook.create`的值设为`false`，无需安装cert-manager。有关配置项的详情，请参考下文**安装Nebula Operator**中的**自定义配置Chart**部分。 + + cert-manager是一个自动化管理证书的工具，利用Kubernetes API扩展功能，使用Webhook服务器提供对cert-manager资源的动态准入控制。用户可参考[cert-manager installation documentation](https://cert-manager.io/docs/installation/kubernetes/)安装cert-manager。 + + cert-manager用于验证Nebula Graph的每个组件副本。如果用户在生产环境中运行它并关心Nebula Graph的高可用性，建议将`admissionWebhook.create`的值设为`true`，然后再安装cert-manager。 + +- [OpenKruise](https://openkruise.io/en-us/) + + OpenKruise是Kubernetes的一整套标准扩展，能与原始的Kubernetes一起工作，为应用Pod、Sidecar容器，甚至是节点中的镜像的管理供更强大和高效的功能。Nebula Operator启动时需要用到OpenKruise开启针对StatefulSet的高级功能。用户可参考[openkruise installation documentation](https://openkruise.io/en-us/docs/installation.html)安装OpenKruise。 + +## 操作步骤 + +### 安装Nebula Operator + +1. 添加Nebula Operator chart仓库至Helm。 + + ```bash + helm repo add nebula-operator https://vesoft-inc.github.io/nebula-operator/charts + ``` + +2. 拉取最新的Helm仓库。 + + ```bash + helm repo update + ``` + + 参考[Helm仓库](https://helm.sh/docs/helm/helm_repo/)获取更多`helm repo`相关信息。 + +3. 安装Nebula Operator。 + + ```bash + helm install nebula-operator nebula-operator/nebula-operator --namespace= --version=${chart_version} + ``` + + - 上述命令中的``为用户创建的命名空间。如果用户未创建该命名空间，可以执行`kubectl create namespace nebula-operator-system`进行创建。用户也可创建其他命名空间。 + + - `${chart_version}`为Nebula Operator chart的版本。当Chart中只有一个默认版本时，可不指定。执行`helm search repo -l nebula-operator`查看Chart版本。 + + 用户可在执行安装Nebula Operator chart命令时自定义其配置。更多信息，查看下文**自定义配置Chart**。 + +### 自定义配置Chart + +执行`helm show values [CHART] [flags]`查看可配置的选项。 + +示例如下： + +```yaml +[abby@master ~]$ helm show values nebula-operator/nebula-operator +image: + nebulaOperator: + image: vesoft/nebula-operator:v0.8.0 + imagePullPolicy: IfNotPresent + kubeRBACProxy: + image: gcr.io/kubebuilder/kube-rbac-proxy:v0.8.0 + imagePullPolicy: IfNotPresent + kubeScheduler: + image: k8s.gcr.io/kube-scheduler:v1.18.8 + imagePullPolicy: IfNotPresent + +imagePullSecrets: [] +kubernetesClusterDomain: "" + +controllerManager: + create: true + replicas: 2 + env: [] + resources: + limits: + cpu: 100m + memory: 30Mi + requests: + cpu: 100m + memory: 20Mi + +admissionWebhook: + create: true + +scheduler: + create: true + schedulerName: nebula-scheduler + replicas: 2 + env: [] + resources: + limits: + cpu: 100m + memory: 30Mi + requests: + cpu: 100m + memory: 20Mi +``` + +`values.yaml`中参数描述如下： + +| 参数 | 默认值 | 描述 | +| :------------------------------------- | :------------------------------ | :----------------------------------------- | +| `image.nebulaOperator.image` | `vesoft/nebula-operator:v0.8.0` | Nebula Operator的镜像，版本为v0.8.0。 | +| `image.nebulaOperator.imagePullPolicy` | `IfNotPresent` | 镜像拉取策略。 | +| `imagePullSecrets` | - | 镜像拉取密钥。 | +| `kubernetesClusterDomain` | `cluster.local`。 | 集群域名。 | +| `controllerManager.create` | `true` | 是否启用controller-manager。 | +| `controllerManager.replicas` | `2` | controller-manger副本数。 | +| `admissionWebhook.create` | `true` | 是否启用Admission Webhook。 | +| `shceduler.create` | `true` | 是否启用Scheduler。 | +| `shceduler.schedulerName` | `nebula-scheduler` | 调度器名称。 | +| `shceduler.replicas` | `2` | nebula-scheduler副本数。 | + +执行`helm install [NAME] [CHART] [flags]`命令安装Chart时，可指定Chart配置。更多信息，参考[安装前自定义Chart](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)。 + +以下示例为在安装Nebula Operator时，指定Nebula Operator的AdmissionWebhook机制为关闭状态（默认开启AdmissionWebhook）： + +```bash +helm install nebula-operator nebula-operator/nebula-operator --namespace= --set admissionWebhook.create=false +``` + +参考[Helm安装](https://helm.sh/docs/helm/helm_install/)获取更多`helm install`相关信息。 + +### 更新Nebula Operator + +用户安装Nebula Operator后，可通过修改`${HOME}/nebula-operator/charts/nebula-operator/values.yaml`文件中参数的值来更新Nebula Operator。操作步骤如下： + +1. 克隆Nebula Operator仓库至本机。 + + ```bash + git clone https://github.com/vesoft-inc/nebula-operator.git + ``` + +2. 修改`${HOME}/nebula-operator/charts/nebula-operator/values.yaml`文件中的参数值。 + +3. 更新Nebula Operator。 + + ```bash + helm upgrade nebula-operator nebula-operator/nebula-operator --namespace= -f ${HOME}/nebula-operator/charts/nebula-operator/values.yaml + ``` + + ``为用户创建的命名空间，nebula-operator相关Pods在此命名空间下。 + +### 卸载Nebula Operator + +1. 卸载Nebula Operator chart。 + + ```bash + helm uninstall nebula-operator --namespace= + ``` + +2. 删除CRD。 + + ```bash + kubectl delete crd nebulaclusters.apps.nebula-graph.io + ``` + +## 后续操作 + +使用Nebula Operator自动化部署Nebula Graph集群。更多信息，请参考[使用Kubectl部署Nebula Graph集群](3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md)或者[使用Helm部署Nebula Graph集群](3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md)。 diff --git a/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md b/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md new file mode 100644 index 0000000000..7287112928 --- /dev/null +++ b/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md @@ -0,0 +1,199 @@ +# 使用Kubectl部署Nebula Graph集群 + +## 前提条件 + +[安装Nebula Operator](2.deploy-nebula-operator.md) + +## 创建集群 + +本文以创建名为`nebula`的集群为例，说明如何部署Nebula Graph集群。 + +1. 创建名为`apps_v1alpha1_nebulacluster.yaml`的文件。 + + 示例文件的内容如下： + + ```yaml + apiVersion: apps.nebula-graph.io/v1alpha1 + kind: NebulaCluster + metadata: + name: nebula + spec: + graphd: + resources: + requests: + cpu: "500m" + memory: "500Mi" + limits: + cpu: "1" + memory: "1Gi" + replicas: 1 + image: vesoft/nebula-graphd + version: v2.5.1 + service: + type: NodePort + externalTrafficPolicy: Local + storageClaim: + resources: + requests: + storage: 2Gi + storageClassName: gp2 + metad: + resources: + requests: + cpu: "500m" + memory: "500Mi" + limits: + cpu: "1" + memory: "1Gi" + replicas: 1 + image: vesoft/nebula-metad + version: v2.5.1 + storageClaim: + resources: + requests: + storage: 2Gi + storageClassName: gp2 + storaged: + resources: + requests: + cpu: "500m" + memory: "500Mi" + limits: + cpu: "1" + memory: "1Gi" + replicas: 3 + image: vesoft/nebula-storaged + version: v2.5.1 + storageClaim: + resources: + requests: + storage: 2Gi + storageClassName: gp2 + reference: + name: statefulsets.apps + version: v1 + schedulerName: default-scheduler + imagePullPolicy: IfNotPresent + ``` + + 参数描述如下： + + | 参数 | 默认值 | 描述 | + | :---- | :--- | :--- | + | `metadata.name` | - | 创建的Nebula Graph集群名称。 | + | `spec.graphd.replicas` | `1` | Graphd服务的副本数。 | + | `spec.graphd.images` | `vesoft/nebula-graphd` | Graphd服务的容器镜像。 | + | `spec.graphd.version` | `v2.5.1` | Graphd服务的版本号。 | + | `spec.graphd.service` | - | Graphd服务Service配置。 | + | `spec.graphd.storageClaim` | - | Graphd服务存储配置。 | + | `spec.metad.replicas` | `1` | Metad服务的副本数。 | + | `spec.metad.images` | `vesoft/nebula-metad` | Metad服务的容器镜像。 | + | `spec.metad.version` | `v2.5.1` | Metad服务的版本号。 | + | `spec.metad.storageClaim` | - | Metad服务存储配置。 | + | `spec.storaged.replicas` | `3` | Storaged服务的副本数。 | + | `spec.storaged.images` | `vesoft/nebula-storaged` | Storaged服务的容器镜像。 | + | `spec.storaged.version` | `v2.5.1` | Storaged服务的版本号。 | + | `spec.storaged.storageClaim` | - | Storaged服务存储配置。 | + | `spec.reference.name` | - | 依赖的控制器名称。 | + | `spec.schedulerName` | - | 调度器名称。 | + | `spec.imagePullPolicy` | Nebula Graph镜像的拉取策略。关于拉取策略详情，请参考[Image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)。 | 镜像拉取策略。 | + + +2. 创建Nebula Graph集群。 + + ```bash + kubectl create -f apps_v1alpha1_nebulacluster.yaml + ``` + + 返回： + + ```bash + nebulacluster.apps.nebula-graph.io/nebula created + ``` + +3. 查看Nebula Graph集群状态。 + + ```bash + kubectl get nebulaclusters.apps.nebula-graph.io nebula + ``` + + 返回： + + ```bash + NAME GRAPHD-DESIRED GRAPHD-READY METAD-DESIRED METAD-READY STORAGED-DESIRED STORAGED-READY AGE + nebula-cluster 1 1 1 1 3 3 31h + ``` + +## 扩缩容集群 + +用户可以通过编辑`apps_v1alpha1_nebulacluster.yaml`文件中的`replicas`的值进行Nebula Graph集群的扩缩容。 + +### 扩容集群 + +本文举例扩容Nebula Graph集群中Storage服务至5个。步骤如下： + +1. 将`apps_v1alpha1_nebulacluster.yaml`文件中`storaged.replicas`的参数值从`3`改为`5`。 + + ```yaml + storaged: + resources: + requests: + cpu: "1" + memory: "1Gi" + limits: + cpu: "1" + memory: "1Gi" + replicas: 5 + image: vesoft/nebula-storaged + version: v2.5.1 + storageClaim: + resources: + requests: + storage: 2Gi + storageClassName: fast-disks + ``` + +2. 执行以下命令使上述更新同步至Nebula Graph集群CR中。 + + ```bash + kubectl apply -f apps_v1alpha1_nebulacluster.yaml + ``` + +3. 查看Storage服务的副本数。 + + ```bash + kubectl get pods -l app.kubernetes.io/cluster=nebula + ``` + 返回： + + ```bash + NAME READY STATUS RESTARTS AGE + nebula-graphd-0 1/1 Running 0 2m + nebula-metad-0 1/1 Running 0 2m + nebula-storaged-0 1/1 Running 0 2m + nebula-storaged-1 1/1 Running 0 2m + nebula-storaged-2 1/1 Running 0 2m + nebula-storaged-3 1/1 Running 0 5m + nebula-storaged-4 1/1 Running 0 5m + ``` + 由上可看出Storage服务的副本数被扩容至5个。 + +### 缩容集群 + +缩容集群的原理和扩容一样，用户只需将`apps_v1alpha1_nebulacluster.yaml`文件中的`replicas`的值缩小。具体操作，请参考上文的**扩容集群**部分。 + +!!! caution + + 目前仅支持对Nebula Graph集群中的Graph服务和Storage服务进行扩缩容，不支持扩缩容Meta服务。 + +## 删除集群 + +使用Kubectl删除Nebula Graph集群的命令如下： + +```bash +kubectl delete -f apps_v1alpha1_nebulacluster.yaml +``` + +## 后续操作 + +[连接Nebula Graph数据库](4.connect-to-nebula-graph-service.md) \ No newline at end of file diff --git a/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md b/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md new file mode 100644 index 0000000000..84066efe68 --- /dev/null +++ b/docs-2.0/nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md @@ -0,0 +1,124 @@ +# 使用Helm部署Nebula Graph集群 + +## 前提条件 + +[安装Nebula Operator](2.deploy-nebula-operator.md) + +## 创建Nebula Graph集群 + +1. 添加Nebula Operator chart至Helm仓库（如已创添加，略过前面1至2步，从第3步开始执行）。 + + ```bash + helm repo add nebula-operator https://vesoft-inc.github.io/nebula-operator/charts + ``` + +2. 更新Helm仓库，拉取最新仓库资源。 + + ```bash + helm repo update + ``` + +3. 配置Helm的环境变量。 + + ```bash + export NEBULA_CLUSTER_NAME=nebula # Nebula Graph集群的名字。 + export NEBULA_CLUSTER_NAMESPACE=nebula # Nebula Graph集群所处的命名空间的名字。 + export STORAGE_CLASS_NAME=gp2 # Nebula Graph集群的StorageClass。 + ``` + +4. 为Nebula Graph集群创建命名空间（如已创建，略过此步）。 + + ```bash + kubectl create namespace "${NEBULA_CLUSTER_NAMESPACE}" + ``` + +5. 创建Nebula Graph集群。 + + ```bash + helm install "${NEBULA_CLUSTER_NAME}" nebula-operator/nebula-cluster \ + --namespace="${NEBULA_CLUSTER_NAMESPACE}" \ + --set nameOverride=${NEBULA_CLUSTER_NAME} \ + --set nebula.storageClassName="${STORAGE_CLASS_NAME}" + ``` + +6. 查看Nebula Graph集群创建状态。 + + ```bash + kubectl -n "${NEBULA_CLUSTER_NAMESPACE}" get pod -l "app.kubernetes.io/cluster=${NEBULA_CLUSTER_NAME}" + ``` + 返回示例： + + ```bash + NAME READY STATUS RESTARTS AGE + nebula-graphd-0 1/1 Running 0 5m34s + nebula-graphd-1 1/1 Running 0 5m34s + nebula-metad-0 1/1 Running 0 5m34s + nebula-metad-1 1/1 Running 0 5m34s + nebula-metad-2 1/1 Running 0 5m34s + nebula-storaged-0 1/1 Running 0 5m34s + nebula-storaged-1 1/1 Running 0 5m34s + nebula-storaged-2 1/1 Running 0 5m34s + ``` + +## 扩缩容集群 + +用户可通过定义Nebula Graph中不同服务对应的`replicas`的值扩缩容Nebuala Graph集群。 + +例如，扩容Nebula Graph集群中Storage的副本数为5（原始值为2），命令如下： + +```bash +helm upgrade "${NEBULA_CLUSTER_NAME}" nebula-operator/nebula-cluster \ + --namespace="${NEBULA_CLUSTER_NAMESPACE}" \ + --set nameOverride=${NEBULA_CLUSTER_NAME} \ + --set nebula.storageClassName="${STORAGE_CLASS_NAME}" \ + --set nebula.storaged.replicas=5 +``` + +同理，将Nebula Graph集群中服务对应的`replicas`的值设置成小于原始值，即可实现集群服务的缩容。 + +!!! caution + + 目前仅支持对Nebula Graph集群中的Graph服务和Storage服务进行扩缩容，不支持扩缩容Meta服务。 + +用户可点击[nebula-cluster/values.yaml](https://github.com/vesoft-inc/nebula-operator/blob/{{operator.branch}}/charts/nebula-cluster/values.yaml)查看Nebula Cluster集群Chart的更多配置。有关文件中配置项的解释，参考下文**Nebula Graph集群Chart配置参数说明**。 + +## 删除集群 + +使用Helm删除集群的命令如下： + +```bash +helm uninstall "${NEBULA_CLUSTER_NAME}" --namespace="${NEBULA_CLUSTER_NAMESPACE}" +``` + +## 后续操作 + +[连接Nebula Graph数据库](4.connect-to-nebula-graph-service.md) + +## Nebula Graph集群Chart配置参数说明 + +| 参数 | 默认值 | 描述 | +| :-------------------------- | :----------------------------------------------------------- | ------------------------------------------------------------ | +| `nameOverride` | `nil` | 覆盖集群Chart的名称。 | +| `nebula.version` | `v2.5.1` | Nebula Graph的版本。 | +| `nebula.imagePullPolicy` | `IfNotPresent` | Nebula Graph镜像的拉取策略。关于拉取策略详情，请参考[Image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)。 | +| `nebula.storageClassName` | `nil` | 持久存储卷的类型，默认使用StorageClass的名字。 | +| `nebula.schedulerName` | `default-scheduler` | Nebula Graph集群的调度器。 | +| `nebula.reference` | `{"name": "statefulsets.apps", "version": "v1"}` | 为Nebula Graph引用的工作负载。 | +| `nebula.podLabels` | `{}` | Nebula Graph服务Pod的标签。 | +| `nebula.podAnnotations` | `{}` | Nebula Graph服务的注解。 | +| `nebula.graphd.image` | `vesoft/nebula-graphd` | Graphd容器镜像名称。使用 `nebula.version`中的值作为版本。 | +| `nebula.graphd.replicas` | `2` | Graphd服务的副本数。 | +| `nebula.graphd.env` | `[]` | Graphd服务的环境变量。 | +| `nebula.graphd.resources` | `{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"1Gi"}}}` | Graphd资源配置。 | +| `nebula.graphd.storage` | `1Gi` | Graphd服务的存储大小值。 | +| `nebula.metad.image` | `vesoft/nebula-metad` | Metad容器镜像名称。使用 `nebula.version`中的值作为版本。 | +| `nebula.metad.replicas` | `3` | Metad服务的副本数。 | +| `nebula.metad.env` | `[]` | Metad服务的环境变量。 | +| `nebula.metad.resources` | `{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"1Gi"}}}` | Metad服务的资源配置。 | +| `nebula.metad.storage` | `1Gi` | Graphd服务的存储大小值。 | +| `nebula.storaged.image` | `vesoft/nebula-storaged` | Storaged容器镜像名称。使用 `nebula.version`中的值作为版本。 | +| `nebula.storaged.replicas` | `3` | Storaged服务的副本数。 | +| `nebula.storaged.env` | `[]` | Storaged服务的环境变量。 | +| `nebula.storaged.resources` | `{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"1Gi"}}}` | Storaged服务的资源配置。 | +| `nebula.storaged.storage` | `1Gi` | Storaged服务的存储空间值。 | +| `imagePullSecrets` | `[]` | 拉取镜像的Secret。 | \ No newline at end of file diff --git a/docs-2.0/nebula-operator/4.connect-to-nebula-graph-service.md b/docs-2.0/nebula-operator/4.connect-to-nebula-graph-service.md new file mode 100644 index 0000000000..f0b1b4a200 --- /dev/null +++ b/docs-2.0/nebula-operator/4.connect-to-nebula-graph-service.md @@ -0,0 +1,140 @@ +# 通过Nebular Operator连接Nebula Graph数据库 + +使用Nebula Operator创建Nebula Graph集群后，用户可在Nebula Graph集群内部访问Nebula Graph数据库，也可在集群外访问Nebula Graph数据库。 + +## 前提条件 + +[使用Nebula Operator创建Nebula Graph集群](nebula-operator/3.deploy-nebula-graph-cluster) + +## 在Nebula Graph集群内连接Nebula Graph数据库 + +当使用Nebula Operator创建Nebula Graph集群后，Nebula Operator会自动在同一命名空间下，创建名为`-graphd-svc`、类型为`ClusterIP`的Service。通过该Service的IP和数据库的端口号，用户可连接Nebula Graph数据库。 + +1. 查看Service，命令如下： + + ```bash + $ kubectl get service -l app.kubernetes.io/cluster= #为变量值，请用实际集群名称替换。 + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + nebula-graphd-svc ClusterIP 10.10.1.2 9669/TCP,19669/TCP,19670/TCP 23h + nebula-metad-headless ClusterIP None 9559/TCP,19559/TCP,19560/TCP 23h + nebula-storaged-headless ClusterIP None 9779/TCP,19779/TCP,19780/TCP,9778/TCP 23h + ``` + + `ClusterIP`类型的Service只允许在集群内部访问容器应用。更多信息，请参考[ClusterIP](https://kubernetes.io/docs/concepts/services-networking/service/)。 + +2. 使用上述`-graphd-svc` Service的IP连接Nebula Graph数据库： + + ```bash + kubectl run -ti --image vesoft/nebula-console:v2.5.0 --restart=Never -- -addr <10.10.1.2> -port 9669 -u -p + ``` + + - `--image`：为连接Nebula Graph的工具Nebula Console的镜像。 + - ``：自定义的Pod名称。 + - `-addr`：连接的graphd服务的IP地址，即`ClusterIP`类型的Service IP地址。 + - `-port`：连接graphd服务的端口。默认端口为9669。 + - `-u`：Nebula Graph账号的用户名。未启用身份认证时，可以使用任意已存在的用户名（默认为root）。 + - `-p`：用户名对应的密码。未启用身份认证时，密码可以填写任意字符。 + + 如果返回以下内容，说明成功连接数据库： + + ```bash + If you don't see a command prompt, try pressing enter. + + (root@nebula) [(none)]> + ``` + +用户还可以使用**完全限定域名（FQDN）**连接数据库，域名格式为`-graphd..svc.`： + +```bash +kubectl run -ti --image vesoft/nebula-console:v2.5.0 --restart=Never -- -addr -graphd-svc.default.svc.cluster.local -port 9669 -u root -p vesoft +``` +`CLUSTER_DOMAIN`的默认值为`cluster.local`。 + +## 在Nebula Graph集群外部连接Nebula Graph数据库 + +用户可创建`NodePort`类型的Service，通过节点IP和暴露的节点端口，从集群外部访问集群内部的服务。用户也可以使用云厂商提供的负载均衡服务，设置Service的类型为`LoadBalancer`。 + +`NodePort`类型的Service通过标签选择器`spec.selector`将前端的请求转发到带有标签`app.kubernetes.io/cluster: `、`app.kubernetes.io/component: graphd`的Graphd pod中。 + +操作步骤如下： + +1. 创建名为`graphd-nodeport-service.yaml`的文件。YAML文件内容如下： + + ```yaml + apiVersion: v1 + kind: Service + metadata: + labels: + app.kubernetes.io/cluster: nebula + app.kubernetes.io/component: graphd + app.kubernetes.io/managed-by: nebula-operator + app.kubernetes.io/name: nebula-graph + name: nebula-graphd-svc-nodeport + namespace: default + spec: + externalTrafficPolicy: Local + ports: + - name: thrift + port: 9669 + protocol: TCP + targetPort: 9669 + - name: http + port: 19669 + protocol: TCP + targetPort: 19669 + selector: + app.kubernetes.io/cluster: nebula + app.kubernetes.io/component: graphd + app.kubernetes.io/managed-by: nebula-operator + app.kubernetes.io/name: nebula-graph + type: NodePort + ``` + + - Nebula Graph默认使用`9669`端口为客户端提供服务。`19669`为Graph服务端口号。 + - `targetPort`的值为映射至Pod的端口，可自定义。 + +2. 执行以下命令使Service服务在集群中生效。 + + ```bash + kubectl create -f graphd-nodeport-service.yaml + ``` + +3. 查看Service中Nebula Graph映射至集群节点的端口。 + + ```bash + kubectl get services + ``` + + 返回： + + ```bash + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + nebula-graphd-svc ClusterIP 10.10.1.2 9669/TCP,19669/TCP,19670/TCP 23h + nebula-graphd-svc-nodeport NodePort 10.20.1.2 9669:32236/TCP,19669:31674/TCP,19670:31057/TCP 24h + nebula-metad-headless ClusterIP None 9559/TCP,19559/TCP,19560/TCP 23h + nebula-storaged-headless ClusterIP None 9779/TCP,19779/TCP,19780/TCP,9778/TCP 23h + ``` + + NodePort类型的Service中，映射至集群节点的端口为`32236`。 + +4. 使用节点IP和上述映射的节点端口连接Nebula Graph。 + + ```bash + kubectl run -ti --image vesoft/nebula-console:v2.5.0 --restart=Never -- -addr -port -u root -p vesoft + ``` + + 示例如下： + + ```bash + [root@k8s4 ~]# kubectl run -ti --image vesoft/nebula-console:v2.5.0 --restart=Never -- nebula-console2 -addr 192.168.8.24 -port 32236 -u root -p vesoft + If you don't see a command prompt, try pressing enter. + + (root@nebula) [(none)]> + ``` + + - `--image`：为连接Nebula Graph的工具Nebula Console的镜像。 + - ``：自定义的Pod名称。本示例为`nebula-console2`。 + - `-addr`：Nebula Graph集群中任一节点IP地址。本示例为`192.168.8.24`。 + - `-port`：Nebula Graph映射至节点的端口。本示例为`32236`。 + - `-u`：Nebula Graph账号的用户名。未启用身份认证时，可以使用任意已存在的用户名（默认为root）。 + - `-p`：用户名对应的密码。未启用身份认证时，密码可以填写任意字符。 \ No newline at end of file diff --git a/docs-2.0/nebula-operator/5.operator-failover.md b/docs-2.0/nebula-operator/5.operator-failover.md new file mode 100644 index 0000000000..2677d69717 --- /dev/null +++ b/docs-2.0/nebula-operator/5.operator-failover.md @@ -0,0 +1,37 @@ +# 故障自愈 + +Nebula Operator调用Nebula Graph集群提供的接口，动态地感知服务是否正常运行。当Nebula Graph集群中某一组件停止运行时，Nebula Operator会自动地进行容错处理。本文通过删除Nebula Graph集群中1个Storage服务Pod，模拟集群故障为例，说明Nebular Operator如何进行故障自愈。 + +## 前提条件 + +[安装Nebula Operator](2.deploy-nebula-operator.md) + +## 操作步骤 + +1. 创建Nebula Graph集群。具体步骤，请参考[使用Nebula Operator创建Nebula Graph集群](nebula-operator/3.deploy-nebula-graph-cluster)。 + +2. 待所有Pods都处于`Running`状态时，模拟故障，删除名为`-storaged-2 Pod`。 + + ```bash + kubectl delete pod -storaged-2 --now + ``` +``为Nebula Graph集群的名称。 + +3. Nebula Operator自动创建名为`-storaged-2`的Pod，以修复故障。 + + 执行`kubectl get pods`查看`-storaged-2`Pod的创建状态。 + + ```bash + ... + nebula-cluster-storaged-1 1/1 Running 0 5d23h + nebula-cluster-storaged-2 0/1 ContainerCreating 0 1s + ... + ``` + + ```bash + ... + nebula-cluster-storaged-1 1/1 Running 0 5d23h + nebula-cluster-storaged-2 1/1 Running 0 4m2s + ... + ``` +当`-storaged-2`的状态由`ContainerCreating`变为`Running`时，说明成功转移故障。 diff --git a/docs-2.0/nebula-operator/6.get-started-with-operator.md b/docs-2.0/nebula-operator/6.get-started-with-operator.md new file mode 100644 index 0000000000..45c6decee7 --- /dev/null +++ b/docs-2.0/nebula-operator/6.get-started-with-operator.md @@ -0,0 +1,7 @@ +# 使用流程 + +使用Nebula Operator访问Nebula Graph集群服务的流程如下： + +1. [安装Nebula Operator](2.deploy-nebula-operator.md) +2. [创建Nebula Graph集群](3.deploy-nebula-graph-cluster) +3. [连接Nebula Graph服务](4.connect-to-nebula-graph-service.md) \ No newline at end of file diff --git a/docs-2.0/nebula-operator/7.operator-faq.md b/docs-2.0/nebula-operator/7.operator-faq.md new file mode 100644 index 0000000000..06264946cc --- /dev/null +++ b/docs-2.0/nebula-operator/7.operator-faq.md @@ -0,0 +1,17 @@ +# 常见问题 + +## Nebula Operator支持v1.x版本的Nebula Graph吗？ + +不支持，因为v1.x版本的Nebula Graph不支持DNS，而Nebula Operator需要使用DNS。 + +## 是否支持升级Nebula Operator操作？ + +暂不支持。 + +## 使用本地存储是否可以保证集群稳定性？ + +无法保证。使用本地存储意味着Pod被绑定到一个特定的节点，Nebula Operator目前不支持在绑定的节点发生故障时进行故障转移。 + +## 扩缩容集群时，如何确保稳定性？ + +建议提前备份数据，以便故障发生时回滚数据。 diff --git a/mkdocs.yml b/mkdocs.yml index 632aafe131..0e26571c2a 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,6 +104,10 @@ extra: bench: release: 1.0.0 branch: master + operator: + release: 0.8.0 + branch: v0.8.0 + nav: - PDF: ./pdf/NebulaGraph-CN.pdf - 前言: README.md @@ -414,10 +418,21 @@ nav: - 导入SST文件数据: nebula-exchange/use-exchange/ex-ug-import-from-sst.md - Exchange 常见问题: nebula-exchange/ex-ug-FAQ.md + - Nebula Operator: + - 什么是Nebula Operator: nebula-operator/1.introduction-to-nebula-operator.md + - 使用流程: nebula-operator/6.get-started-with-operator.md + - 部署Nebula Operator: nebula-operator/2.deploy-nebula-operator.md + - 部署Nebula Graph集群: + - 使用Kubectl部署Nebula Graph集群: nebula-operator/3.deploy-nebula-graph-cluster/3.1create-cluster-with-kubectl.md + - 使用Helm部署Nebula Graph集群: nebula-operator/3.deploy-nebula-graph-cluster/3.2create-cluster-with-helm.md + - 连接Nebula Graph数据库: nebula-operator/4.connect-to-nebula-graph-service.md + - 故障自愈: nebula-operator/5.operator-failover.md + - 常见问题: nebula-operator/7.operator-faq.md + - Nebula Algorithm: nebula-algorithm.md - Nebula Spark Connector: nebula-spark-connector.md - + - Nebula Flink Connector: nebula-flink-connector.md - Nebula Bench: nebula-bench.md @@ -457,19 +472,19 @@ plugins: - git-revision-date-localized - with-pdf: copyright: 2021 Vesoft Inc. - cover_subtitle: master since 2.5.1 - author: 吴敏，周瑶，梁振亚，杨怡璇 + cover_subtitle: master since master + author: 吴敏，周瑶，梁振亚，杨怡璇，黄凤仙 cover: true back_cover: true cover_logo: 'https://cloud-cdn.nebula-graph.com.cn/nebula-for-pdf.png' output_path: pdf/NebulaGraph-CN.pdf - #show_anchors: true - #render_js: true - #headless_chrome_path: headless-chromium - #enabled_if_env: ENABLE_PDF_EXPORT - #debug_html: true - #show_anchors: true - #verbose: true + show_anchors: true + render_js: true + headless_chrome_path: headless-chromium + enabled_if_env: ENABLE_PDF_EXPORT + debug_html: true + show_anchors: true + verbose: true extra_javascript: - js/version-select.js