Merge pull request #1190 from bigchaindb/docs-re-advanced-azure-node

[WIP] Docs re/ Node on Kubernetes on Azure

docs/server/source/cloud-deployment-starter-templates/index.rst

@@ -1,15 +0,0 @@
-Cloud Deployment Starter Templates
-==================================
-
-We have some "starter templates" to deploy a basic, working, but bare-bones BigchainDB node on various cloud providers. They should *not* be used as-is to deploy a node for production. They can be used as a starting point. A full production node should meet the requirements outlined in the section on :doc:`production node assumptions, components and requirements <../nodes/index>`.
-
-You don't have to use the tools we use in the starter templates (e.g. Terraform and Ansible). You can use whatever tools you prefer.
-
-If you find the cloud deployment starter templates for nodes helpful, then you may also be interested in our scripts for :doc:`deploying a testing cluster on AWS <../clusters-feds/aws-testing-cluster>` (documented in the Clusters & Federations section).
-
-.. toctree::
-   :maxdepth: 1
-
-   template-terraform-aws
-   template-ansible
-   azure-quickstart-template

docs/server/source/cloud-deployment-templates/azure-quickstart-template.md

@@ -1,6 +1,6 @@
 # Azure Quickstart Template
 
-If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
+If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
 
 Note: There was an Azure quickstart template in the `blockchain` directory of Microsoft's `Azure/azure-quickstart-templates` repository on GitHub. It's gone now; it was replaced by the one described here.
 

docs/server/source/cloud-deployment-templates/index.rst

@@ -0,0 +1,18 @@
+Cloud Deployment Templates
+==========================
+
+We have some "templates" to deploy a basic, working, but bare-bones BigchainDB node on various cloud providers. They should *not* be used as-is to deploy a node for production. They can be used as a starting point.
+
+You don't have to use the tools we use in the templates. You can use whatever tools you prefer.
+
+If you find the cloud deployment templates for nodes helpful, then you may also be interested in our scripts for :doc:`deploying a testing cluster on AWS <../clusters-feds/aws-testing-cluster>` (documented in the Clusters & Federations section).
+
+.. toctree::
+   :maxdepth: 1
+
+   template-terraform-aws
+   template-ansible
+   azure-quickstart-template
+   template-kubernetes-azure
+   node-on-kubernetes
+   

docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst

@@ -0,0 +1,46 @@
+Run a BigchainDB Node in a Kubernetes Cluster
+=============================================
+
+Assuming you already have a `Kubernetes <https://kubernetes.io/>`_
+cluster up and running, this page describes how to run a
+BigchainDB node in it.
+
+
+Step 1: Install kubectl
+-----------------------
+
+kubectl is the Kubernetes CLI.
+If you don't already have it installed,
+then see the `Kubernetes docs to install it
+<https://kubernetes.io/docs/user-guide/prereqs/>`_.
+
+
+Step 2: Configure kubectl
+-------------------------
+
+The default location of the kubectl configuration file is ``~/.kube/config``.
+If you don't have that file, then you need to get it.
+
+If you deployed your Kubernetes cluster on Azure
+using the Azure CLI 2.0 (as per :doc:`our template <template-kubernetes-azure>`),
+then you can get the ``~/.kube/config`` file using:
+
+.. code:: bash
+
+   $ az acs kubernetes get-credentials \
+   --resource-group <name of resource group containing the cluster> \
+   --name <ACS cluster name>
+
+
+Step 3: Run a MongoDB Container 
+-------------------------------
+
+To start a MongoDB Docker container in a pod on one of the cluster nodes:
+
+.. code:: bash
+
+   $ kubectl ?????
+
+
+Note: The BigchainDB Dashboard can be deployed
+as a Docker container, like everything else.

docs/server/source/cloud-deployment-templates/template-ansible.md

@@ -1,6 +1,6 @@
 # Template: Ansible Playbook to Run a BigchainDB Node on an Ubuntu Machine
 
