Connect to NebulaGraph databases with Nebular Operator¶

After creating a NebulaGraph cluster with NebulaGraph Operator on Kubernetes, you can connect to NebulaGraph databases from within the cluster and outside the cluster.

Prerequisites¶

Create a NebulaGraph cluster with NebulaGraph Operator on Kubernetes. For more information, see Deploy NebulaGraph clusters with Kubectl or Deploy NebulaGraph clusters with Helm.

Connect to NebulaGraph databases from within a NebulaGraph cluster¶

When a NebulaGraph cluster is created, NebulaGraph Operator automatically creates a Service named <cluster-name>-graphd-svc with the type ClusterIP under the same namespace. With the IP of the Service and the port number of the NebulaGraph database, you can connect to the NebulaGraph database.

Run the following command to check the IP of the Service:

$ kubectl get service -l app.kubernetes.io/cluster=<nebula>  #<nebula> is a variable value. Replace it with the desired name.
NAME                       TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                                          AGE
nebula-graphd-svc          ClusterIP   10.98.213.34   <none>        9669/TCP,19669/TCP,19670/TCP                     23h
nebula-metad-headless      ClusterIP   None           <none>        9559/TCP,19559/TCP,19560/TCP                     23h
nebula-storaged-headless   ClusterIP   None           <none>        9779/TCP,19779/TCP,19780/TCP,9778/TCP            23h

Services of the ClusterIP type only can be accessed by other applications in a cluster. For more information, see ClusterIP.

Run the following command to connect to the NebulaGraph database using the IP of the <cluster-name>-graphd-svc Service above:

kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- <nebula_console_name> -addr <cluster_ip>  -port <service_port> -u <username> -p <password>

For example:

kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- nebula-console -addr 10.98.213.34  -port 9669 -u root -p vesoft

- `--image`: The image for the tool NebulaGraph Console used to connect to NebulaGraph databases.
- `<nebula-console>`: The custom Pod name.
- `-addr`: The IP of the `ClusterIP` Service, used to connect to Graphd services.
- `-port`: The port to connect to Graphd services, the default port of which is 9669.
- `-u`: The username of your NebulaGraph account. Before enabling authentication, you can use any existing username. The default username is root.
- `-p`: The password of your NebulaGraph account. Before enabling authentication, you can use any characters as the password.

A successful connection to the database is indicated if the following is returned:

```bash
If you don't see a command prompt, try pressing enter.

(root@nebula) [(none)]>

You can also connect to NebulaGraph databases with Fully Qualified Domain Name (FQDN). The domain format is <cluster-name>-graphd.<cluster-namespace>.svc.<CLUSTER_DOMAIN>:

kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- <nebula_console_name> -addr <cluster_name>-graphd-svc.default.svc.cluster.local -port <service_port> -u <username> -p <password>

The default value of CLUSTER_DOMAIN is cluster.local.

Connect to NebulaGraph databases from outside a NebulaGraph cluster via `NodePort`¶

You can create a Service of type NodePort to connect to NebulaGraph databases from outside a NebulaGraph cluster with a node IP and an exposed node port. You can also use load balancing software provided by cloud providers (such as Azure, AWS, etc.) and set the Service of type LoadBalancer.

The Service of type NodePort forwards the front-end requests via the label selector spec.selector to Graphd pods with labels app.kubernetes.io/cluster: <cluster-name> and app.kubernetes.io/component: graphd.

Steps:

Create a YAML file named graphd-nodeport-service.yaml. The file contents are as follows:

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

NebulaGraph uses port 9669 by default. 19669 is the port of the Graph service in a NebulaGraph cluster.
The value of targetPort is the port mapped to the database Pods, which can be customized.

Run the following command to create a NodePort Service.
```
kubectl create -f graphd-nodeport-service.yaml
```

Check the port mapped on all of your cluster nodes.

kubectl get services

Output:

NAME                           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                                          AGE
nebula-graphd-svc              ClusterIP   10.98.213.34   <none>        9669/TCP,19669/TCP,19670/TCP                     23h
nebula-graphd-svc-nodeport     NodePort    10.107.153.129 <none>        9669:32236/TCP,19669:31674/TCP,19670:31057/TCP   24h
nebula-metad-headless          ClusterIP   None           <none>        9559/TCP,19559/TCP,19560/TCP                     23h
nebula-storaged-headless       ClusterIP   None           <none>        9779/TCP,19779/TCP,19780/TCP,9778/TCP            23h

As you see, the mapped port of NebulaGraph databases on all cluster nodes is 32236.

Connect to NebulaGraph databases with your node IP and the node port above.
```
kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- <nebula_console_name> -addr <node_ip> -port <node_port> -u <username> -p <password>
```
For example:
```
kubectl run -ti --image vesoft/nebula-console:v3.2.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: The image for the tool NebulaGraph Console used to connect to NebulaGraph databases.
- <nebula-console>: The custom Pod name. The above example uses nebula-console2.
- -addr: The IP of any node in a NebulaGraph cluster. The above example uses 192.168.8.24.
- -port: The mapped port of NebulaGraph databases on all cluster nodes. The above example uses 32236.
- -u: The username of your NebulaGraph account. Before enabling authentication, you can use any existing username. The default username is root.
- -p: The password of your NebulaGraph account. Before enabling authentication, you can use any characters as the password.

