Readme file

        Version last updated: 12/01/2022

        Helm chart to install IBM Cloud Block Storage plug-in

        Introduction

        IBM Cloud Block Storage is persistent, high-performance iSCSI storage that you can add to your apps by using Kubernetes persistent volumes (PVs). To create and mount block storage to your app, you must install the IBM Cloud Block Storage plug-in by using a Helm chart. This Helm chart also includes the creation of pre-defined block storage classes that you can use to define the size and IOPS of the block storage device that you want to create.

        For more information about IBM Cloud Block Storage, see Getting started with Block Storage.

        Chart Details

        When you install the IBM Cloud Block Storage plug-in Helm chart, the following Kubernetes resources are deployed into your Kubernetes cluster:

        • IBM Cloud Block Storage driver daemonset: The daemonset deploys one ibmcloud-block-storage-driver pod on every worker node in your cluster. The daemonset contains the Kubernetes flex driver plug-in to communicate with the kubelet component in your cluster.
        • IBM Cloud Block Storage plug-in pod: The pod contains the storage provisioner controllers to work with the Kubernetes controllers.
        • IBM-provided storage classes: You can use the storage classes to create block storage with a specific configuration.
        • Kubernetes service accounts, RBAC cluster roles and cluster role bindings: The service accounts and RBAC roles authorize the plug-in to interact with your Kubernetes resources.

        Prerequisites

        Resources Required

        To install the Helm chart in your cluster, you must have the Administrator platform role.

        PodSecurityPolicy Requirements

        The IBM Cloud Block Storage driver daemonset myst access hostpath volumes to install binaries. To enable access to these volumes, the predefined pod security policy ibm-privileged-psp is used.

        Installing the Chart

        1. Make sure that your worker node applies the latest patch for your minor version.

          1. List the current patch version of your worker nodes.

            ibmcloud ks workers --cluster

            Example output:

            OK
ID                                                  Public IP        Private IP     Machine Type           State    Status   Zone    Version
kube-dal10-crb1a23b456789ac1b20b2nc1e12b345ab-w26   169.xx.xxx.xxx    10.xxx.xx.xxx   b3c.4x16.encrypted      normal   Ready    dal10   1.12.6_1523*

            If your worker node does not apply the latest patch version, you see an asterisk (*) in the Version column of your CLI output.

          2. Review the version changelog to find the changes that are included in the latest patch version.

          3. Apply the latest patch version by reloading your worker node. Follow the instructions in the ibmcloud ks worker-reload command to gracefully reschedule any running pods on your worker node before you reload your worker node. Note that during the reload, your worker node machine is updated with the latest image and data is deleted if not stored outside the worker node.

        2. Follow the instructions to install the Helm client on your local machine, and install the Helm server (Tiller) with a service account in your cluster.

          Note: The installation of the Helm server Tiller requires public network connection to the public Google Container Registry. If your cluster cannot access the public network, such as a private cluster behind a firewall or a cluster with only the private service endpoint enabled, you can choose to pull the Tiller image to your local machine and push the image to your namespace in IBM Cloud Container Registry, or to install the Helm chart without using Tiller.

        3. Verify that Tiller is installed with a service account. If you installed Tiller in a different namespace, such as ibm-services-system, replace kube-system with this namespace.

          kubectl get serviceaccount -n kube-system tiller

          Example output:

          NAME                                 SECRETS   AGE
tiller                               1         2m

        4. Add the IBM Cloud Helm chart repository to the cluster where you want to use the IBM Cloud Block Storage plug-in.

          helm repo add iks-charts https://icr.io/helm/iks-charts

        5. Update the Helm repo to retrieve the latest version of all Helm charts in this repo.

          helm repo update

        6. Install the IBM Cloud Block Storage plug-in. When you install the plug-in, pre-defined block storage classes are added to your cluster.

          helm install iks-charts/ibmcloud-block-storage-plugin

          Example output:

          NAME:   bald-olm
LAST DEPLOYED: Wed Apr 18 10:02:55 2018
NAMESPACE: default
STATUS: DEPLOYED

RESOURCES:
==> v1/DaemonSet
NAME                           DESIRED  CURRENT  READY  UP-TO-DATE  AVAILABLE  NODE SELECTOR  AGE
ibmcloud-block-storage-driver  0        0        0      0           0                   0s

==> v1/Deployment
NAME                           DESIRED  CURRENT  UP-TO-DATE  AVAILABLE  AGE
ibmcloud-block-storage-plugin  1        0        0           0          0s