-If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
+If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
 
 This page explains how to use [Ansible](https://www.ansible.com/) to install, configure and run all the software needed to run a one-machine BigchainDB node on a server running Ubuntu 16.04.
 

docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst

@@ -0,0 +1,103 @@
+Template: Deploy a Kubernetes Cluster on Azure
+==============================================
+
+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.
+
+
+Step 1: Get a Pay-As-You-Go Azure Subscription
+----------------------------------------------
+
+Microsoft Azure has a Free Trial subscription (at the time of writing),
+but it's too limited to run an advanced BigchainDB node.
+Sign up for a Pay-As-You-Go Azure subscription
+via `the Azure website <https://azure.microsoft.com>`_.
+
+You may find that you have to sign up for a Free Trial subscription first.
+That's okay: you can have many subscriptions.
+
+
+Step 2: Deploy an Azure Container Service (ACS)
+-----------------------------------------------
+
+It's *possible* to deploy an Azure Container Service (ACS)
+from the `Azure Portal <https://portal.azure.com>`_
+(i.e. online in your web browser)
+but it's actually easier to do it using the Azure
+Command-Line Interface (CLI).
+(The Azure Portal will ask you for a public SSH key
+and a "service principal," and you'll have to create those
+first if they don't exist. The CLI will create them
+for you if necessary.)
+
+Microsoft has `instructions to install the Azure CLI 2.0
+on most common operating systems
+<https://docs.microsoft.com/en-us/cli/azure/install-az-cli2>`_.
+Do that.
+
+Next, login to your account using:
+
+.. code:: bash
+
+   $ az login
+
+It will tell you to open a web page and to copy a code to that page.
+
+If the login is a success, you will see some information
+about all your subscriptions, including the one that is currently
+enabled (``"state": "Enabled"``). If the wrong one is enabled,
+you can switch to the right one using:
+
+.. code:: bash
+
+   $ az account set --subscription <subscription name or ID>
+
+Next, you will have to pick the Azure data center location
+where you'd like to deploy your cluster.
+You can get a list of all available locations using:
+
+.. code:: bash
+
+   $ az account list-locations
+
+Next, create an Azure "resource group" to contain all the
+resources (virtual machines, subnets, etc.) associated
+with your soon-to-be-deployed cluster. You can name it
+whatever you like but avoid fancy characters because they may
+confuse some software.
+
+.. code:: bash
+
+   $ az group create --name <resource group name> --location <location name>
+
+Example location names are ``koreacentral`` and ``westeurope``.
+
+Finally, you can deploy an ACS using something like:
+
+.. code:: bash
+
+   $ az acs create --name <a made-up cluster name> \
+   --resource-group <name of resource group created earlier> \
+   --agent-count 3 \
+   --agent-vm-size Standard_D2_v2 \
+   --dns-prefix <make up a name> \
+   --generate-ssh-keys \
+   --location <same location as the resource group> \
+   --orchestrator-type kubernetes
+
+There are more options. For help understanding all the options, use the built-in help:
+
+.. code:: bash
+
+   $ az acs create --help
+
+It takes a few minutes for all the resources to deploy.
+You can watch the progress in the `Azure Portal
+<https://portal.azure.com>`_:
+go to **Resource groups** (with the blue cube icon)
+and click on the one you created
+to see all the resources in it.
+
+Next, you can :doc:`run a BigchainDB node on your new
+Kubernetes cluster <node-on-kubernetes>`.

docs/server/source/cloud-deployment-templates/template-terraform-aws.md

@@ -1,6 +1,6 @@
 # Template: Using Terraform to Provision an Ubuntu Machine on AWS
 
-If you didn't read the introduction to the [cloud deployment starter templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
+If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
 
 This page explains a way to use [Terraform](https://www.terraform.io/) to provision an Ubuntu machine (i.e. an EC2 instance with Ubuntu 16.04) and other resources on [AWS](https://aws.amazon.com/). That machine can then be used to host a one-machine BigchainDB node.
 

docs/server/source/index.rst

@@ -7,7 +7,7 @@ BigchainDB Server Documentation
    ← Back to All BigchainDB Docs <https://docs.bigchaindb.com/en/latest/index.html>
    introduction
    quickstart
-   cloud-deployment-starter-templates/index
+   cloud-deployment-templates/index
    nodes/index
    dev-and-test/index
    server-reference/index

docs/server/source/introduction.md

@@ -8,7 +8,7 @@ Note that there are a few kinds of nodes:
 
 - A **dev/test node** is a node created by a developer working on BigchainDB Server, e.g. for testing new or changed code. A dev/test node is typically run on the developer's local machine.
 
-- A **bare-bones node** is a node deployed in the cloud, either as part of a testing cluster or as a starting point before upgrading the node to be production-ready. Our cloud deployment starter templates deploy a bare-bones node, as do our scripts for deploying a testing cluster on AWS.
+- A **bare-bones node** is a node deployed in the cloud, either as part of a testing cluster or as a starting point before upgrading the node to be production-ready. Our cloud deployment templates deploy a bare-bones node, as do our scripts for deploying a testing cluster on AWS.
 
 - A **production node** is a node that is part of a federation's BigchainDB cluster. A production node has the most components and requirements.
 
@@ -16,7 +16,7 @@ Note that there are a few kinds of nodes:
 ## Setup Instructions for Various Cases
 
 * [Set up a local stand-alone BigchainDB node for learning and experimenting: Quickstart](quickstart.html)
-* [Set up and run a bare-bones node in the cloud](cloud-deployment-starter-templates/index.html)
+* [Set up and run a bare-bones node in the cloud](cloud-deployment-templates/index.html)
 * [Set up and run a local dev/test node for developing and testing BigchainDB Server](dev-and-test/setup-run-node.html)
 * [Deploy a testing cluster on AWS](clusters-feds/aws-testing-cluster.html)
 * [Set up and run a federation (including production nodes)](clusters-feds/set-up-a-federation.html)

docs/server/source/nodes/node-assumptions.md

@@ -8,6 +8,6 @@ We make some assumptions about production nodes:
 
 2. Each production node in a federation's cluster is managed by a different person or team.
 
-Because of the first assumption, we don't provide a detailed cookbook explaining how to secure a server, or other things that a sysadmin should know. (We do provide some [starter templates](../cloud-deployment-starter-templates/index.html), but those are just a starting point.)
+Because of the first assumption, we don't provide a detailed cookbook explaining how to secure a server, or other things that a sysadmin should know. (We do provide some [templates](../cloud-deployment-templates/index.html), but those are just a starting point.)