From 2e33302504eabe9c1293866dde52c7786d5acd91 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Mon, 6 Aug 2018 13:46:29 +0200 Subject: [PATCH] Problem: k8s docs not clear about who they're for Solution: Add a note atop k8s docs pages to clarify who they're for --- .../architecture.rst | 22 ++++++++++++++----- .../bigchaindb-network-on-kubernetes.rst | 11 ++++++++++ .../production-deployment-template/index.rst | 17 ++++++++++---- .../node-config-map-and-secrets.rst | 11 ++++++++++ .../node-on-kubernetes.rst | 13 ++++++++++- .../tectonic-azure.rst | 11 ++++++++++ .../template-kubernetes-azure.rst | 11 ++++++++++ .../upgrade-on-kubernetes.rst | 11 ++++++++++ .../workflow.rst | 14 ++++++++++-- 9 files changed, 109 insertions(+), 12 deletions(-) diff --git a/docs/server/source/production-deployment-template/architecture.rst b/docs/server/source/production-deployment-template/architecture.rst index 4d029f5c..2bfc9e4c 100644 --- a/docs/server/source/production-deployment-template/architecture.rst +++ b/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 `_. -* NGINX, OpenResty, BigchainDB and MongoDB Monitoring Agent. +* NGINX, OpenResty, BigchainDB and MongoDB Monitoring Agent `Kubernetes Deployments `_. -* MongoDB and Tendermint `Kubernetes StatefulSet `_. +* MongoDB and Tendermint `Kubernetes StatefulSets `_. * Third party services like `3scale `_, `MongoDB Cloud Manager `_ and the `Azure Operations Management Suite diff --git a/docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst b/docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst index 100dafb5..d3caf6a3 100644 --- a/docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst +++ b/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, diff --git a/docs/server/source/production-deployment-template/index.rst b/docs/server/source/production-deployment-template/index.rst index 64a834db..fa9d64c1 100644 --- a/docs/server/source/production-deployment-template/index.rst +++ b/docs/server/source/production-deployment-template/index.rst @@ -1,10 +1,19 @@ Production Deployment Template ============================== -This section outlines how *we* deploy production BigchainDB, -integrated with Tendermint(backend for BFT consensus), -clusters on Microsoft Azure using -Kubernetes. We improve it constantly. +.. 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 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. diff --git a/docs/server/source/production-deployment-template/node-config-map-and-secrets.rst b/docs/server/source/production-deployment-template/node-config-map-and-secrets.rst index 7bf8d0de..d308bc11 100644 --- a/docs/server/source/production-deployment-template/node-config-map-and-secrets.rst +++ b/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, diff --git a/docs/server/source/production-deployment-template/node-on-kubernetes.rst b/docs/server/source/production-deployment-template/node-on-kubernetes.rst index b6fbeedd..96f4098a 100644 --- a/docs/server/source/production-deployment-template/node-on-kubernetes.rst +++ b/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 `_. It assumes you already have a running Kubernetes cluster. diff --git a/docs/server/source/production-deployment-template/tectonic-azure.rst b/docs/server/source/production-deployment-template/tectonic-azure.rst index f9d58074..03cfb433 100644 --- a/docs/server/source/production-deployment-template/tectonic-azure.rst +++ b/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 `_ cluster. This page describes one way to deploy a Kubernetes cluster on Azure using Tectonic. diff --git a/docs/server/source/production-deployment-template/template-kubernetes-azure.rst b/docs/server/source/production-deployment-template/template-kubernetes-azure.rst index 7b6b4e2c..9ff10cac 100644 --- a/docs/server/source/production-deployment-template/template-kubernetes-azure.rst +++ b/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 `_ cluster. This page describes one way to deploy a Kubernetes cluster on Azure. diff --git a/docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst b/docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst index 07d63f7b..8d836564 100644 --- a/docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst +++ b/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, diff --git a/docs/server/source/production-deployment-template/workflow.rst b/docs/server/source/production-deployment-template/workflow.rst index 61b499ee..793175b9 100644 --- a/docs/server/source/production-deployment-template/workflow.rst +++ b/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: