From f2f1ee8ef109131c92078016bd3d321a19d13371 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Tue, 28 Feb 2017 19:08:13 +0100 Subject: [PATCH 1/4] docs: create k8s StorageClass & PVC --- .../node-on-kubernetes.rst | 116 ++++++++++++++++-- 1 file changed, 109 insertions(+), 7 deletions(-) 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 03ffb2fe..9ae16675 100644 --- a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst +++ b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst @@ -21,7 +21,7 @@ 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 +**Azure.** If you deployed your Kubernetes cluster on Azure using the Azure CLI 2.0 (as per :doc:`our template `), then you can get the ``~/.kube/config`` file using: @@ -32,15 +32,117 @@ then you can get the ``~/.kube/config`` file using: --name -Step 3: Run a MongoDB Container -------------------------------- +Step 3: Create a StorageClass +----------------------------- -To start a MongoDB Docker container in a pod on one of the cluster nodes: +MongoDB needs somewhere to store its data persistently, +outside the container where MongoDB is running. +Explaining how Kubernetes handles persistent volumes, +and the associated terminology, +is beyond the scope of this documentation; +see `the Kubernetes docs about persistent volumes +`_. + +The first thing to do is create a Kubernetes StorageClass. + +**Azure.** First, you need an Azure storage account. +While you might be able to use an existing one, +create a new one specifically for MongoDB data: .. code:: bash - $ kubectl ????? + $ az storage account create --name \ + --resource-group \ + --location \ + --sku Standard_LRS + +where LRS means locally-redundant storage. Other option-values (and other options) can be found in `the docs for az storage account create `_. + +Next, create a Kubernetes Storage Class named ``slow`` +by writing a file named ``azureStorageClass.yml`` containing: + +.. code:: yaml + + kind: StorageClass + apiVersion: storage.k8s.io/v1beta1 + metadata: + name: slow + provisioner: kubernetes.io/azure-disk + parameters: + skuName: Standard_LRS + location: + +and then: + +.. code:: bash + + $ kubectl apply -f azureStorageClass.yml + +You can check if it worked using ``kubectl get storageclasses``. + +Note that there is no line of the form +``storageAccount: `` +under ``parameters:``. When we included one +and then created a PersistentVolumeClaim based on it, +the PersistentVolumeClaim would get stuck +in a "Pending" state. -Note: The BigchainDB Dashboard can be deployed -as a Docker container, like everything else. +Step 4: Create a PersistentVolumeClaim +-------------------------------------- + +Next, you'll create a PersistentVolumeClaim named ``mongoclaim``. +Create a file named ``mongoclaim.yml`` +with the following contents: + +.. code:: yaml + + kind: PersistentVolumeClaim + apiVersion: v1 + metadata: + name: mongoclaim + annotations: + volume.beta.kubernetes.io/storage-class: slow + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi + +Note how there's no explicit depencency on the storage provider. +``ReadWriteOnce`` (RWO) means the volume can be mounted as +read-write by a single Kubernetes node. +(``ReadWriteOnce`` is the *only* access mode supported +by AzureDisk.) +``storage: 2Gi`` means the volume has a size of two +`gibibytes `_. +(You can change that if you like.) + +Create ``mongoclaim`` in your Kubernetes cluster: + +.. code:: bash + + $ kubectl apply -f mongoclaim.yml + +You can check its status using: + +.. code:: bash + + $ kubectl get pvc + +Initially, the status of ``mongoclaim`` might be "Pending" +but it should become "Bound" fairly quickly. + +.. code:: bash + + $ kubectl describe pvc + Name: mongoclaim + Namespace: default + StorageClass: slow + Status: Bound + Volume: pvc-ebed81f1-fdca-11e6-abf0-000d3a27ab21 + Labels: + Capacity: 2Gi + Access Modes: RWO + No events. From 35ee6e55398062f3fa365c9e3d9830c91e3c4ffe Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Wed, 1 Mar 2017 13:35:31 +0100 Subject: [PATCH 2/4] docs: add instructions to update az command --- .../template-kubernetes-azure.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst b/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst index 0758912d..0fe8c378 100644 --- a/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst +++ b/docs/server/source/cloud-deployment-templates/template-kubernetes-azure.rst @@ -45,6 +45,12 @@ on most common operating systems `_. Do that. +First, update the Azure CLI to the latest version: + +.. code:: bash + + $ az component update + Next, login to your account using: .. code:: bash From 77c6b138a82491b538945a8b0115c6cb41585804 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Wed, 1 Mar 2017 15:49:20 +0100 Subject: [PATCH 3/4] expanded docs re/ Azure storage accounts & ACS --- .../node-on-kubernetes.rst | 35 ++++++++++++------- 1 file changed, 23 insertions(+), 12 deletions(-) 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 9ae16675..f64b8207 100644 --- a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst +++ b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst @@ -46,19 +46,28 @@ see `the Kubernetes docs about persistent volumes The first thing to do is create a Kubernetes StorageClass. **Azure.** First, you need an Azure storage account. -While you might be able to use an existing one, -create a new one specifically for MongoDB data: +If you deployed your Kubernetes cluster on Azure +using the Azure CLI 2.0 +(as per :doc:`our template `), +then the `az acs create` command already created two +storage accounts in the same location and resource group +as your Kubernetes cluster. +Both should have the same "storage account SKU": ``Standard_LRS``. +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. -.. code:: bash +Premium storage is higher-cost and higher-performance. +It uses solid state drives (SSD). +At the time of writing, +when we created a storage account with SKU ``Premium_LRS`` +and tried to use that, +the PersistentVolumeClaim would get stuck in a "Pending" state. +For future reference, the command to create a storage account is +`az storage account create `_. - $ az storage account create --name \ - --resource-group \ - --location \ - --sku Standard_LRS - -where LRS means locally-redundant storage. Other option-values (and other options) can be found in `the docs for az storage account create `_. - -Next, create a Kubernetes Storage Class named ``slow`` +Create a Kubernetes Storage Class named ``slow`` by writing a file named ``azureStorageClass.yml`` containing: .. code:: yaml @@ -86,6 +95,8 @@ under ``parameters:``. When we included one and then created a PersistentVolumeClaim based on it, the PersistentVolumeClaim would get stuck in a "Pending" state. +Kubernetes just looks for a storageAccount +with the specified skuName and location. Step 4: Create a PersistentVolumeClaim @@ -110,7 +121,7 @@ with the following contents: requests: storage: 2Gi -Note how there's no explicit depencency on the storage provider. +Note how there's no explicit mention of Azure, AWS or whatever. ``ReadWriteOnce`` (RWO) means the volume can be mounted as read-write by a single Kubernetes node. (``ReadWriteOnce`` is the *only* access mode supported From 4e32a492b16e9ec838631fbb88315481d9c72049 Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Wed, 1 Mar 2017 16:26:57 +0100 Subject: [PATCH 4/4] docs: changed PersistentVolumeClaim from 2Gi to 20Gi --- .../source/cloud-deployment-templates/node-on-kubernetes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 f64b8207..afb0b438 100644 --- a/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst +++ b/docs/server/source/cloud-deployment-templates/node-on-kubernetes.rst @@ -119,14 +119,14 @@ with the following contents: - ReadWriteOnce resources: requests: - storage: 2Gi + storage: 20Gi Note how there's no explicit mention of Azure, AWS or whatever. ``ReadWriteOnce`` (RWO) means the volume can be mounted as read-write by a single Kubernetes node. (``ReadWriteOnce`` is the *only* access mode supported by AzureDisk.) -``storage: 2Gi`` means the volume has a size of two +``storage: 20Gi`` means the volume has a size of 20 `gibibytes `_. (You can change that if you like.)