==> v1/StorageClass
NAME                      PROVISIONER        AGE
ibmc-block-bronze         ibm.io/ibmc-block  0s
ibmc-block-custom         ibm.io/ibmc-block  0s
ibmc-block-gold           ibm.io/ibmc-block  0s
ibmc-block-retain-bronze  ibm.io/ibmc-block  0s
ibmc-block-retain-custom  ibm.io/ibmc-block  0s
ibmc-block-retain-gold    ibm.io/ibmc-block  0s
ibmc-block-retain-silver  ibm.io/ibmc-block  0s
ibmc-block-silver         ibm.io/ibmc-block  0s

==> v1/ServiceAccount
NAME                           SECRETS  AGE
ibmcloud-block-storage-plugin  1        0s

==> v1/ClusterRole
NAME                           AGE
ibmcloud-block-storage-plugin  0s

==> v1/ClusterRoleBinding
NAME                           AGE
ibmcloud-block-storage-plugin  0s

NOTES:
Thank you for installing: ibmcloud-block-storage-plugin.   Your release is named: bald-olm

        7. Verify that the installation was successful.

          kubectl get pod -n kube-system | grep block

          Example output:

          ibmcloud-block-storage-driver-kh4mt                              1/1       Running   0          27d       10.118.98.19   10.118.98.19
ibmcloud-block-storage-plugin-58c5f9dc86-pbl4t                   1/1       Running   0          14d       172.21.0.204   10.118.98.19

          The installation is successful when you see one ibmcloud-block-storage-plugin pod and one or more ibmcloud-block-storage-driver pods. The number of ibmcloud-block-storage-driver pods equals the number of worker nodes in your cluster. All pods must be in a Running state.

        8. Verify that the storage classes for block storage were added to your cluster.

          kubectl get storageclasses | grep block

          Example output:

          ibmc-block-bronze            ibm.io/ibmc-block
ibmc-block-custom            ibm.io/ibmc-block
ibmc-block-gold              ibm.io/ibmc-block
ibmc-block-retain-bronze     ibm.io/ibmc-block
ibmc-block-retain-custom     ibm.io/ibmc-block
ibmc-block-retain-gold       ibm.io/ibmc-block
ibmc-block-retain-silver     ibm.io/ibmc-block
ibmc-block-silver            ibm.io/ibmc-block

        9. Repeat these steps for every cluster where you want to provision block storage.

        Mounting IBM Cloud Block Storage to your pod

        You can provision block storage for your cluster by creating a persistent volume claim (PVC). A PVC is a request for storage that you want to add to your cluster. In your PVC, you include all the details about your storage, such as the size and IOPS.

        When you create your PVC, a persistent volume (PV) is automatically created for you. A persistent volume is a Kubernetes resource that points to an actual storage device on a server. By mounting a PVC to your pod, you mount the PV to your pod and create a mount point that you can use to read from and write to that storage device.

        1. Create a PVC in the default namespace of your cluster. This example uses an example PVC that provisions 20 GB of block storage by using the ibmc-block-bronze storage class. For more information about how to create your own PVC, see Adding block storage to apps.

          1. Create a configuration file for your PVC.
            kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: claim1-block-bronze
  annotations:
    volume.beta.kubernetes.io/storage-class: "ibmc-block-bronze" # name of the storage class
  labels:
    billingType: "monthly" # optional params [hourly | monthly (default)]
spec:
  accessModes:
    - ReadWriteOnce # access mode
  resources:
    requests:
      storage: 20Gi #
          2. Create the PVC in your cluster.
            kubectl apply -f pvc.yaml

        2. Verify that the PVC was created and bound to a PV. This process might take a few minutes to complete.

          kubectl get pvc -n default

          Example output:

          NAME                  STATUS    VOLUME                                     CAPACITY   ACCESSMODES   STORAGECLASS        AGE
claim1-block-bronze   Bound     pvc-a10522a0-ad75-11e7-9741-b21aa31307c7   20Gi       RWO           ibmc-block-bronze   1m

          Your PVC is created successfully when the Status of your PVC shows Bound.

        3. Mount the PVC to a pod. You can use the yaml in this repository to deploy a pod to your cluster that mounts the PVC that you created earlier.

          1. Create a configuration file for your pod.
            apiVersion: v1
kind: Pod
metadata:
  name: pod1-claim1
