Skip to content

Connect to a NebulaGraph cluster

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

A NebulaGraph cluster is created on Kubernetes. For more information, see Create a NebulaGraph cluster.

Connect to NebulaGraph databases from within a NebulaGraph cluster

You can create a ClusterIP type Service to provide an access point to the NebulaGraph database for other Pods within the cluster. By using the Service's IP and the Graph service's port number (9669), you can connect to the NebulaGraph database. For more information, see ClusterIP.

  1. Create a file named graphd-clusterip-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
  namespace: default
spec:
  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: ClusterIP  # Set the type to ClusterIP.
    • NebulaGraph uses port 9669 by default. 19669 is the HTTP port of the Graph service in a NebulaGraph cluster.
    • targetPort is the port mapped to the database Pods, which can be customized.

  2. Create a ClusterIP Service.

    kubectl create -f graphd-clusterip-service.yaml

  3. Check the IP of the Service:

    $ kubectl get service -l app.kubernetes.io/cluster=<nebula>  # <nebula> is the name of your NebulaGraph cluster.
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
...

  4. 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.8.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.8.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:

    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>. The default value of CLUSTER_DOMAIN is cluster.local.

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

    service_port is the port to connect to Graphd services, the default port of which is 9669.

    Note

    If the spec.console field is set in the cluster configuration file, you can also connect to NebulaGraph databases with the following command:

    # Enter the nebula-console Pod.
kubectl exec -it nebula-console -- /bin/sh

# Connect to NebulaGraph databases.
nebula-console -addr nebula-graphd-svc.default.svc.cluster.local -port 9669 -u <username> -p <password>

    For information about the nebula-console container, see nebula-console.

Connect to NebulaGraph databases from within a NebulaGraph cluster

You can also create a ClusterIP type Service to provide an access point to the NebulaGraph database for other Pods within the cluster. By using the Service's IP and the Graph service's port number (9669), you can connect to the NebulaGraph database. For more information, see ClusterIP.

  1. Create a file named graphd-clusterip-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
  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: ClusterIP  # Set the type to ClusterIP.
    • NebulaGraph uses port 9669 by default. 19669 is the HTTP port of the Graph service in a NebulaGraph cluster.
    • targetPort is the port mapped to the database Pods, which can be customized.

  2. Create a ClusterIP Service.

    kubectl create -f graphd-clusterip-service.yaml

  3. Check the IP of the Service:

    $ kubectl get service -l app.kubernetes.io/cluster=<nebula>  # <nebula> is the name of your NebulaGraph cluster.
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
...

  4. 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.8.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.8.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:

    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>. The default value of CLUSTER_DOMAIN is cluster.local.

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

    service_port is the port to connect to Graphd services, the default port of which is 9669.

    Note

    If the spec.console field is set in the cluster configuration file, you can also connect to NebulaGraph databases with the following command:

    # Enter the nebula-console Pod.
kubectl exec -it nebula-console -- /bin/sh

# Connect to NebulaGraph databases.
nebula-console -addr nebula-graphd-svc.default.svc.cluster.local -port 9669 -u <username> -p <password>

    For information about the nebula-console container, see nebula-console.

Connect to NebulaGraph databases from outside a NebulaGraph cluster via NodePort

You can create a NodePort type Service to access internal cluster services from outside the cluster using any node IP and the exposed node port. You can also utilize load balancing services provided by cloud vendors (such as Azure, AWS, etc.) by setting the Service type to LoadBalancer. This allows external access to internal cluster services through the public IP and port of the load balancer provided by the cloud vendor.

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.

After creating a NebulaGraph cluster based on the example template, where spec.graphd.service.type=NodePort, the NebulaGraph Operator will automatically create a NodePort type Service named <cluster-name>-graphd-svc in the same namespace. You can directly connect to the NebulaGraph database through any node IP and the exposed node port (see step 4 below). You can also create a custom Service according to your needs.

Steps:

  1. 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   # Set the type to NodePort.
    • NebulaGraph uses port 9669 by default. 19669 is the HTTP 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.

  2. Run the following command to create a NodePort Service.

    kubectl create -f graphd-nodeport-service.yaml

  3. Check the port mapped on all of your cluster nodes.

    kubectl get services -l app.kubernetes.io/cluster=<nebula> # <nebula> is the name of your NebulaGraph cluster.

    Output:

    NAME                           TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)                                          AGE
nebula-graphd-svc-nodeport     NodePort    10.107.153.129 <none>        9669:32236/TCP,19669:31674/TCP,19670:31057/TCP   24h
...

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

  4. Connect to NebulaGraph databases with your node IP and the node port above.

    kubectl run -ti --image vesoft/nebula-console:v3.8.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.8.0 --restart=Never -- nebula-console -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-console.
    • -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.

    Note

    If the spec.console field is set in the cluster configuration file, you can also connect to NebulaGraph databases with the following command:

    # Enter the nebula-console Pod.
kubectl exec -it nebula-console -- /bin/sh

# Connect to NebulaGraph databases.
nebula-console -addr <node_ip> -port <node_port> -u <username> -p <password>

    For information about the nebula-console container, see nebula-console.

Connect to NebulaGraph databases from outside a NebulaGraph cluster via Ingress

When dealing with multiple pods in a cluster, managing services for each pod separately is not a good practice. Ingress is a Kubernetes resource that provides a unified entry point for accessing multiple services. Ingress can be used to expose multiple services under a single IP address.

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 host network and DaemonSet pattern.

Due to the use of HostNetwork, Nginx Ingress pods may be scheduled on the same node (port conflicts will occur when multiple pods try to listen on the same port on the same node). To avoid this situation, Nginx Ingress is deployed on these nodes in DaemonSet mode (ensuring that a pod replica runs on each node in the cluster). You first need to select some nodes and label them for the specific deployment of Nginx Ingress.

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.

  1. 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.

  2. 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

  3. 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.

  4. 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.8.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.8.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)]>

    Note

    If the spec.console field is set in the cluster configuration file, you can also connect to NebulaGraph databases with the following command:

    # Enter the nebula-console Pod.
kubectl exec -it nebula-console -- /bin/sh

# Connect to NebulaGraph databases.
nebula-console -addr <ingress_host_ip> -port <external_port> -u <username> -p <password>

    For information about the nebula-console container, see nebula-console.

Last update: July 18, 2023