init

_sources/blueprint.rst.txt

@@ -0,0 +1,12 @@
+MongoDB Kanister Blueprint
+--------------------------
+
+The below blueprint is the actual blueprint used to backup and restore
+MongoDB at the time this documentation was generated.
+
+.. literalinclude:: ../go/src/kio/kanister/examples/mongodb.yaml
+  :language: yaml
+  :linenos:
+
+.. spelling::
+   Kanister

_sources/custom.rst.txt

@@ -0,0 +1,51 @@
+.. _custom:
+
+Installing Custom Applications
+==============================
+
+While we have a sample application deployed for you to experiment
+with, we encourage you to deploy any of your own applications, whether
+they be custom container images or images downloaded from
+DockerHub. The only current restriction is that they need to be
+deployed into the ``default`` namespace.
+
+Applications can be deployed via the use of either ``kubectl`` (and
+the provided configuration file that was emailed to you), via the
+Kubernetes dashboard available at
+``https://your-testdrive-url.example.com/dashboard/``, or via Helm.
+
+Once you have deployed your own applications, please feel free to
+create policies that cover that application and bring the system back
+into compliance, run manual restores, test restores, etc.
+
+
+Using Helm
+----------
+
+The test cluster has Helm's Tiller installed in the "default" namespace.
+Helm can be used to install and manage applications once ``kubectl``
+is appropriately configured. Since Tiller is installed in the default
+namespace, one of the following two approaches is needed:
+
+* Exporting an environment variable: ``export TILLER_NAMESPACE=default``.
+* Executing ``helm`` with the ``--tiller-namespace default`` flag.
+
+Helm example
+############
+
+The below example shows how one can install MongoDB through the use of
+a Helm chart.
+
+.. code-block:: bash
+
+  export TILLER_NAMESPACE=default
+  helm install stable/mongodb-replicaset
+
+Note that this is a a dynamically scalable MongoDB replica set using
+Kubernetes StatefulSets and Init Containers. We will also be modifying
+this Helm chart later to provide application-consistent snapshots
+using Kanister, a Kasten framework.
+
+.. spelling::
+   Init
+   Kanister

_sources/index.rst.txt

@@ -0,0 +1,99 @@
+.. K10 documentation master file, created by
+   sphinx-quickstart on Thu May 25 15:27:06 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Documentation Overview
+======================
+
+Kasten's K10 platform is a unique application-centric data management
+solution for all public and private Kubernetes deployments that
+balances the needs of operators and developers making it easier to
+build, deploy, and manage stateful containerized applications at
+scale.
+
+Through a top-down application focus, K10 provides the right balance
+and separation of concerns between developers and operators. In
+particular, the current release of the platform focuses on the
+following four use cases:
+
+|
+
+   .. image:: ./_static/index_usecases.jpg
+
+|
+
+**Test/Dev Environments**
+  K10 supports the safe and automated export of data from production
+  to test and dev environments with data masking support. In addition,
+  it also provides the ability to clone applications and namespaces to
+  help with debugging and workspace suspend/resume workloads.
+
+**Cloud Migration**
+  To support disaster-recovery and ultimately cross-cloud portability,
+  K10 allows for the seamless migration of applications with their
+  data across non-federated Kubernetes clusters. These clusters can be
+  under the same account, in different accounts, or even different
+  accounts across different cloud provider regions.
+
+**Backup and Recovery**
+  The K10 platform supports protecting applications both at the volume
+  level and, through the use of an open-source framework called
+  Kanister, at the application/data-service level. Based on
+  label-based criteria, K10 can protect applications today against
+  accidental and malicious data loss.
+
+**Disaster Recovery**
+  To assist in the fast recovery from site or cluster outages, K10
+  supports simple orchestrated recovery that can be full or partial.
+
+
+Quickstart
+----------
+
+If you want a high-level introduction to the system, we recommend
+starting with the :ref:`quickstart` guide.
+
+If you are using this documentation for our test drive system, we
+recommend you get started with the :ref:`testdrive` documentation
+first.
+
+Guided Walkthrough
+------------------
+
+For a more detailed documentation-driven walkthrough of the system,
+the recommended sequence of actions is:
+
+#. :ref:`install`
+#. :ref:`overview`
+#. :ref:`protect`
+#. :ref:`restore`
+#. :ref:`migration`
+#. :ref:`kanister`
+
+Support
+=======
+
+You can file bug reports or get help by sending email to our `support <[email protected]>`_
+alias. You can also call at any time for either support or
+feedback: +1-412-370-2852.
+
+
+.. toctree::
+   :hidden:
+
+   self
+   quickstart
+   install
+   overview
+   protect
+   restore
+   migration
+   kanister
+   restrictions
+   testdrive
+
+.. spelling::
+   dev
+   Kanister
+   namespaces

