Problem: k8s docs not clear about who they're for (#2439)

Solution: Add a note atop k8s docs pages to clarify who they're for

docs/server/source/production-deployment-template/architecture.rst

@@ -1,13 +1,25 @@
-Architecture of a BigchainDB Node
+Architecture of a BigchainDB Node Running in a Kubernetes Cluster
-==================================
+=================================================================
 
-A BigchainDB Production deployment is hosted on a Kubernetes cluster and includes:
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
+If you deploy a BigchainDB node into a Kubernetes cluster
+as described in these docs, it will include:
 
 * NGINX, OpenResty, BigchainDB, MongoDB and Tendermint
   `Kubernetes Services <https://kubernetes.io/docs/concepts/services-networking/service/>`_.
-* NGINX, OpenResty, BigchainDB and MongoDB Monitoring Agent.
+* NGINX, OpenResty, BigchainDB and MongoDB Monitoring Agent
   `Kubernetes Deployments <https://kubernetes.io/docs/concepts/workloads/controllers/deployment/>`_.
-* MongoDB and Tendermint `Kubernetes StatefulSet <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`_.
+* MongoDB and Tendermint `Kubernetes StatefulSets <https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/>`_.
 * Third party services like `3scale <https://3scale.net>`_,
   `MongoDB Cloud Manager <https://cloud.mongodb.com>`_ and the
   `Azure Operations Management Suite

docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst

@@ -3,6 +3,17 @@
 Kubernetes Template: Deploying a BigchainDB network
 ===================================================
 
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
 This page describes how to deploy a static BigchainDB + Tendermint network.
 
 If you want to deploy a stand-alone BigchainDB node in a BigchainDB cluster,

docs/server/source/production-deployment-template/index.rst

@@ -1,10 +1,19 @@
 Production Deployment Template
 ==============================
 
-This section outlines how *we* deploy production BigchainDB,
+.. note::
-integrated with Tendermint(backend for BFT consensus),
+
-clusters on Microsoft Azure using
+   A highly-available Kubernetes cluster requires at least five virtual machines
-Kubernetes. We improve it constantly.
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
+This section outlines a way to deploy a production BigchainDB node (or BigchainDB cluster)
+on Microsoft Azure using Kubernetes.
 You may choose to use it as a template or reference for your own deployment,
 but *we make no claim that it is suitable for your purposes*.
 Feel free change things to suit your needs or preferences.

docs/server/source/production-deployment-template/node-config-map-and-secrets.rst

@@ -3,6 +3,17 @@
 How to Configure a BigchainDB Node
 ==================================
 
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
 This page outlines the steps to set a bunch of configuration settings
 in your BigchainDB node.
 They are pushed to the Kubernetes cluster in two files,

docs/server/source/production-deployment-template/node-on-kubernetes.rst

@@ -3,7 +3,18 @@
 Kubernetes Template: Deploy a Single BigchainDB Node
 ====================================================
 
-This page describes how to deploy a BigchainDB + Tendermint node
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
+This page describes how to deploy a BigchainDB node
 using `Kubernetes <https://kubernetes.io/>`_.
 It assumes you already have a running Kubernetes cluster.
 

docs/server/source/production-deployment-template/tectonic-azure.rst

@@ -1,6 +1,17 @@
 Walkthrough: Deploy a Kubernetes Cluster on Azure using Tectonic by CoreOS
 ==========================================================================
 
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
 A BigchainDB node can be run inside a `Kubernetes <https://kubernetes.io/>`_
 cluster.
 This page describes one way to deploy a Kubernetes cluster on Azure using Tectonic.

docs/server/source/production-deployment-template/template-kubernetes-azure.rst

@@ -1,6 +1,17 @@
 Template: Deploy a Kubernetes Cluster on Azure
 ==============================================
 
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
 A BigchainDB node can be run inside a `Kubernetes <https://kubernetes.io/>`_
 cluster.
 This page describes one way to deploy a Kubernetes cluster on Azure.

docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst

@@ -1,6 +1,17 @@
 Kubernetes Template: Upgrade all Software in a BigchainDB Node
 ==============================================================
 
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
 This page outlines how to upgrade all the software associated
 with a BigchainDB node running on Kubernetes,
 including host operating systems, Docker, Kubernetes,

docs/server/source/production-deployment-template/workflow.rst

@@ -3,9 +3,19 @@
 Overview
 ========
 
-This page summarizes the steps *we* go through
+.. note::
+
+   A highly-available Kubernetes cluster requires at least five virtual machines
+   (three for the master and two for your app's containers).
+   Therefore we don't recommend using Kubernetes to run a BigchainDB node
+   if that's the only thing the Kubernetes cluster will be running.
+   Instead, see **How to Set Up a BigchainDB Network**.
+   If your organization already *has* a big Kubernetes cluster running many containers,
+   and your organization has people who know Kubernetes,
+   then this Kubernetes deployment template might be helpful.
+
+This page summarizes some steps to go through
 to set up a production BigchainDB cluster.
-We are constantly improving them.
 You can modify them to suit your needs.
 
 .. _generate-the-blockchain-id-and-genesis-time: