Merge pull request #142 from kanisterio/sync

Doc update, pic-gal fixed, profile version update in requirements.yaml

docs/index.rst

@@ -11,103 +11,13 @@ tasks in Blueprints which can be easily shared and extended. The framework takes
 care of the tedious details around execution on Kubernetes and presents a
 homogeneous operational experience across applications at scale.
 
-The design of Kanister was driven by the following main goals:
-
-1. Application-Centric: Given the increasingly complex and distributed nature
-   of cloud-native data services, there is a growing need for data management
-   tasks to be at the *application* level. Experts who possess domain knowledge
-   of a specific application's needs should be able to capture these needs when
-   performing data operations on that application.
-
-2. API Driven: Data management tasks for each specific application may vary
-   widely, and these tasks should be encapsulated by a well-defined API so as to
-   provide a uniform data management experience. Each application expert can
-   provide an application-specific pluggable implementation that satisfies this
-   API, thus enabling a homogeneous data management experience of diverse and
-   evolving data services.
-
-3. Extensible: Any data management solution capable of managing a diverse set of
-   applications must be flexible enough to capture the needs of custom data services
-   running in a variety of environments. Such flexibility can only be provided if
-   the solution itself can easily be extended.
-
-
-Getting Started
-===============
-
-To get up and running using Kanister, we encourage you to start with
-the :ref:`architecture` section first. :ref:`install` will then allow
-you to work through the :ref:`tutorial`.
-
-Alternatively, you can start by installing :ref:`Kanister-enabled Helm
-applications<helm>` and then using Kanister to manipulate them. See
-the Quick Start section below and the documentation on :ref:`helm` for
-more information.
-
-Kanister is an open-source project and the source, this documentation,
-and more examples can be found on `GitHub
-<https://github.com/kanisterio/kanister>`_.
-
-
-
-Quick Start
-===========
-
-The Kanister operator controller can be installed on a `Kubernetes
-<https://kubernetes.io>`_ cluster using the `Helm <https://helm.sh>`_
-package manager.
-
-The following commands will install Kanister, Kanister-enabled MySQL
-and backup to an AWS S3 bucket.
-
-.. code-block:: bash
-
-  # Add Kanister Charts
-  helm repo add kanister http://charts.kanister.io
-
-  # Install the Kanister Controller
-  helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=0.14.0
-
-  # Install MySQL and configure its Kanister Blueprint.
-  # Also create a Profile CR that can be used in ActionSets
-  helm install kanister/kanister-mysql                        \
-      --name mysql-release --namespace mysql-ns               \
-      --set kanister.create_profile="true"                    \
-      --set kanister.s3_bucket="mysql-backup-bucket"          \
-      --set kanister.s3_api_key="${AWS_ACCESS_KEY_ID}"        \
-      --set kanister.s3_api_secret="${AWS_SECRET_ACCESS_KEY}" \
-      --set kanister.controller_namespace=kanister
-
-  # Perform a backup by creating an ActionSet
-  cat << EOF | kubectl create -f -
-  apiVersion: cr.kanister.io/v1alpha1
-  kind: ActionSet
-  metadata:
-    generateName: mysql-backup-
-    namespace: kanister
-  spec:
-    actions:
-    - name: backup
-      blueprint: mysql-release-kanister-mysql-blueprint
-      object:
-        kind: Deployment
-        name: mysql-release-kanister-mysql
-        namespace: mysql-ns
-      profile:
-        apiVersion: v1alpha1
-        kind: profile
-        name: mysql-release-kanister-mysql-backup-profile
-        namespace: mysql-ns
-  EOF
-
-
 .. toctree::
    :hidden:
 
    self
+   overview
+   usage
    architecture
-   install
-   tutorial
    tooling
    helm
    functions

docs/overview.rst