spec:
  containers:
  - image: rabbitmq 
    name: container-name
    volumeMounts:
    - mountPath: /myvolumepath
      name: pvc-name
  volumes:
  - name: pvc-name
    persistentVolumeClaim:
      claimName: claim1-block-bronze
          2. Create the pod in your cluster.
            kubectl apply -f pod.yaml

        4. Verify that the pod was created successfully.

          kubectl get pod

          Example output:

          NAME          READY     STATUS    RESTARTS   AGE
pod1-claim1   1/1       Running   0          1m

          The creation of your pod is successful when the Status of your pod shows Running.

        5. Log in to the pod.

          kubectl exec -it pod1-claim1 /bin/bash

        6. View the mount path.

          df -h | grep myvolumepath

          Example output:

          /dev/mapper/3600a09803830387574244b316b7a7961   20G   44M   19G   1% /myvolumepath

        7. Navigate to the mount directory.

          cd /myvolumepath/

        8. List all the files in this mount directory.

          ls

          Example output:

          lost+found

        9. Create a new file and write a short text to the file.

          echo "Test write" >> test.txt

        10. Verify that the file was created.

          ls

          Example output:

          lost+found  test.txt

        11. Verify that the file includes your text.

          cat test.txt

          Example output:

          Test write

        12. Exit your pod.

        Configuration

        The helm chart has the following values that you can overwrite by using the install --set parameter. For example:

        helm install --set image.pluginBuild=1.16 iks-charts/ibmcloud-block-storage-plugin
        Value Description Default
        replicaCount Number of provisioner replica to run 1
        image.repository The image repository of provisioner icr.io/ibm/ibmcloud-block-storage-plugin
        image.flexrepository The image repository of driver icr.io/ibm/ibmcloud-block-storage-driver
        image.pluginBuild The provisioner build tag 1.16
        image.driverBuild The driver build tag 1.16
        image.pullPolicy Image Pull Policy Always

        Updating the IBM Cloud Block Storage plug-in on your cluster

        If you want to upgrade your existing IBM Cloud Block Storage plug-in chart to latest version. you can do it as below.

        Before you begin: Log in to your IBM Cloud account. Target the appropriate region and, if applicable, resource group. Set the context for your cluster.

        1. Update the Helm repo to retrieve the latest version of all helm charts in this repo.

          helm repo update

        2. Optional: Download the latest Helm chart to your local machine. Then, extract the package and review the release.md file to find the latest release information.

          helm fetch --untar iks-charts/ibmcloud-block-storage-plugin && cd ibmcloud-block-storage-plugin

        3. Find the name of the block storage Helm chart that you installed in your cluster.

          helm ls | grep ibmcloud-block-storage-plugin

          Example output:

          myhelmchart 	1       	Mon Sep 18 15:31:40 2017	DEPLOYED	ibmcloud-block-storage-plugin-0.1.0	default

        4. Upgrade the IBM Cloud Block Storage plug-in to the latest version.

          helm upgrade --force --recreate-pods   iks-charts/ibmcloud-block-storage-plugin

        5. Optional: When you update the plug-in, the default storage class is unset. If you want to set the default storage class to a storage class of your choice, run the following command.

          kubectl patch storageclass  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

        Removing the IBM Cloud Block Storage plug-in from your cluster

        If you do not want to provision and use IBM Cloud Block Storage for your cluster, you can uninstall the helm chart.

        Important: Removing the plug-in does not remove existing PVCs, PVs, or data. When you remove the plug-in, all the related pods and daemon sets are removed from your cluster. You cannot provision new block storage for your cluster or use existing block storage PVCs and PVs after you remove the plug-in.

        Before you begin:

        To remove the plug-in:

        1. Find the name of the block storage Helm chart that you installed in your cluster.

          helm ls | grep ibmcloud-block-storage-plugin

          Example output:

          myhelmchart 	1       	Mon Sep 18 15:31:40 2017	DEPLOYED	ibmcloud-block-storage-plugin-0.1.0	default

        2. Delete the IBM Cloud Block Storage plug-in.

          helm delete

        3. Verify that the block storage pods are removed.

          kubectl get pod -n kube-system | grep ibmcloud-block-storage-plugin

          The removal of the pods is successful if no pods are displayed in your CLI output.

        4. Verify that the block storage storage classes are removed.

          kubectl get storageclasses | grep block

          The removal of the storage classes is successful if no storage classes are displayed in your CLI output.

        Limitations

        • This chart can run only on an amd64 architecture type.