Connect to NebulaGraph databases from outside a NebulaGraph cluster via Ingress¶

Nginx Ingress is an implementation of Kubernetes Ingress. Nginx Ingress watches the Ingress resource of a Kubernetes cluster and generates the Ingress rules into Nginx configurations that enable Nginx to forward 7 layers of traffic.

You can use Nginx Ingress to connect to a NebulaGraph cluster from outside the cluster using a combination of the HostNetwork and DaemonSet pattern.

As HostNetwork is used, the Nginx Ingress pod cannot be scheduled to the same node. To avoid listening port conflicts, some nodes can be selected and labeled as edge nodes in advance, which are specially used for the Nginx Ingress deployment. Nginx Ingress is then deployed on these nodes in a DaemonSet mode.

Ingress does not support TCP or UDP services. For this reason, the nginx-ingress-controller pod uses the flags --tcp-services-configmap and --udp-services-configmap to point to an existing ConfigMap where the key refers to the external port to be used and the value refers to the format of the service to be exposed. The format of the value is <namespace/service_name>:<service_port>.

For example, the configurations of the ConfigMap named as tcp-services is as follows:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tcp-services
  namespace: nginx-ingress
data:
  # update 
  9769: "default/nebula-graphd-svc:9669"

Steps are as follows.

Create a file named nginx-ingress-daemonset-hostnetwork.yaml.

Click on nginx-ingress-daemonset-hostnetwork.yaml to view the complete content of the example YAML file.

Note

The resource objects in the YAML file above use the namespace nginx-ingress. You can run kubectl create namespace nginx-ingress to create this namespace, or you can customize the namespace.
Label a node where the DaemonSet named nginx-ingress-controller in the above YAML file (The node used in this example is named worker2 with an IP of 192.168.8.160) runs.
```
kubectl label node worker2 nginx-ingress=true
```

Run the following command to enable Nginx Ingress in the cluster you created.

kubectl create -f nginx-ingress-daemonset-hostnetwork.yaml

Output:

configmap/nginx-ingress-controller created
configmap/tcp-services created
serviceaccount/nginx-ingress created
serviceaccount/nginx-ingress-backend created
clusterrole.rbac.authorization.k8s.io/nginx-ingress created
clusterrolebinding.rbac.authorization.k8s.io/nginx-ingress created
role.rbac.authorization.k8s.io/nginx-ingress created
rolebinding.rbac.authorization.k8s.io/nginx-ingress created
service/nginx-ingress-controller-metrics created
service/nginx-ingress-default-backend created
service/nginx-ingress-proxy-tcp created
daemonset.apps/nginx-ingress-controller created

Since the network type that is configured in Nginx Ingress is hostNetwork, after successfully deploying Nginx Ingress, with the IP (192.168.8.160) of the node where Nginx Ingress is deployed and with the external port (9769) you define, you can access NebulaGraph.

Use the IP address and the port configured in the preceding steps. You can connect to NebulaGraph with NebulaGraph Console.
```
kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- <nebula_console_name> -addr <host_ip> -port <external_port> -u <username> -p <password>
```
Output:
```
kubectl run -ti --image vesoft/nebula-console:v3.2.0 --restart=Never -- nebula-console -addr 192.168.8.160 -port 9769 -u root -p vesoft
```
- --image: The image for the tool NebulaGraph Console used to connect to NebulaGraph databases.
- <nebula-console> The custom Pod name. The above example uses nebula-console.
- -addr: The IP of the node where Nginx Ingress is deployed. The above example uses 192.168.8.160.
- -port: The port used for external network access. The above example uses 9769.
- -u: The username of your NebulaGraph account. Before enabling authentication, you can use any existing username. The default username is root.
- -p: The password of your NebulaGraph account. Before enabling authentication, you can use any characters as the password.
A successful connection to the database is indicated if the following is returned:
```
If you don't see a command prompt, try pressing enter.
(root@nebula) [(none)]>
```

Last update: February 1, 2023