@@ -0,0 +1,99 @@
+.. _overview:
+
+Kanister Overview
+*****************
+
+.. contents:: Kanister Overview
+  :local:
+
+Design Goals
+============
+
+The design of Kanister was driven by the following main goals:
+
+1. **Application-Centric:** Given the increasingly complex and distributed nature
+   of cloud-native data services, there is a growing need for data management
+   tasks to be at the *application* level. Experts who possess domain knowledge
+   of a specific application's needs should be able to capture these needs when
+   performing data operations on that application.
+
+2. **API Driven:** Data management tasks for each specific application may vary
+   widely, and these tasks should be encapsulated by a well-defined API so as to
+   provide a uniform data management experience. Each application expert can
+   provide an application-specific pluggable implementation that satisfies this
+   API, thus enabling a homogeneous data management experience of diverse and
+   evolving data services.
+
+3. **Extensible:** Any data management solution capable of managing a diverse set of
+   applications must be flexible enough to capture the needs of custom data services
+   running in a variety of environments. Such flexibility can only be provided if
+   the solution itself can easily be extended.
+
+
+Getting Started
+===============
+
+To get up and running using Kanister, we encourage you to start with
+the :ref:`architecture` section first. :ref:`install` will then allow
+you to work through the :ref:`tutorial`.
+
+Alternatively, you can start by installing :ref:`Kanister-enabled Helm
+applications<helm>` and then using Kanister to manipulate them. See
+the Quick Start section below and the documentation on :ref:`helm` for
+more information.
+
+Kanister is an open-source project and the source, this documentation,
+and more examples can be found on `GitHub
+<https://github.com/kanisterio/kanister>`_.
+
+
+
+Quick Start
+===========
+
+The Kanister operator controller can be installed on a `Kubernetes
+<https://kubernetes.io>`_ cluster using the `Helm <https://helm.sh>`_
+package manager.
+
+The following commands will install Kanister, Kanister-enabled MySQL
+and backup to an AWS S3 bucket.
+
+.. code-block:: bash
+
+  # Add Kanister Charts
+  helm repo add kanister http://charts.kanister.io
+
+  # Install the Kanister Controller
+  helm install --name myrelease --namespace kanister kanister/kanister-operator --set image.tag=0.14.0
+
+  # Install MySQL and configure its Kanister Blueprint.
+  # Also create a Profile CR that can be used in ActionSets
+  helm install kanister/kanister-mysql                        \
+      --name mysql-release --namespace mysql-ns               \
+      --set kanister.create_profile="true"                    \
+      --set kanister.s3_bucket="mysql-backup-bucket"          \
+      --set kanister.s3_api_key="${AWS_ACCESS_KEY_ID}"        \
+      --set kanister.s3_api_secret="${AWS_SECRET_ACCESS_KEY}" \
+      --set kanister.controller_namespace=kanister
+
+  # Perform a backup by creating an ActionSet
+  cat << EOF | kubectl create -f -
+  apiVersion: cr.kanister.io/v1alpha1
+  kind: ActionSet
+  metadata:
+    generateName: mysql-backup-
+    namespace: kanister
+  spec:
+    actions:
+    - name: backup
+      blueprint: mysql-release-kanister-mysql-blueprint
+      object:
+        kind: Deployment
+        name: mysql-release-kanister-mysql
+        namespace: mysql-ns
+      profile:
+        apiVersion: v1alpha1
+        kind: profile
+        name: mysql-release-kanister-mysql-backup-profile
+        namespace: mysql-ns
+  EOF

docs/usage.rst

@@ -0,0 +1,13 @@
+.. _usage:
+
+Usage
+*****
+
+The following section will guide you to properly setup Kanister
+in a Kubernetes cluster and run through a simple tutorial.
+
+.. toctree::
+   :maxdepth: 2
+
+   install
+   tutorial

examples/helm/kanister/kanister-elasticsearch/requirements.yaml

@@ -1,5 +1,5 @@
 dependencies:
   - name: profile
-    version: "0.1.0"
+    version: "0.14.0"
     condition: profile.create
     repository: "https://charts.kanister.io"

examples/helm/kanister/kanister-mongodb-replicaset/requirements.yaml

@@ -1,5 +1,5 @@
 dependencies:
   - name: profile
-    version: "0.1.0"
+    version: "0.14.0"
     condition: profile.create
     repository: "https://charts.kanister.io"

examples/helm/kanister/kanister-mysql/requirements.yaml

@@ -1,5 +1,5 @@
 dependencies:
   - name: profile
-    version: "0.1.0"
+    version: "0.14.0"
     condition: profile.create
     repository: "https://charts.kanister.io"

examples/helm/kanister/kanister-postgresql/requirements.yaml

@@ -1,5 +1,5 @@
 dependencies:
   - name: profile
-    version: "0.1.0"
+    version: "0.14.0"
     condition: profile.create
     repository: "https://charts.kanister.io"

examples/picture-gallery-pvc-snapshot/README.md

@@ -1,3 +1,92 @@
 # Walkthrough of Picture Gallery
 
