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.
-
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.
- NebulaGraph uses port
-
Create a ClusterIP Service.
kubectl create -f graphd-clusterip-service.yaml
-
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 ...
-
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 theClusterIP
Service, used to connect to Graphd services.-port
: The port to connect to Graphd services, the default port of which is9669
.-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 ofCLUSTER_DOMAIN
iscluster.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 is9669
.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.
-
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.
- NebulaGraph uses port
-
Create a ClusterIP Service.
kubectl create -f graphd-clusterip-service.yaml
-
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 ...
-
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 theClusterIP
Service, used to connect to Graphd services.-port
: The port to connect to Graphd services, the default port of which is9669
.-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 ofCLUSTER_DOMAIN
iscluster.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 is9669
.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:
-
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.
- NebulaGraph uses port
-
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 -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
. -
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 usesnebula-console
.-addr
: The IP of any node in a NebulaGraph cluster. The above example uses192.168.8.24
.-port
: The mapped port of NebulaGraph databases on all cluster nodes. The above example uses32236
.-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.
-
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 runkubectl 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 namedworker2
with an IP of192.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.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 usesnebula-console
.-addr
: The IP of the node where Nginx Ingress is deployed. The above example uses192.168.8.160
.-port
: The port used for external network access. The above example uses9769
.-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.