_sources/install.rst.txt

@@ -0,0 +1,217 @@
+.. _install:
+
+K10: Install
+============
+
+If you are deploying the Kasten platform in your own Kubernetes
+cluster in AWS or Google (GKE), the below instructions will help.
+
+.. contents:: Installation Overview
+  :local:
+
+Prerequisites
+-------------
+
+* You need the `Helm package manager <https://helm.sh/>`_
+* Just like our :doc:`Kanister </kanister>` charts, you need to add
+  the Kasten Helm repository to your local setup
+
+.. code-block:: console
+
+   $ helm repo add kasten https://charts.kasten.io/
+
+
+Installing on AWS
+-----------------
+
+To install on AWS, you need to define two environment variables that
+specify your access key id and secret access key.
+After doing so, just run the following command to install K10,
+the Kasten platform.
+
+.. code-block:: console
+
+   $ helm install kasten/k10 --name=k10 --namespace=kasten-io \
+             --set k10_secrets.aws_access_key_id="${AWS_ACCESS_KEY_ID}" \
+             --set k10_secrets.aws_secret_access_key="${AWS_SECRET_ACCESS_KEY}"
+
+In particular, the above AWS access keys should have the following
+policy permissions.
+
+
+EC2 (EBS) Permissions
++++++++++++++++++++++++++
+
+The following permissions are needed by Kasten to operate on EBS, AWS
+EC2's underlying block storage solution
+
+.. literalinclude:: ../pipelines/manifests/test_drive/aws_ec2_k10_minimal_policy.json
+  :language: javascript
+
+
+Optional S3 Permissions
++++++++++++++++++++++++
+
+If you are going to migrate applications between different clusters,
+you will need an S3 bucket for it. The credentials used above should
+have the following permissions on the bucket.
+
+.. note:: A future release will allow a completely different set of
+  credentials to be used for accessing the S3 object store.
+
+.. literalinclude:: ../pipelines/manifests/test_drive/aws_s3_bucket_acess_template.json
+  :language: javascript
+
+Installing on GKE
+-----------------
+
+A `GCP Service Account (SA)
+<https://cloud.google.com/compute/docs/access/service-accounts>`_
+automatically gets created with every GKE cluster.  This SA can be
+accessed within the GKE cluster to perform actions on GCP resources
+and is the simplest way to run the Kasten platform.  If the SA is
+correctly configured (see more below), just run the following command
+to install K10:
+
+.. code-block:: console
+
+   $ helm install kasten/k10 --name=k10 --namespace=kasten-io
+
+Service Account Scope
++++++++++++++++++++++
+
+By default, the default service account scope is sufficient for
+K10. However, for cross-cluster application migration and K10 DR, we
+also do need permissions to access Google Cloud Storage (GCS)
+(``https://www.googleapis.com/auth/devstorage.read_write`` or,
+alternatively, ``storage-full`` can also be used as an alias). The
+complete scope listing is as follows:
+
+.. code-block:: console
+
+  compute-rw,
+  storage-full,
+  cloud-platform,
+  https://www.googleapis.com/auth/trace.append,
+  https://www.googleapis.com/auth/service.management.readonly,
+  https://www.googleapis.com/auth/servicecontrol,
+  https://www.googleapis.com/auth/monitoring.write,
+  https://www.googleapis.com/auth/logging.write,
+
+If the cluster was not originally created with the additional
+credential, it is technically possible to modify the scope following
+`these instructions
+<https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances#changeserviceaccountandscopes>`_.
+However, given the need to restart instances, that is not
+recommended. As documented below, we recommend creating a separate
+service account with the correct permissions.
+
+Alternatively, if a new cluster is being created, the modified scope
+can be set at that time. For example, it can be passed to the
+``gcloud`` command via the ``--scope`` parameter.
+
+Using a Separate Service Account
+++++++++++++++++++++++++++++++++
+
+
+Creating a new Service Account
+##############################
+
+K10 requires a newly created service account to contain the following
+roles:
+
+.. code-block:: console
+
+  roles/compute.storageAdmin
+  roles/storage.admin
+
+The following steps should be used to create the service account and
+add the required permissions:
+
+.. code-block:: console
+
+  myproject=$(gcloud config get-value core/project)
+  gcloud iam service-accounts create k10-test-sa --display-name "K10 Service Account"
+  k10saemail=$(gcloud iam service-accounts list --filter "k10-test-sa" --format="value(email)")
+  gcloud iam service-accounts keys create --iam-account=${k10saemail} k10-sa-key.json
+  gcloud projects add-iam-policy-binding ${myproject} --member serviceAccount:${k10saemail} --role roles/compute.storageAdmin
+  gcloud projects add-iam-policy-binding ${myproject} --member serviceAccount:${k10saemail} --role roles/storage.admin
+
+
+Installing K10 with the new Service Account
+###########################################
+
+For security reasons, ``helm`` does not allow the use of a file
+outside the chart folder. To therefore use the ``k10-sa-key.json``
+generated above, you need to fetch the chart, unpack it, and then
+install with a pointer to the newly created credentials.
+
+.. code-block:: console
+
+  helm fetch kasten/k10 --devel --untar
+  cp k10-sa-key.json k10/
+  helm install k10/ --name=k10 --namespace=kasten-io --set k10_secrets.google_api_key_path=k10-sa-key.json
+
+
+Kasten Dashboard Access
+-----------------------
+
+In order to access :doc:`Kasten Dashboard </overview>`, an `ingress
+controller <https://goo.gl/C2MCYp>`_ needs to be deployed into the
+Kubernetes cluster.  The Kasten Helm chart will deploy the
+`nginx ingress <https://kubeapps.com/charts/stable/nginx-ingress>`_
+and configure it with the NodePort service.  With the default
+configuration, the :doc:`Kasten Dashboard </overview>` is secured and
+can only be accessed via a user who is already authenticated using
+``kubectl`` (see below).
+
+If your cluster already has deployed an ingress controller, you can
+disable the nginx ingress deployment by specifying the following
+option to the ``helm`` command:
+
+.. code-block:: console
+
+    --set nginx.enable=false
+
+To configure nginx ingress to be exposed through the default
+LoadBalacer, please use the following option with ``helm``:
+
+.. code-block:: console
+
+    --set nginx.controller.service.type=LoadBalacer
+
+
+Accessing via ``kubectl``
++++++++++++++++++++++++++
+
+Run the following command to have kubectl establish a proxy connection
+to the ingress controller service
+
+.. code-block:: console
+
+    kubectl proxy
+
+The dashboard will be available at:
+``http://localhost:8001/api/v1/namespaces/kasten-io/services/k10-nginx-controller:http/proxy/``
+
+Accessing via a LoadBalacer
++++++++++++++++++++++++++++
+
+To access the dashboard via the LoadBalancer, you have to first find
+the LoadBalancer's public DNS/IP address:
+
+.. code-block:: console
+
+  kubectl --namespace kasten-io get services k10-nginx-controller \
+     -o jsonpath='{.status.loadBalancer.ingress[].hostname}'
+
+The K10 dashboard will be available at the root of the DNS or IP
+address returned from the above command.
+
+.. note:: Currently, directly viewing the dashboard via the
+  LoadBalancer is only protected by Basic-Auth.
+
+.. spelling::
+   nginx
+   kubectl
+   Auth