From 807ca9c1e3e0d49481be4d263723e71c92e21175 Mon Sep 17 00:00:00 2001
From: Haiyan Meng <haiyanmeng@google.com>
Date: Thu, 6 Feb 2020 15:56:23 -0800
Subject: [PATCH] Add notes on backup and restore

---
 api/internal/crawl/config/elastic/esbackup.yaml    | 7 ++++++-
 api/internal/crawl/config/elastic/escluster.yaml   | 1 +
 api/internal/crawl/config/elastic/esrestore.yaml   | 4 +++-
 api/internal/crawl/config/elastic/essnaptshot.yaml | 7 +++++++
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/api/internal/crawl/config/elastic/esbackup.yaml b/api/internal/crawl/config/elastic/esbackup.yaml
index a3b5e6da8..fbdbee461 100644
--- a/api/internal/crawl/config/elastic/esbackup.yaml
+++ b/api/internal/crawl/config/elastic/esbackup.yaml
@@ -1,7 +1,8 @@
+# ESBackup depends on ESCluster, and is depended by ESSnapshot.
 # Creating `esbackup/kustomize-backbup` will create the `kustomize-backup` snapshot repository.
 # Deleting `esbackup/kustomize-backbup` will delete the `kustomize-backup` snapshot repository.
 # Deleting `esbackup/kustomize-backbup` will NOT delete the snapshots in the `kustomize-backup` snapshot repository, instead makes all the snapshots in the repository inaccessible.
-# Deleting `esbackup/kustomize-backbup` will NOT delete essnapshot and esrestore objects.
+# Deleting `esbackup/kustomize-backbup` will NOT delete the essnapshot objects depending on it, but will cause those essnapshot objects to be reconciled, which update the status of the essnapshot objects to reflect the fact that the esbackup object is missing.
 # If you delete the `kustomize-backup` snapshot repository directly without deleting `esbackup/kustomize-backbup`, the ESBackup object will not recreate the snapshot repository.
 apiVersion: elasticsearch.cloud.google.com/v1alpha1
 kind: ESBackup
@@ -10,7 +11,11 @@ metadata:
 spec:
   storage:
     gcs:
+      # the bucket must exist for the snapshot respository to be created successfully.
       bucket: kustomize-backup
+      # the path does not need to exist.
+      # If the path does not exist, the controller will create the folder in the GCS bucket.
+      # If the path already exists and includes snapshots, these snapshots can be used.
       path: kustomize
       secret:
         name: kustomizesa
diff --git a/api/internal/crawl/config/elastic/escluster.yaml b/api/internal/crawl/config/elastic/escluster.yaml
index 4515cee47..d0fca4bb0 100644
--- a/api/internal/crawl/config/elastic/escluster.yaml
+++ b/api/internal/crawl/config/elastic/escluster.yaml
@@ -1,3 +1,4 @@
+# ESCluster is depended by ESBackup and ESRestore.
 apiVersion: elasticsearch.cloud.google.com/v1alpha1
 kind: ESCluster
 metadata:
diff --git a/api/internal/crawl/config/elastic/esrestore.yaml b/api/internal/crawl/config/elastic/esrestore.yaml
index 4490d8248..fbe5529c3 100644
--- a/api/internal/crawl/config/elastic/esrestore.yaml
+++ b/api/internal/crawl/config/elastic/esrestore.yaml
@@ -1,7 +1,9 @@
+# ESRestore depends on both ESCluster and ESSnapshot.
 # Creating `esrestore/kustomize-restore` will restore the `kuostmize` index in the `kustomize-snapshot` snapshot to a new index named `kusotmize-restore`.
 # Deleting `esrestore/kustomize-restore` will not delete the restored index.
 # Deleting `esrestore/kustomize-restore` should happen before deleting `essnapshot/kustomize-snapshot`.
-# If the `kusotmize-restore` index is deleted manually, the ESRestore object will restore the `kustomize` index to it again.
+# After the restore is complete, if the `kusotmize-restore` index is deleted manually, the ESRestore object will NOT restore the `kustomize` index to it again.
+# The correct way of using ESRestore is: create a ESRestore object to restore the index; delete the ESRestore object after the restore is complete.
 apiVersion: elasticsearch.cloud.google.com/v1alpha1
 kind: ESRestore
 metadata:
diff --git a/api/internal/crawl/config/elastic/essnaptshot.yaml b/api/internal/crawl/config/elastic/essnaptshot.yaml
index 46b7c95eb..adc4dec24 100644
--- a/api/internal/crawl/config/elastic/essnaptshot.yaml
+++ b/api/internal/crawl/config/elastic/essnaptshot.yaml
@@ -1,7 +1,14 @@
+# ESSnapshot depends on ESBackup, and is depended by ESRestore.
 # Creating `essnapshot/kustomize-snapshot` will create a snapshot named `kustomize-snapshot` in the `kustomize-backup` snapshot repository.
+# After being created, the `kustomize-snapshot` snapshot will not be automatically updated when the `kuostomize` index is updated.
+# If you delete `essnapshot/kustomize-snapshot` and recreate it, the new snapshot will capture the current status of the `kustomize` index.
 # Deleting `essnapshot/kustomize-snapshot` will delete the snapshot.
 # Deleting `essnapshot/kustomize-snapshot` should happen before deleting `esbackup/kustomize-backup`.
 # If the `kustomize-snapshot` snapshot is deleted directly without deleting `essnapshot/kustomize-snapshot`, the ESSnapshot object will recreate the snapshot.
+# The correct way of using ESSnapshot is: create an ESSnapshot object to create a snapshot, keep the ESSnapshot object until the snapshot is no longer needed.
+# To update the snapshot to capture the latest version of the index, you can either:
+#   1) delete the snapshot, and wait for the ESSnapshot object to recreate the snapshot;
+#   2) delete the ESSnapshot object, and recreate the ESSnapshot object.
 apiVersion: elasticsearch.cloud.google.com/v1alpha1
 kind: ESSnapshot
 metadata: