From 9b4273a98719adee75a7613c3e2be94b0df56b8d Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Tue, 7 Aug 2018 13:20:47 +0200 Subject: [PATCH] Problem: Docs: 'Production Deployment Template' not a good name anymore (#2440) Solution: Rename that section to 'Kubernetes Deployment Template' --- .../source/appendices/all-in-one-bigchaindb.md | 2 +- docs/server/source/clusters.md | 10 ---------- docs/server/source/index.rst | 2 +- .../architecture.rst | 0 .../bigchaindb-network-on-kubernetes.rst | 0 .../ca-installation.rst | 0 .../client-tls-certificate.rst | 0 .../cloud-manager.rst | 2 +- .../easy-rsa.rst | 0 .../index.rst | 4 ++-- .../log-analytics.rst | 0 .../node-config-map-and-secrets.rst | 0 .../node-on-kubernetes.rst | 12 ++++++------ .../revoke-tls-certificate.rst | 0 .../server-tls-certificate.rst | 0 .../tectonic-azure.rst | 0 .../template-kubernetes-azure.rst | 0 .../troubleshoot.rst | 0 .../upgrade-on-kubernetes.rst | 0 .../workflow.rst | 6 +++--- 20 files changed, 14 insertions(+), 24 deletions(-) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/architecture.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/bigchaindb-network-on-kubernetes.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/ca-installation.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/client-tls-certificate.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/cloud-manager.rst (96%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/easy-rsa.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/index.rst (90%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/log-analytics.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/node-config-map-and-secrets.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/node-on-kubernetes.rst (98%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/revoke-tls-certificate.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/server-tls-certificate.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/tectonic-azure.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/template-kubernetes-azure.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/troubleshoot.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/upgrade-on-kubernetes.rst (100%) rename docs/server/source/{production-deployment-template => k8s-deployment-template}/workflow.rst (96%) diff --git a/docs/server/source/appendices/all-in-one-bigchaindb.md b/docs/server/source/appendices/all-in-one-bigchaindb.md index 601da89e..246b4e50 100644 --- a/docs/server/source/appendices/all-in-one-bigchaindb.md +++ b/docs/server/source/appendices/all-in-one-bigchaindb.md @@ -15,7 +15,7 @@ This image contains all the services required for a BigchainDB node i.e. *This image is to help quick deployment for early adopters, for a more standard approach please refer to one of our deployment guides:* - [BigchainDB developer setup guides](https://docs.bigchaindb.com/projects/contributing/en/latest/dev-setup-coding-and-contribution-process/index.html). -- [BigchainDB with Kubernetes](http://docs.bigchaindb.com/projects/server/en/latest/production-deployment-template/index.html). +- [BigchainDB with Kubernetes](http://docs.bigchaindb.com/projects/server/en/latest/k8s-deployment-template/index.html). ## Prerequisite(s) - [Docker](https://docs.docker.com/engine/installation/) diff --git a/docs/server/source/clusters.md b/docs/server/source/clusters.md index be1d1c9c..23cbf1f3 100644 --- a/docs/server/source/clusters.md +++ b/docs/server/source/clusters.md @@ -2,7 +2,6 @@ A **BigchainDB Cluster** is a set of connected **BigchainDB Nodes**, managed by a **BigchainDB Consortium** (i.e. an organization). Those terms are defined in the [BigchainDB Terminology page](https://docs.bigchaindb.com/en/latest/terminology.html). - ## Consortium Structure & Governance The consortium might be a company, a foundation, a cooperative, or [some other form of organization](https://en.wikipedia.org/wiki/Organizational_structure). @@ -13,13 +12,6 @@ This documentation doesn't explain how to create a consortium, nor does it outli It's worth noting that the decentralization of a BigchainDB cluster depends, to some extent, on the decentralization of the associated consortium. See the pages about [decentralization](https://docs.bigchaindb.com/en/latest/decentralized.html) and [node diversity](https://docs.bigchaindb.com/en/latest/diversity.html). - -## Relevant Technical Documentation - -Anyone building or managing a BigchainDB cluster may be interested -in [our production deployment template](production-deployment-template/index.html). - - ## Cluster DNS Records and SSL Certificates We now describe how *we* set up the external (public-facing) DNS records for a BigchainDB cluster. Your consortium may opt to do it differently. @@ -30,14 +22,12 @@ There were several goals: * There should be no sharing of SSL certificates among BigchainDB node operators. * Optional: Allow clients to connect to a "random" BigchainDB node in the cluster at one particular domain (or subdomain). - ### Node Operator Responsibilities 1. Register a domain (or use one that you already have) for your BigchainDB node. You can use a subdomain if you like. For example, you might opt to use `abc-org73.net`, `api.dynabob8.io` or `figmentdb3.ninja`. 2. Get an SSL certificate for your domain or subdomain, and properly install it in your node (e.g. in your NGINX instance). 3. Create a DNS A Record mapping your domain or subdomain to the public IP address of your node (i.e. the one that serves the BigchainDB HTTP API). - ### Consortium Responsibilities Optional: The consortium managing the BigchainDB cluster could register a domain name and set up CNAME records mapping that domain name (or one of its subdomains) to each of the nodes in the cluster. For example, if the consortium registered `bdbcluster.io`, they could set up CNAME records like the following: diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst index c8f16d02..be9d1a10 100644 --- a/docs/server/source/index.rst +++ b/docs/server/source/index.rst @@ -10,13 +10,13 @@ BigchainDB Server Documentation simple-network-setup production-nodes/index clusters - production-deployment-template/index dev-and-test/index server-reference/index http-client-server-api events/index drivers-clients/index data-models/index + k8s-deployment-template/index release-notes glossary appendices/index diff --git a/docs/server/source/production-deployment-template/architecture.rst b/docs/server/source/k8s-deployment-template/architecture.rst similarity index 100% rename from docs/server/source/production-deployment-template/architecture.rst rename to docs/server/source/k8s-deployment-template/architecture.rst diff --git a/docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst b/docs/server/source/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst similarity index 100% rename from docs/server/source/production-deployment-template/bigchaindb-network-on-kubernetes.rst rename to docs/server/source/k8s-deployment-template/bigchaindb-network-on-kubernetes.rst diff --git a/docs/server/source/production-deployment-template/ca-installation.rst b/docs/server/source/k8s-deployment-template/ca-installation.rst similarity index 100% rename from docs/server/source/production-deployment-template/ca-installation.rst rename to docs/server/source/k8s-deployment-template/ca-installation.rst diff --git a/docs/server/source/production-deployment-template/client-tls-certificate.rst b/docs/server/source/k8s-deployment-template/client-tls-certificate.rst similarity index 100% rename from docs/server/source/production-deployment-template/client-tls-certificate.rst rename to docs/server/source/k8s-deployment-template/client-tls-certificate.rst diff --git a/docs/server/source/production-deployment-template/cloud-manager.rst b/docs/server/source/k8s-deployment-template/cloud-manager.rst similarity index 96% rename from docs/server/source/production-deployment-template/cloud-manager.rst rename to docs/server/source/k8s-deployment-template/cloud-manager.rst index fb0512df..458a8eeb 100644 --- a/docs/server/source/production-deployment-template/cloud-manager.rst +++ b/docs/server/source/k8s-deployment-template/cloud-manager.rst @@ -41,7 +41,7 @@ Configure MongoDB Cloud Manager for Monitoring * If you have authentication enabled, select the option to enable authentication and specify the authentication mechanism as per your - deployment. The default BigchainDB production deployment currently + deployment. The default BigchainDB Kubernetes deployment template currently supports ``X.509 Client Certificate`` as the authentication mechanism. * If you have TLS enabled, select the option to enable TLS/SSL for MongoDB diff --git a/docs/server/source/production-deployment-template/easy-rsa.rst b/docs/server/source/k8s-deployment-template/easy-rsa.rst similarity index 100% rename from docs/server/source/production-deployment-template/easy-rsa.rst rename to docs/server/source/k8s-deployment-template/easy-rsa.rst diff --git a/docs/server/source/production-deployment-template/index.rst b/docs/server/source/k8s-deployment-template/index.rst similarity index 90% rename from docs/server/source/production-deployment-template/index.rst rename to docs/server/source/k8s-deployment-template/index.rst index fa9d64c1..44a3fc07 100644 --- a/docs/server/source/production-deployment-template/index.rst +++ b/docs/server/source/k8s-deployment-template/index.rst @@ -1,4 +1,4 @@ -Production Deployment Template +Kubernetes Deployment Template ============================== .. note:: @@ -12,7 +12,7 @@ Production Deployment Template 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) +This section outlines a way to deploy a 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*. diff --git a/docs/server/source/production-deployment-template/log-analytics.rst b/docs/server/source/k8s-deployment-template/log-analytics.rst similarity index 100% rename from docs/server/source/production-deployment-template/log-analytics.rst rename to docs/server/source/k8s-deployment-template/log-analytics.rst diff --git a/docs/server/source/production-deployment-template/node-config-map-and-secrets.rst b/docs/server/source/k8s-deployment-template/node-config-map-and-secrets.rst similarity index 100% rename from docs/server/source/production-deployment-template/node-config-map-and-secrets.rst rename to docs/server/source/k8s-deployment-template/node-config-map-and-secrets.rst diff --git a/docs/server/source/production-deployment-template/node-on-kubernetes.rst b/docs/server/source/k8s-deployment-template/node-on-kubernetes.rst similarity index 98% rename from docs/server/source/production-deployment-template/node-on-kubernetes.rst rename to docs/server/source/k8s-deployment-template/node-on-kubernetes.rst index 96f4098a..e9032ec4 100644 --- a/docs/server/source/production-deployment-template/node-on-kubernetes.rst +++ b/docs/server/source/k8s-deployment-template/node-on-kubernetes.rst @@ -40,7 +40,7 @@ If you don't have that file, then you need to get it. **Azure.** If you deployed your Kubernetes cluster on Azure using the Azure CLI 2.0 (as per :doc:`our template -<../production-deployment-template/template-kubernetes-azure>`), +<../k8s-deployment-template/template-kubernetes-azure>`), then you can get the ``~/.kube/config`` file using: .. code:: bash @@ -288,7 +288,7 @@ The first thing to do is create the Kubernetes storage classes. First, you need an Azure storage account. If you deployed your Kubernetes cluster on Azure using the Azure CLI 2.0 -(as per :doc:`our template <../production-deployment-template/template-kubernetes-azure>`), +(as per :doc:`our template <../k8s-deployment-template/template-kubernetes-azure>`), then the `az acs create` command already created a storage account in the same location and resource group as your Kubernetes cluster. @@ -300,7 +300,7 @@ in the same data center. Premium storage is higher-cost and higher-performance. It uses solid state drives (SSD). -We recommend using Premium storage for our production template. +We recommend using Premium storage with our Kubernetes deployment template. Create a `storage account `_ for Premium storage and associate it with your Azure resource group. For future reference, the command to create a storage account is @@ -383,7 +383,7 @@ but it should become "Bound" fairly quickly. $ kubectl patch pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' For notes on recreating a private volume form a released Azure disk resource consult - :doc:`the page about cluster troubleshooting <../production-deployment-template/troubleshoot>`. + :doc:`the page about cluster troubleshooting <../k8s-deployment-template/troubleshoot>`. .. _start-kubernetes-stateful-set-mongodb: @@ -580,7 +580,7 @@ Step 19(Optional): Configure the MongoDB Cloud Manager ------------------------------------------------------ Refer to the -:doc:`documentation <../production-deployment-template/cloud-manager>` +:doc:`documentation <../k8s-deployment-template/cloud-manager>` for details on how to configure the MongoDB Cloud Manager to enable monitoring and backup. @@ -760,4 +760,4 @@ verify that your node or cluster works as expected. Next, you can set up log analytics and monitoring, by following our templates: -* :doc:`../production-deployment-template/log-analytics`. +* :doc:`../k8s-deployment-template/log-analytics`. diff --git a/docs/server/source/production-deployment-template/revoke-tls-certificate.rst b/docs/server/source/k8s-deployment-template/revoke-tls-certificate.rst similarity index 100% rename from docs/server/source/production-deployment-template/revoke-tls-certificate.rst rename to docs/server/source/k8s-deployment-template/revoke-tls-certificate.rst diff --git a/docs/server/source/production-deployment-template/server-tls-certificate.rst b/docs/server/source/k8s-deployment-template/server-tls-certificate.rst similarity index 100% rename from docs/server/source/production-deployment-template/server-tls-certificate.rst rename to docs/server/source/k8s-deployment-template/server-tls-certificate.rst diff --git a/docs/server/source/production-deployment-template/tectonic-azure.rst b/docs/server/source/k8s-deployment-template/tectonic-azure.rst similarity index 100% rename from docs/server/source/production-deployment-template/tectonic-azure.rst rename to docs/server/source/k8s-deployment-template/tectonic-azure.rst diff --git a/docs/server/source/production-deployment-template/template-kubernetes-azure.rst b/docs/server/source/k8s-deployment-template/template-kubernetes-azure.rst similarity index 100% rename from docs/server/source/production-deployment-template/template-kubernetes-azure.rst rename to docs/server/source/k8s-deployment-template/template-kubernetes-azure.rst diff --git a/docs/server/source/production-deployment-template/troubleshoot.rst b/docs/server/source/k8s-deployment-template/troubleshoot.rst similarity index 100% rename from docs/server/source/production-deployment-template/troubleshoot.rst rename to docs/server/source/k8s-deployment-template/troubleshoot.rst diff --git a/docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst b/docs/server/source/k8s-deployment-template/upgrade-on-kubernetes.rst similarity index 100% rename from docs/server/source/production-deployment-template/upgrade-on-kubernetes.rst rename to docs/server/source/k8s-deployment-template/upgrade-on-kubernetes.rst diff --git a/docs/server/source/production-deployment-template/workflow.rst b/docs/server/source/k8s-deployment-template/workflow.rst similarity index 96% rename from docs/server/source/production-deployment-template/workflow.rst rename to docs/server/source/k8s-deployment-template/workflow.rst index 793175b9..668f1a3c 100644 --- a/docs/server/source/production-deployment-template/workflow.rst +++ b/docs/server/source/k8s-deployment-template/workflow.rst @@ -15,7 +15,7 @@ Overview then this Kubernetes deployment template might be helpful. This page summarizes some steps to go through -to set up a production BigchainDB cluster. +to set up a BigchainDB cluster. You can modify them to suit your needs. .. _generate-the-blockchain-id-and-genesis-time: @@ -123,13 +123,13 @@ and set it equal to your secret token, e.g. 3. Deploy a Kubernetes cluster for your BigchainDB node. We have some instructions for how to -:doc:`Deploy a Kubernetes cluster on Azure <../production-deployment-template/template-kubernetes-azure>`. +:doc:`Deploy a Kubernetes cluster on Azure <../k8s-deployment-template/template-kubernetes-azure>`. .. warning:: In theory, you can deploy your BigchainDB node to any Kubernetes cluster, but there can be differences between different Kubernetes clusters, especially if they are running different versions of Kubernetes. - We tested this Production Deployment Template on Azure ACS in February 2018 and at that time + We tested this Kubernetes Deployment Template on Azure ACS in February 2018 and at that time ACS was deploying a **Kubernetes 1.7.7** cluster. If you can force your cluster to have that version of Kubernetes, then you'll increase the likelihood that everything will work in your cluster.