-The blueprint for this application is in progress. Once it is ready, we will be able to take PVC screenshots, restore PVCs and delete the backup data.
+This is an example of using Kanister to protect the volumes of a simple application called Picture Gallery. It demonstrates the use of kanister functions to take individual snapshots of each PVC associated with an appication and to restore the PVCs when needed.
+
+Note: This example demo will only work on AWS cluster for now.
+
+### 1. Deploy the Application
+
+The following command deploys the example Picture Gallery application in `default` namespace:
+
+```bash
+# Create a picture gallery deployment
+$ kubectl apply -f ./examples/picture-gallery-pvc-snapshot/picture-gallery-deployment.yaml
+deployment "picture-gallery" created
+```
+
+### 2. Protect the PVCs
+
+Next create a Blueprint which describes how backup and restore actions can be executed on the PVCs of this application. The Blueprint for this application can be found at `blueprint.yaml`. In order for this example to work, you should install kanister profile using the command specified below. Do not forget to replace the default s3 credentials (bucket and region) with your credentials before you run this command. The following commands will install kanister Profile and create a Blueprint in controller's namespace:
+
+```bash
+# Configure access to an S3 Bucket
+$ helm install kanister/profile                 \
+    --name profile --namespace kanister       \
+    --set defaultProfile=true                 \
+    --set s3.bucket="my-kanister-bucket"      \
+    --set s3.region="us-west-2"              \
+    --set s3.accessKey="${AWS_ACCESS_KEY_ID}" \
+    --set s3.secretKey="${AWS_SECRET_ACCESS_KEY}"
+
+# Create the kanister blueprint that has instructions on how to backup the PVCs
+$ kubectl apply -f examples/picture-gallery-pvc-snapshot/blueprint.yaml
+blueprint "picture-gallery" created
+
+```
+
+You can now create an ActionSet defining backup action, which will take individual snapshots of every PVC bound to Picture Gallery. The ActionSet should be created in the same namespace as the controller.
+
+```
+# Create the actionset that causes the controller to kick off the backup
+$ kubectl --namespace kanister create -f examples/picture-gallery-pvc-snapshot/backup-actionset.yaml
+actionset "pic-gal-pvc-snapshot--f4c4q" created
+
+# View the status of the actionset
+$ kubectl --namespace kanister get actionset pic-gal-pvc-snapshot--f4c4q -oyaml
+
+# Check the controller logs to see if the backup action is complete before moving to next step
+$ kubectl --namespace kanister logs -l app=kanister-operator
+```
+
+### 3. Restore the PVCs
+
+Now that you have taken the snapshots of all the PVCs, you can test the backup action by running restore command using the `kanctl` tool as shown below. Once the restore is completed, you can see that the PVCs are up and the Picture Gallery pod is running
+
+```bash
+# List all PVCs assoicated with Picture Gallery
+$ kubectl get pvc
+
+# Restore all PVCs for Picture Gallery
+$ kanctl --namespace kanister create actionset --action restore --from "pic-gal-pvc-snapshot-f4c4q"
+actionset "restore-pic-gal-pvc-snapshot-hc7tt-6c6fk" created
+
+# View the status of the actionset
+$ kubectl --namespace kanister get actionset restore-pic-gal-pvc-snapshot-hc7tt-6c6fk -oyaml
+
+# check the controller logs to see if the restore action is complete before moving to next step
+$ kubectl --namespace kanister logs -l app=kanister-operator
+
+#View the status of the PVCs and Picture Gallery pod
+$ kubectl get pvc
+$ kubectl get pods
+```
+
+### 4. Delete the Snapshots
+
+The snapshots created by backup action can be cleaned up using the following command:
+
+```bash
+$ kanctl --namespace kanister create actionset --action delete --from "pic-gal-pvc-snapshot-f4c4q"
+actionset "delete-pic-gal-pvc-snapshot-hc7tt-6c6fk" created
+
+# View the status of the actionset
+$ kubectl --namespace kanister get actionset delete-pic-gal-pvc-snapshot-hc7tt-6c6fk -oyaml
+```
+
+### Troubleshooting
+
+If you run into any issues with the above commands, you can check the logs of the controller using:
+
+```bash
+$ kubectl --namespace kanister logs -l app=kanister-operator
+```

examples/picture-gallery-pvc-snapshot/picture-gallery-deployment.yaml

@@ -72,7 +72,7 @@ spec:
         tier: frontend
     spec:
       containers:
-      - image: kastenio/picturegallery:70307e
+      - image: kastenio/picturegallery:3fbc5be
         livenessProbe:
           httpGet:
             path: /