Readme file
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
- Create or use an existing standard Kubernetes cluster that you provisioned with IBM Cloud Kubernetes Service.
- Install the IBM Cloud CLI, the IBM Cloud Kubernetes Service plug-in, the Kubernetes CLI.
- Log in to your IBM Cloud account. Target the appropriate region and, if applicable, resource group. Set the context for your cluster.
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
-
Make sure that your worker node applies the latest patch for your minor version.
-
List the current patch version of your worker nodes.
Example output:
If your worker node does not apply the latest patch version, you see an asterisk (*) in the Version column of your CLI output.
-
Review the version changelog to find the changes that are included in the latest patch version.
-
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.
-
-
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.
-
Verify that Tiller is installed with a service account. If you installed Tiller in a different namespace, such as
ibm-services-system
, replacekube-system
with this namespace.Example output:
-
Add the IBM Cloud Helm chart repository to the cluster where you want to use the IBM Cloud Block Storage plug-in.
-
Update the Helm repo to retrieve the latest version of all Helm charts in this repo.
-
Install the IBM Cloud Block Storage plug-in. When you install the plug-in, pre-defined block storage classes are added to your cluster.
Example output:
-
Verify that the installation was successful.
Example output:
The installation is successful when you see one
ibmcloud-block-storage-plugin
pod and one or moreibmcloud-block-storage-driver
pods. The number ofibmcloud-block-storage-driver
pods equals the number of worker nodes in your cluster. All pods must be in a Running state. -
Verify that the storage classes for block storage were added to your cluster.
Example output:
-
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.
-
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.- Create a configuration file for your PVC.
- Create the PVC in your cluster.
-
Verify that the PVC was created and bound to a PV. This process might take a few minutes to complete.
Example output:
Your PVC is created successfully when the Status of your PVC shows Bound.
-
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.
- Create a configuration file for your pod.
- Create the pod in your cluster.
-
Verify that the pod was created successfully.
Example output:
The creation of your pod is successful when the Status of your pod shows Running.
-
Log in to the pod.
-
View the mount path.
Example output:
-
Navigate to the mount directory.
-
List all the files in this mount directory.
Example output:
-
Create a new file and write a short text to the file.
-
Verify that the file was created.
Example output:
-
Verify that the file includes your text.
Example output:
-
Exit your pod.
Configuration
The helm chart has the following values that you can overwrite by using the install --set
parameter. For example:
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.
-
Update the Helm repo to retrieve the latest version of all helm charts in this repo.
-
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. -
Find the name of the block storage Helm chart that you installed in your cluster.
Example output:
-
Upgrade the IBM Cloud Block Storage plug-in to the latest version.
-
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.
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:
- Log in to your IBM Cloud account. Target the appropriate region and, if applicable, resource group. Set the context for your cluster.
- Make sure that you do not have any PVCs or PVs in your cluster that use block storage.
To remove the plug-in:
-
Find the name of the block storage Helm chart that you installed in your cluster.
Example output:
-
Delete the IBM Cloud Block Storage plug-in.
-
Verify that the block storage pods are removed.
The removal of the pods is successful if no pods are displayed in your CLI output.
-
Verify that the block storage storage classes are removed.
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.