Reorganized docs page re/ config-map.yaml & secret.yaml

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

@@ -1,51 +1,35 @@
-Configure the Node
+How to Configure Your BigchainDB Node
-==================
+=====================================
 
-Use the ConfigMap template in ``configuration/config-map.yaml`` file to
+This page outlines the steps to set a bunch of configuration settings
-configure the node. Update all the values for the keys in the
+in your BigchainDB node.
-ConfigMaps ``vars``, ``bdb-public-key``, ``bdb-keyring`` and
+They are pushed to the Kubernetes cluster in two files,
-``mongodb-whitelist``.
+named ``config-map.yaml`` (a set of ConfigMaps)
+and ``secret.yaml`` (a set of Secrets).
+They are stored in the Kubernetes cluster's key-value store (etcd).
+
+Make sure you did all the things listed in the section titled
+:ref:`Things Each Node Operator Must Do`
+(including generation of all the SSL certificates needed
+for MongoDB auth).
 
 
-Use the Secret template in ``configuration/secret.yaml`` file to configure
+Edit config-map.yaml
-the secrets for this node. Update all the values for the keys in the Secrets
+--------------------
-``mdb-agent-api-key``, ``https-certs``, ``bdb-private-key``,
-``threescale-credentials`` and ``mdb-certs``.
 
-You might not need all the keys during the deployment.
+Make a copy of the file ``k8s/configuration/config-map.yaml``
-For example, if you plan to access the BigchainDB API over HTTP, you might
+and edit the data values in the various ConfigMaps.
-not need the ``https-certs`` Secret.
+That file already contains many comments to help you
+understand each data value, but we make some additional
+remarks on some of the values below.
 
+vars
+~~~~
 
-Ensure that all the secrets are base64 encoded values and the unused ones
+Your BigchainDB cluster organization should have a standard way
-are set to an empty string.
+of naming instances, so the instances in your BigchainDB node
-For example, assuming that the public key chain is named ``cert.pem`` and
+should conform to that standard (i.e. you can't just make up some names).
-private key is ``cert.key``, run the following commands to encode the
+There are some things worth noting about the ``mdb-instance-name``:
-certificates into single continuous string that can be embedded in yaml,
-and then copy the contents of ``cert.pem.b64`` in the ``cert.pem`` field,
-and the contents of ``cert.key.b64`` in the ``cert.key`` field. 
-      
-
-.. code:: bash
-
-    cat cert.pem | base64 -w 0 > cert.pem.b64
-    
-    cat cert.key | base64 -w 0 > cert.key.b64
-
-
-Create the ConfigMap and Secret using the commands:
-
-.. code:: bash
-
-   kubectl --context k8s-bdb-test-cluster-0 apply -f configuration/config-map.yaml
-
-   kubectl --context k8s-bdb-test-cluster-0 apply -f configuration/secret.yaml
-
-
-Some of the Node Configuration Options
---------------------------------------
-
-1. ConfigMap vars.mdb-instance-name
 
 * MongoDB reads the local ``/etc/hosts`` file while bootstrapping a replica
   set to resolve the hostname provided to the ``rs.initiate()`` command.
@@ -57,16 +41,56 @@ Some of the Node Configuration Options
 * This field will also be used by other MongoDB instances when forming a
   MongoDB replica set.
 * We use ``mdb-instance-0``, ``mdb-instance-1`` and so on in our
-    documentation.
+  documentation. Your BigchainDB cluster may use a different naming convention.
 
-2. ConfigMap bdb-keyring.bdb-keyring
+bdb-keyring.bdb-keyring
+~~~~~~~~~~~~~~~~~~~~~~~
 
-  * This value specifies the public keys of all the nodes in a BigchainDB
+This lists the BigchainDB public keys
-    cluster.
+of all *other* nodes in your BigchainDB cluster
-  * It is a ':' separated list, similar to the PATH variables in Unix systems.
+(not including the public key of your BigchainDB node). Cases:
+
+* If you're deploying the first node in the cluster,
+  the value should be ``""`` (an empty string).
+* If you're deploying the second node in the cluster,
+  the value should be one public key inside double quotes
+  (*not* base64-encoded). For example,
+  ``"EPQk5i5yYpoUwGVM8VKZRjM8CYxB6j8Lu8i8SG7kGGce"``
+* If there are two or more other nodes already in the cluster,
+  the value should be a colon-separated list of public keys
+  inside double quotes (with no base64 encoding anywhere).
+  For example,
+  ``"DPjpKbmbPYPKVAuf6VSkqGCf5jzrEh69Ldef6TrLwsEQ:EPQk5i5yYpoUwGVM8VKZRjM8CYxB6j8Lu8i8SG7kGGce"``
 
 
-3. ConfigMap bdb-public-key.bdb-public-key
+Edit secret.yaml
+----------------
 
-  * This value specifies the public key of the current BigchainDB node.
+Make a copy of the file ``k8s/configuration/secret.yaml``
+and edit the data values in the various Secrets.
+That file includes many comments to explain the required values.
+**In particular, note that all values must be base64-encoded.**
+There are tips at the top of the file
+explaining how to convert values into base64-encoded values.
 
+Your BigchainDB node might not need all the Secrets.
+For example, if you plan to access the BigchainDB API over HTTP, you
+don't need the ``https-certs`` Secret.
+You can delete the Secrets you don't need,
+or set their data values to ``""``.
+
+Note that ``ca.pem`` is just another name for ``ca.crt``
+(the certificate of your BigchainDB cluster's self-signed CA).
+
+
+Deploy Your config-map.yaml and secret.yaml
+-------------------------------------------
+
+You can deploy your edited ``config-map.yaml`` and ``secret.yaml``
+files to your Kubernetes cluster using the commands:
+
+.. code:: bash
+
+   $ kubectl apply -f config-map.yaml
+
+   $ kubectl apply -f secret.yaml