neo4j-operator

Neo4J Operator

Project status: alpha

The project is in alpha phase. While no breaking API changes are currently planned, we reserve the right to address bugs and change the API before the project is declared stable.

Table of Contents

• Overview
• Usage
  • Install the Operator
  • Deploy Sample Neo4J Cluster
  • Uninstall the Operator
• Neo4J Cluster Configuration
  • Basic
  • SSL Certificates
  • Scheduled Backups
• Development
  • Run the Operator Locally
  • Build the Operator Image
  • Direct Access to Neo4J Cluster

Overview

The operator itself has been built with the Operator framework and runs official Neo4J Docker image.

Usage

Install the Operator

Register the Neo4jCluster custom resource definition.

$ kubectl apply -f deploy/crds/database_v1alpha1_neo4jcluster_crd.yaml

You can choose to enable Neo4J operator for all namespaces or just for the a specific one. Examples target default namespace.

Create the operator role, role binding and service account.

$ kubectl apply -f deploy/role.yaml
$ kubectl apply -f deploy/role_binding.yaml
$ kubectl apply -f deploy/service_account.yaml

Operator requires elevated privileges in order to watch for the custom resource updates. On Google Kubernetes Engine, the following command must be run before continuing with installation process. Replace user ID with your own credentials.

$ cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: your-google-id@gmail.com-cluster-admin-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: User
  name: "your-google-id@gmail.com"
EOF

Finally, deploy the operator.

$ sed -i 's|REPLACE_IMAGE|lantonia/neo4j-operator:latest|g' deploy/operator.yaml
$ kubectl apply -f deploy/operator.yaml

Deploy Sample Neo4J Cluster

Create file neo4j.yaml with the following content to provision eight node cluster.

apiVersion: database.neo4j.org/v1alpha1
kind: Neo4jCluster
metadata:
  name: example1
spec:
  image-version: 3.5.4-enterprise
  admin-password: TmVvNEojUGFzc3cwcmQxMjMh
  core-replicas: 3
  read-replica-replicas: 5
  resources:
    requests:
      cpu: 1000m
      memory: 2048Mi
    limits:
      cpu: 1000m
      memory: 2048Mi
  persistent-storage:
    size: 1Gi

Deploy Neo4J cluster.

$ kubectl apply -f neo4j.yaml

Query cluster status to review ready servers and the current leader.

$ kubectl get neo4jclusters.database.neo4j.org
NAME       CORE SERVERS   READ REPLICAS   LEADER                                      BOLT URL
example1   3/3            5/5             neo4j-core-example1-1.neo4j-core-example1   bolt+routing://neo4j-core-example1:7687

Uninstall the Operator

Neo4J pods, volumes and services managed by the operator will not be deleted even if the operator is uninstalled.

$ kubectl delete -f deploy/operator.yaml

Neo4J Cluster Configuration

Basic

Below table presents basic configuration parameters.

Complete example of eight node cluster definition.

apiVersion: database.neo4j.org/v1alpha1
kind: Neo4jCluster
metadata:
  name: example1
spec:
  image-version: 3.5.4-enterprise
  admin-password: TmVvNEojUGFzc3cwcmQxMjMh
  core-replicas: 3
  read-replica-replicas: 5
  resources:
    requests:
      cpu: 1000m
      memory: 2048Mi
    limits:
      cpu: 1000m
      memory: 2048Mi
  persistent-storage:
    size: 1Gi

SSL Certificates

Users may choose to leverage custom SSL certificates for encrypted communication. Paste content of private key and public certificate to Neo4J cluster YAML file.

ssl:
  key: |
    -----BEGIN PRIVATE KEY-----
    MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDI05vZ7So8Ly6D
    ... (truncated) ...
    U2RRbKeEcDhcABzPF0bJFEPR
    -----END PRIVATE KEY-----
  certificate: |
    -----BEGIN CERTIFICATE-----
    MIIDkzCCAnugAwIBAgIJAJMfoyRqXIZMMA0GCSqGSIb3DQEBBQUAMGAxCzAJBgNV
    ... (truncated) ...
    DQnQ+OGUMw==
    -----END CERTIFICATE-----

Scheduled Backups

Operator can manage automatic backups triggered as Kubernetes cron jobs. Users have to define schedule, storage size and resource limits for pod executing neo4j-admin backup command.

backup:
  schedule: "*/5 * * * *"
  size: 2Gi
    resources:
      requests:
        cpu: 200m
        memory: 1024Mi
      limits:
        cpu: 200m
        memory: 1024Mi

Development

Run the Operator Locally

You can run the operator locally to help with development, testing, and debugging tasks.

The following command will run the operator locally with the default Kubernetes config file present at $HOME/.kube/config. Use the --kubeconfig flag to provide a different path.

$ export OPERATOR_NAME=neo4j-operator
$ operator-sdk up local --namespace=default

In another terminal window, create custom Kubernetes resource definition and provision example Neo4J cluster.

$ kubectl apply -f deploy/crds/database_v1alpha1_neo4jcluster_crd.yaml
$ kubectl apply -f deploy/crds/database_v1alpha1_neo4jcluster_cr.yaml

Build the Operator Image

Use the following commands to build the image of Neo4J operator and push to desired Docker repository.

$ operator-sdk build lantonia/neo4j-operator:latest
$ # For old Docker versions:
$ # docker build -f build/Dockerfile -t lantonia/neo4j-operator:latest .
$ # sed -i 's|REPLACE_IMAGE|lantonia/neo4j-operator:latest|g' deploy/operator.yaml
$ docker push lantonia/neo4j-operator:latest

Direct Access to Neo4J Cluster

For debugging and development you might want to access the Neo4J cluster directly. For example, if you created the cluster with name example1 in the default namespace, you can forward the Neo4J port to any of the pods (e.g. neo4j-core-example1-0) as follows:

$ kubectl port-forward -n default neo4j-core-example1-0 7473:7473