diff --git a/docs/server/source/cloud-deployment-templates/add-node-on-kubernetes.rst b/docs/server/source/cloud-deployment-templates/add-node-on-kubernetes.rst index 542d3d2b..ea435ed3 100644 --- a/docs/server/source/cloud-deployment-templates/add-node-on-kubernetes.rst +++ b/docs/server/source/cloud-deployment-templates/add-node-on-kubernetes.rst @@ -1,25 +1,26 @@ -Add a BigchainDB Node in a Kubernetes Cluster -============================================= +Kubernetes Template: Add a BigchainDB Node to an Existing BigchainDB Cluster +============================================================================ -**Refer this document if you want to add a new BigchainDB node to an existing -cluster** +This page describes how to deploy a BigchainDB node using Kubernetes, +and how to add that node to an existing BigchainDB cluster. +It assumes you already have a running Kubernetes cluster +where you can deploy the new BigchainDB node. -**If you want to start your first BigchainDB node in the BigchainDB cluster, -refer** -:doc:`this ` +If you want to deploy the first BigchainDB node in a BigchainDB cluster, +or a stand-alone BigchainDB node, +then see :doc:`the page about that `. Terminology Used ---------------- -``existing cluster`` will refer to the existing (or any one of the existing) -Kubernetes cluster that already hosts a BigchainDB instance with a MongoDB -backend. +``existing cluster`` will refer to one of the existing Kubernetes clusters +hosting one of the existing BigchainDB nodes. ``ctx-1`` will refer to the kubectl context of the existing cluster. ``new cluster`` will refer to the new Kubernetes cluster that will run a new -BigchainDB instance with a MongoDB backend. +BigchainDB node (including a BigchainDB instance and a MongoDB instance). ``ctx-2`` will refer to the kubectl context of the new cluster. @@ -38,26 +39,19 @@ existing cluster. Step 1: Prerequisites --------------------- -* You will need to have a public and private key for the new BigchainDB - instance you will set up. +* A public/private key pair for the new BigchainDB instance. * The public key should be shared offline with the other existing BigchainDB - instances. The means to achieve this requirement is beyond the scope of this - document. + nodes in the existing BigchainDB cluster. -* You will need the public keys of all the existing BigchainDB instances. The - means to achieve this requirement is beyond the scope of this document. +* You will need the public keys of all the existing BigchainDB nodes. * A new Kubernetes cluster setup with kubectl configured to access it. - If you are using Kubernetes on Azure Container Server (ACS), please refer - our documentation `here ` for the set up. -If you haven't read our guide to set up a -:doc:`node on Kubernetes `, now is a good time to jump in -there and then come back here as these instructions build up from there. +* Some familiarity with deploying a BigchainDB node on Kubernetes. + See our :doc:`other docs about that `. - -NOTE: If you are managing multiple kubernetes clusters, from your local +Note: If you are managing multiple Kubernetes clusters, from your local system, you can run ``kubectl config view`` to list all the contexts that are available for the local kubectl. To target a specific cluster, add a ``--context`` flag to the kubectl CLI. For @@ -71,9 +65,10 @@ example: $ kubectl --context ctx-2 proxy --port 8002 -Step 2: Prepare the New Kubernetes cluster +Step 2: Prepare the New Kubernetes Cluster ------------------------------------------ -Follow the steps in the sections to set up Storage Classes and Persisten Volume + +Follow the steps in the sections to set up Storage Classes and Persistent Volume Claims, and to run MongoDB in the new cluster: 1. :ref:`Add Storage Classes ` @@ -84,13 +79,13 @@ Claims, and to run MongoDB in the new cluster: Step 3: Add the New MongoDB Instance to the Existing Replica Set ---------------------------------------------------------------- -Note that by ``replica set`` we are referring to the MongoDB replica set, and not -to Kubernetes' ``ReplicaSet``. -If you are not the administrator of an existing MongoDB/BigchainDB instance, you -will have to coordinate offline with an existing administrator so that s/he can -add the new MongoDB instance to the replica set. The means to achieve this is -beyond the scope of this document. +Note that by ``replica set``, we are referring to the MongoDB replica set, +not a Kubernetes' ``ReplicaSet``. + +If you are not the administrator of an existing BigchainDB node, you +will have to coordinate offline with an existing administrator so that they can +add the new MongoDB instance to the replica set. Add the new instance of MongoDB from an existing instance by accessing the ``mongo`` shell. @@ -100,7 +95,7 @@ Add the new instance of MongoDB from an existing instance by accessing the $ kubectl --context ctx-1 exec -it mdb-0 -c mongodb -- /bin/bash root@mdb-0# mongo --port 27017 -We can only add members to a replica set from the ``PRIMARY`` instance. +One can only add members to a replica set from the ``PRIMARY`` instance. The ``mongo`` shell prompt should state that this is the primary member in the replica set. If not, then you can use the ``rs.status()`` command to find out who the @@ -113,7 +108,7 @@ Run the ``rs.add()`` command with the FQDN and port number of the other instance PRIMARY> rs.add(":") -Step 4: Verify the replica set membership +Step 4: Verify the Replica Set Membership ----------------------------------------- You can use the ``rs.conf()`` and the ``rs.status()`` commands available in the @@ -123,7 +118,7 @@ The new MongoDB instance should be listed in the membership information displayed. -Step 5: Start the new BigchainDB instance +Step 5: Start the New BigchainDB Instance ----------------------------------------- Get the file ``bigchaindb-dep.yaml`` from GitHub using: @@ -149,20 +144,20 @@ Create the required Deployment using: You can check its status using the command ``kubectl get deploy -w`` -Step 6: Restart the existing BigchainDB instance(s) +Step 6: Restart the Existing BigchainDB Instance(s) --------------------------------------------------- -Add public key of the new BigchainDB instance to the keyring of all the -existing instances and update the BigchainDB instances using: + +Add the public key of the new BigchainDB instance to the keyring of all the +existing BigchainDB instances and update the BigchainDB instances using: .. code:: bash $ kubectl --context ctx-1 replace -f bigchaindb-dep.yaml -This will create a ``rolling deployment`` in Kubernetes where a new instance of +This will create a "rolling deployment" in Kubernetes where a new instance of BigchainDB will be created, and if the health check on the new instance is successful, the earlier one will be terminated. This ensures that there is zero downtime during updates. -You can login to an existing BigchainDB instance and run the ``bigchaindb -show-config`` command to see the configuration update to the keyring. - +You can SSH to an existing BigchainDB instance and run the ``bigchaindb +show-config`` command to check that the keyring is updated. diff --git a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst index 650d2f45..b19d79a3 100644 --- a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst +++ b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst @@ -1,15 +1,13 @@ -Bootstrap a BigchainDB Node in a Kubernetes Cluster -=================================================== +Kubernetes Template: Deploy a Single BigchainDB Node +==================================================== -**Refer this document if you are starting your first BigchainDB instance in -a BigchainDB cluster or starting a stand-alone BigchainDB instance** +This page describes how to deploy the first BigchainDB node +in a BigchainDB cluster, or a stand-alone BigchainDB node, +using `Kubernetes `_. +It assumes you already have a running Kubernetes cluster. -**If you want to add a new BigchainDB node to an existing cluster, refer** -:doc:`this ` - -Assuming you already have a `Kubernetes `_ -cluster up and running, this page describes how to run a -BigchainDB node in it. +If you want to add a new BigchainDB node to an existing BigchainDB cluster, +refer to :doc:`the page about that `. Step 1: Install kubectl @@ -49,18 +47,17 @@ Step 3: Create Storage Classes MongoDB needs somewhere to store its data persistently, outside the container where MongoDB is running. - -The official MongoDB Docker container exports two volume mounts with correct +Our MongoDB Docker container +(based on the official MongoDB Docker container) +exports two volume mounts with correct permissions from inside the container: +* The directory where the mongod instance stores its data: ``/data/db``. + There's more explanation in the MongoDB docs about `storage.dbpath `_. -* The directory where the mongod instance stores its data - ``/data/db``, - described at `storage.dbpath `_. - -* The directory where mongodb instance stores the metadata for a sharded - cluster - ``/data/configdb/``, described at - `sharding.configDB `_. - +* The directory where the mongodb instance stores the metadata for a sharded + cluster: ``/data/configdb/``. + There's more explanation in the MongoDB docs about `sharding.configDB `_. Explaining how Kubernetes handles persistent volumes, and the associated terminology, @@ -69,9 +66,6 @@ see `the Kubernetes docs about persistent volumes `_. The first thing to do is create the Kubernetes storage classes. -We will accordingly create two storage classes and persistent volume claims in -Kubernetes. - **Azure.** First, you need an Azure storage account. If you deployed your Kubernetes cluster on Azure @@ -85,7 +79,6 @@ Standard storage is lower-cost and lower-performance. It uses hard disk drives (HDD). LRS means locally-redundant storage: three replicas in the same data center. - Premium storage is higher-cost and higher-performance. It uses solid state drives (SSD). At the time of writing, @@ -102,11 +95,10 @@ Get the file ``mongo-sc.yaml`` from GitHub using: $ wget https://raw.githubusercontent.com/bigchaindb/bigchaindb/master/k8s/mongodb/mongo-sc.yaml -You may want to update the ``parameters.location`` field in both the files to +You may have to update the ``parameters.location`` field in both the files to specify the location you are using in Azure. - -Create the required storage classes using +Create the required storage classes using: .. code:: bash @@ -115,7 +107,7 @@ Create the required storage classes using You can check if it worked using ``kubectl get storageclasses``. -Note that there is no line of the form +**Azure.** Note that there is no line of the form ``storageAccount: `` under ``parameters:``. When we included one and then created a PersistentVolumeClaim based on it, @@ -128,9 +120,8 @@ with the specified skuName and location. Step 4: Create Persistent Volume Claims --------------------------------------- -Next, we'll create two PersistentVolumeClaim objects ``mongo-db-claim`` and +Next, you will create two PersistentVolumeClaim objects ``mongo-db-claim`` and ``mongo-configdb-claim``. - Get the file ``mongo-pvc.yaml`` from GitHub using: .. code:: bash @@ -166,15 +157,14 @@ Step 5: Create the Config Map - Optional This step is required only if you are planning to set up multiple `BigchainDB nodes -`_, else you can -skip to the :ref:`next step `. +`_. MongoDB reads the local ``/etc/hosts`` file while bootstrapping a replica set to resolve the hostname provided to the ``rs.initiate()`` command. It needs to ensure that the replica set is being initialized in the same instance where the MongoDB instance is running. -To achieve this, we create a ConfigMap with the FQDN of the MongoDB instance +To achieve this, you will create a ConfigMap with the FQDN of the MongoDB instance and populate the ``/etc/hosts`` file with this value so that a replica set can be created seamlessly. @@ -188,35 +178,29 @@ You may want to update the ``data.fqdn`` field in the file before creating the ConfigMap. ``data.fqdn`` field will be the DNS name of your MongoDB instance. This will be used by other MongoDB instances when forming a MongoDB replica set. It should resolve to the MongoDB instance in your cluster when -you are done with the setup. This will help when we are adding more MongoDB +you are done with the setup. This will help when you are adding more MongoDB instances to the replica set in the future. -For ACS -^^^^^^^ +**Azure.** In Kubernetes on ACS, the name you populate in the ``data.fqdn`` field will be used to configure a DNS name for the public IP assigned to the Kubernetes Service that is the frontend for the MongoDB instance. - We suggest using a name that will already be available in Azure. We use ``mdb-instance-0``, ``mdb-instance-1`` and so on in this document, which gives us ``mdb-instance-0..cloudapp.azure.com``, ``mdb-instance-1..cloudapp.azure.com``, etc. as the FQDNs. The ```` is the Azure datacenter location you are using, which can also be obtained using the ``az account list-locations`` command. - You can also try to assign a name to an Public IP in Azure before starting the process, or use ``nslookup`` with the name you have in mind to check if it's available for use. - In the rare chance that name in the ``data.fqdn`` field is not available, -we will need to create a ConfigMap with a unique name and restart the +you must create a ConfigMap with a unique name and restart the MongoDB instance. -For Kubernetes on bare-metal or other cloud providers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On other environments, you need to provide the name resolution function +**Kubernetes on bare-metal or other cloud providers.** +You need to provide the name resolution function by other means (using DNS providers like GoDaddy, CloudFlare or your own private DNS server). The DNS set up for other environments is currently beyond the scope of this document. @@ -231,10 +215,9 @@ Create the required ConfigMap using: You can check its status using: ``kubectl get cm`` +Now you are ready to run MongoDB and BigchainDB on our Kubernetes cluster. -Now we are ready to run MongoDB and BigchainDB on our Kubernetes cluster. - Step 6: Run MongoDB as a StatefulSet ------------------------------------ @@ -250,12 +233,10 @@ Note how the MongoDB container uses the ``mongo-db-claim`` and the ``/data/configdb`` diretories (mount path). Note also that we use the pod's ``securityContext.capabilities.add`` specification to add the ``FOWNER`` capability to the container. - That is because MongoDB container has the user ``mongodb``, with uid ``999`` and group ``mongodb``, with gid ``999``. When this container runs on a host with a mounted disk, the writes fail when there is no user with uid ``999``. - To avoid this, we use the Docker feature of ``--cap-add=FOWNER``. This bypasses the uid and gid permission checks during writes and allows data to be persisted to disk. @@ -277,9 +258,9 @@ Create the required StatefulSet using: You can check its status using the commands ``kubectl get statefulsets -w`` and ``kubectl get svc -w`` -You may have to wait for upto 10 minutes wait for disk to be created +You may have to wait for up to 10 minutes for the disk to be created and attached on the first run. The pod can fail several times with the message -specifying that the timeout for mounting the disk has exceeded. +saying that the timeout for mounting the disk was exceeded. Step 7: Initialize a MongoDB Replica Set - Optional @@ -287,8 +268,7 @@ Step 7: Initialize a MongoDB Replica Set - Optional This step is required only if you are planning to set up multiple `BigchainDB nodes -`_, else you can -skip to the :ref:`step 9 `. +`_. Login to the running MongoDB instance and access the mongo shell using: @@ -298,7 +278,7 @@ Login to the running MongoDB instance and access the mongo shell using: $ kubectl exec -it mdb-0 -c mongodb -- /bin/bash root@mdb-0:/# mongo --port 27017 -We initialize the replica set by using the ``rs.initiate()`` command from the +You will initiate the replica set by using the ``rs.initiate()`` command from the mongo shell. Its syntax is: .. code:: bash @@ -335,28 +315,21 @@ Step 8: Create a DNS record - Optional This step is required only if you are planning to set up multiple `BigchainDB nodes -`_, else you can -skip to the :ref:`next step `. +`_. -Since we currently rely on Azure to provide us with a public IP and manage the -DNS entries of MongoDB instances, we detail only the steps required for ACS -here. - -Select the current Azure resource group and look for the ``Public IP`` +**Azure.** Select the current Azure resource group and look for the ``Public IP`` resource. You should see at least 2 entries there - one for the Kubernetes master and the other for the MongoDB instance. You may have to ``Refresh`` the Azure web page listing the resources in a resource group for the latest changes to be reflected. - Select the ``Public IP`` resource that is attached to your service (it should -have the Kubernetes cluster name alongwith a random string), +have the Kubernetes cluster name along with a random string), select ``Configuration``, add the DNS name that was added in the ConfigMap earlier, click ``Save``, and wait for the changes to be applied. To verify the DNS setting is operational, you can run ``nslookup `` from your local Linux shell. - This will ensure that when you scale the replica set later, other MongoDB members in the replica set can reach this instance. @@ -420,7 +393,7 @@ on the cluster and query the internal DNS and IP endpoints. $ kubectl run -it toolbox -- image --restart=Never --rm It will drop you to the shell prompt. -Now we can query for the ``mdb`` and ``bdb`` service details. +Now you can query for the ``mdb`` and ``bdb`` service details. .. code:: bash