From 980fab01b3bef986325d77b7830586971f399c3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Sch=C3=A4fer?= Date: Sat, 20 Apr 2019 13:55:32 +0200 Subject: [PATCH 1/3] Add documentation for neo4j backups in kubernetes --- SUMMARY.md | 5 +-- deployment/README.md | 2 +- deployment/backup.md | 74 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 3 deletions(-) create mode 100644 deployment/backup.md diff --git a/SUMMARY.md b/SUMMARY.md index c993fe120..e1cf09126 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,7 +5,6 @@ * [Installation](installation.md) * [Backend](backend/README.md) * [GraphQL](backend/graphql.md) - * [Legacy Migration](backend/db-migration-worker/README.md) * [Webapp](webapp/README.md) * [COMPONENTS](webapp/components.md) * [PLUGINS](webapp/plugins.md) @@ -21,7 +20,9 @@ * [Frontend tests](webapp/testing.md) * [Backend tests](backend/testing.md) * [Contributing](CONTRIBUTING.md) -* [Deployment](deployment/README.md) +* [Kubernetes Deployment](deployment/README.md) + * [Neo4J DB Backup](deployment/backup.md) +* [Maintenance](maintenance/README.md) * [Feature Specification](cypress/features.md) * [Code of conduct](CODE_OF_CONDUCT.md) * [License](LICENSE.md) diff --git a/deployment/README.md b/deployment/README.md index 982a886ac..84912d2a5 100644 --- a/deployment/README.md +++ b/deployment/README.md @@ -181,7 +181,7 @@ This setup is completely optional and only required if you have data on a server Create a configmap with the specific connection data of your legacy server: ```bash -$ kubectl create configmap db-migration-worker \ +$ kubectl create configmap maintenance-worker \ --namespace=human-connection \ --from-literal=SSH_USERNAME=someuser \ --from-literal=SSH_HOST=yourhost \ diff --git a/deployment/backup.md b/deployment/backup.md new file mode 100644 index 000000000..556d257db --- /dev/null +++ b/deployment/backup.md @@ -0,0 +1,74 @@ +# Backup (offline) + +This tutorial explains how to carry out an offline backup of your Neo4J +database in a kubernetes cluster. + +An offline backup requires the Neo4J database to be stopped. Read +[the docs](https://neo4j.com/docs/operations-manual/current/tools/dump-load/). +Neo4J also offers online backups but this is available in enterprise edition +only. + +The tricky part is to stop the Neo4J database *without* stopping the container. +Neo4J's docker container image starts `neo4j` by default, so we have to override +this command with sth. that keeps the container spinning but does not terminate +it. + +## Stop and Restart Neo4J Database in Kubernetes + +[This tutorial](http://bigdatums.net/2017/11/07/how-to-keep-docker-containers-running/) +explains how to keep a docker container running. For kubernetes, the way how to +override the docker image `CMD` is explained [here](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#define-a-command-and-arguments-when-you-create-a-pod). + +So, all we have to do is to edit the kubernetes deployment of our Neo4J database +and set a custom `command` every time we have to carry out tasks like backup, +restore, seed etc. + +{% hint style="info" %} TODO: implement maintenance mode {% endhint %} +First bring the application into maintenance mode to ensure there are no +database connections left and nobody can access the application. + +Run the following: + +```sh +kubectl --namespace=human-connection edit deployment nitro-neo4j +``` + +Add the following to `spec.template.spec.containers`: +``` +["tail", "-f", "/dev/null"] +``` +and write the file which will update the deployment. + +Then perform your tasks! + +When you're done, edit the deployment again and remove the `command`. Write the +file and trigger an update of the deployment. + +## Create a Backup in Kubernetes + +First stop your Neo4J database, see above. Then: +```sh +kubectl --namespace=human-connection get pods +# copy the ID of the pod running Neo4J +kubectl --namespace=human-connection exec -it bash +# once you're in the pod +neo4j-admin dump --to=/root/neo4j-backup +exit +# download the file + kubectl cp human-connection/:/root/neo4j-backup ./neo4j-backup +``` +Restart your Neo4J database. + +## Restore a Backup in Kubernetes + +First stop your Neo4J database. Then: +```sh +kubectl --namespace=human-connection get pods +# copy the ID of the pod running Neo4J +kubectl cp ./neo4j-backup human-connection/:/root/ +kubectl --namespace=human-connection exec -it bash +# once you're in the pod +neo4j-admin load --from=/root/neo4j-backup --force +exit +``` +Restart your Neo4J database. From 718b2da6e755e5921059f8449955fc94e4c026bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Sch=C3=A4fer?= Date: Tue, 23 Apr 2019 17:21:45 +0200 Subject: [PATCH 2/3] Improve the docs with @datenbrei --- deployment/backup.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/deployment/backup.md b/deployment/backup.md index 556d257db..482b77175 100644 --- a/deployment/backup.md +++ b/deployment/backup.md @@ -39,7 +39,12 @@ Add the following to `spec.template.spec.containers`: ``` and write the file which will update the deployment. -Then perform your tasks! +The command `tail -f /dev/null` is the equivalent of *sleep forever*. It is a +hack to keep the container busy and to prevent its shutdown. It will also +override the default `neo4j` command and the kubernetes pod will not start the +database. + +Now perform your tasks! When you're done, edit the deployment again and remove the `command`. Write the file and trigger an update of the deployment. @@ -49,26 +54,30 @@ file and trigger an update of the deployment. First stop your Neo4J database, see above. Then: ```sh kubectl --namespace=human-connection get pods -# copy the ID of the pod running Neo4J +# Copy the ID of the pod running Neo4J. kubectl --namespace=human-connection exec -it bash -# once you're in the pod +# Once you're in the pod, dump the db to a file e.g. `/root/neo4j-backup`. neo4j-admin dump --to=/root/neo4j-backup exit -# download the file +# Download the file from the pod to your computer. kubectl cp human-connection/:/root/neo4j-backup ./neo4j-backup ``` -Restart your Neo4J database. +Revert your changes to deployment `nitro-neo4j` which will restart the database. ## Restore a Backup in Kubernetes First stop your Neo4J database. Then: ```sh kubectl --namespace=human-connection get pods -# copy the ID of the pod running Neo4J +# Copy the ID of the pod running Neo4J. +# Then upload your local backup to the pod. Note that once the pod gets deleted +# e.g. if you change the deployment, the backup file is gone with it. kubectl cp ./neo4j-backup human-connection/:/root/ kubectl --namespace=human-connection exec -it bash -# once you're in the pod +# Once you're in the pod restore the backup and overwrite the default database +# called `graph.db` with `--force`. +# This will delete all existing data in database `graph.db`! neo4j-admin load --from=/root/neo4j-backup --force exit ``` -Restart your Neo4J database. +Revert your changes to deployment `nitro-neo4j` which will restart the database. From 500221314a4b8f7f355b6f2f4a962613911e5784 Mon Sep 17 00:00:00 2001 From: mattwr18 Date: Tue, 23 Apr 2019 12:29:34 -0300 Subject: [PATCH 3/3] Update backup.md --- deployment/backup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deployment/backup.md b/deployment/backup.md index 482b77175..5d6d61866 100644 --- a/deployment/backup.md +++ b/deployment/backup.md @@ -16,10 +16,10 @@ it. ## Stop and Restart Neo4J Database in Kubernetes [This tutorial](http://bigdatums.net/2017/11/07/how-to-keep-docker-containers-running/) -explains how to keep a docker container running. For kubernetes, the way how to +explains how to keep a docker container running. For kubernetes, the way to override the docker image `CMD` is explained [here](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#define-a-command-and-arguments-when-you-create-a-pod). -So, all we have to do is to edit the kubernetes deployment of our Neo4J database +So, all we have to do is edit the kubernetes deployment of our Neo4J database and set a custom `command` every time we have to carry out tasks like backup, restore, seed etc.