From 3f3b2f91b80f7b8252133140e4cb699d7a5b4eab Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Thu, 8 Jun 2017 17:40:43 +0200 Subject: [PATCH] Reorganized docs page re/ config-map.yaml & secret.yaml --- .../node-config-map-and-secrets.rst | 150 ++++++++++-------- 1 file changed, 87 insertions(+), 63 deletions(-) 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 88bfbe31..03f56afe 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 @@ -1,72 +1,96 @@ -Configure the Node -================== +How to Configure Your BigchainDB Node +===================================== -Use the ConfigMap template in ``configuration/config-map.yaml`` file to -configure the node. Update all the values for the keys in the -ConfigMaps ``vars``, ``bdb-public-key``, ``bdb-keyring`` and -``mongodb-whitelist``. +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, +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 -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``. +Edit config-map.yaml +-------------------- -You might not need all the keys during the deployment. -For example, if you plan to access the BigchainDB API over HTTP, you might -not need the ``https-certs`` Secret. - +Make a copy of the file ``k8s/configuration/config-map.yaml`` +and edit the data values in the various ConfigMaps. +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. -Ensure that all the secrets are base64 encoded values and the unused ones -are set to an empty string. -For example, assuming that the public key chain is named ``cert.pem`` and -private key is ``cert.key``, run the following commands to encode the -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. - +vars +~~~~ + +Your BigchainDB cluster organization should have a standard way +of naming instances, so the instances in your BigchainDB node +should conform to that standard (i.e. you can't just make up some names). +There are some things worth noting about the ``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. + It needs to ensure that the replica set is being initialized in the same + instance where the MongoDB instance is running. +* We use the value in the ``mdb-instance-name`` field to achieve this. +* This field will be the DNS name of your MongoDB instance, and Kubernetes + maps this name to its internal DNS. +* 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. Your BigchainDB cluster may use a different naming convention. + +bdb-keyring.bdb-keyring +~~~~~~~~~~~~~~~~~~~~~~~ + +This lists the BigchainDB public keys +of all *other* nodes in your BigchainDB cluster +(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"`` + + +Edit secret.yaml +---------------- + +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 - 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. - It needs to ensure that the replica set is being initialized in the same - instance where the MongoDB instance is running. - * We use the value in the ``mdb-instance-name`` field to achieve this. - * This field will be the DNS name of your MongoDB instance, and Kubernetes - maps this name to its internal DNS. - * 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. - -2. ConfigMap bdb-keyring.bdb-keyring - - * This value specifies the public keys of all the nodes in a BigchainDB - cluster. - * It is a ':' separated list, similar to the PATH variables in Unix systems. - - -3. ConfigMap bdb-public-key.bdb-public-key - - * This value specifies the public key of the current BigchainDB node. + $ kubectl apply -f config-map.yaml + $ kubectl apply -f secret.yaml