The Container Storage Interface (CSI) Driver for Linode Block Storage enables container orchestrators such as Kubernetes to manage the life-cycle of persistent storage claims.
More information about the Kubernetes CSI can be found in the GitHub Kubernetes CSI and CSI Spec repositories.
There are two ways of deploying CSI.
The recommended way is to use Helm.
The second way is to use manually set secrets on the kubernetes cluster then use
kubectl to deploy using the given yaml
file.
Generate a Personal Access Token (PAT) using the Linode Cloud Manager.
This token will need:
LINODE_API_TOKEN
must be a Linode APIv4 Personal Access
Token with Volume and Linode
permissions.
REGION
must be a Linode region.
helm repo add linode-csi https://linode.github.io/linode-blockstorage-csi-driver/
helm repo update linode-csi
export LINODE_API_TOKEN="...your Linode API token..."
export REGION="your preferred region"
helm install linode-csi-driver \
--set apiToken="${LINODE_API_TOKEN}" \
--set region="${REGION}" \
linode-csi/linode-blockstorage-csi-driver
_See helm install for command documentation._
To uninstall the linode-blockstorage-csi-driver from your cluster, run the following command:
helm uninstall linode-csi-driver
_See helm uninstall for command documentation._
To upgrade when new changes are made to the helm chart, run the following command:
export LINODE_API_TOKEN="...your Linode API token..."
export REGION="your preferred region"
helm upgrade linode-csi-driver \
--install \
--set apiToken="${LINODE_API_TOKEN}" \
--set region="${REGION}" \
linode-csi/linode-blockstorage-csi-driver
_See helm upgrade for command documentation._
There are other variables that can be set to a different value. For list of all the modifiable variables/values, see helm-chart/csi-driver/values.yaml.
Values can be set/overrided by using the '--set var=value,...' flag or by passing in a custom-values.yaml using '-f custom-values.yaml'.
Recommendation: Use a custom values.yaml
file to override the variables to
avoid any errors with template rendering.
Create the following secret:
apiVersion: v1
kind: Secret
metadata:
name: linode
namespace: kube-system
stringData:
token: "your linode api token"
region: "your preferred region"
then apply it with
kubectl apply -f secret.yaml
You should receive notification that the secret was created. You can confirm this by running:
$ kubectl -n kube-system get secret/linode
NAME TYPE DATA AGE
linode Opaque 2 2m
The following command will deploy the latest version of the CSI driver with all related Kubernetes volume attachment, driver registration, and provisioning sidecars:
kubectl apply -f https://raw.githubusercontent.com/linode/linode-blockstorage-csi-driver/master/pkg/linode-bs/deploy/releases/linode-blockstorage-csi-driver.yaml
If you need a specific release of the CSI driver you can specify the release version in the URL like the following:
kubectl apply -f https://raw.githubusercontent.com/linode/linode-blockstorage-csi-driver/master/pkg/linode-bs/deploy/releases/linode-blockstorage-csi-driver-v0.5.3.yaml
This deployment is a concatenation of all of the yaml
files in
pkg/linode-bs/deploy/kubernetes/.
Notably, this deployment will:
Set the default storage class to linode-block-storage-retain
Learn
More
This behavior can be modified in the
csi-storageclass.yaml
section of the deployment by toggling the
storageclass.kubernetes.io/is-default-class
annotation.
$ kubectl get storageclasses
NAME PROVISIONER AGE
linode-block-storage-retain (default) linodebs.csi.linode.com 2d
linode-block-storage linodebs.csi.linode.com 2d
Use a reclaimPolicy
of Retain
Learn
More
Volumes created by this CSI driver will default to using the
linode-block-storage-retain
storage class if one is not specified.
Upon deletion of all PersitentVolumeClaims, the PersistentVolume and its
backing Block Storage Volume will remain intact.
Assume that the Linode CCM is initialized and running Learn More
If you absolutely intend to run this on a cluster which will not run the
Linode CCM, you must modify the init container script located in the
08-cm-get-linode-id.yaml
ConfigMap and delete the
line
that contains the exit 1
.
This repository contains two
manifests
that demonstrate use of the Linode BlockStorage CSI.
These manifests will create a PersistentVolume Claim using the
linode-block-storage-retain
storage class and then consume it in a minimal
pod.
Once you have installed the Linode BlockStorage CSI, the following commands will
run the example.
Once you are finished with the example, please be sure to delete the pod, PVC,
and the associated Block Storage Volume.
The PVC created in this example uses the linode-block-storage-retain
storage
class, so you will need to remove the Block Storage Volume from your Linode
account via the Cloud Manager or the Linode CLI.
kubectl create -f https://raw.githubusercontent.com/linode/linode-blockstorage-csi-driver/master/pkg/linode-bs/examples/kubernetes/csi-pvc.yaml
kubectl create -f https://raw.githubusercontent.com/linode/linode-blockstorage-csi-driver/master/pkg/linode-bs/examples/kubernetes/csi-app.yaml
Verify that the pod is running and can consume the volume:
kubectl get pvc/csi-example-pvc pods/csi-example-pod
kubectl describe pvc/csi-example-pvc pods/csi-example-pod
Now, let's add some data into the PVC, and delete and recreate the pod. Our data will remain intact.
First, we will write some data to a file in the PVC:
$ kubectl exec -it csi-example-pod -- /bin/sh -c "echo persistence > /data/example.txt; ls -l /data"
total 20
-rw-r--r-- 1 root root 12 Dec 5 13:06 example.txt
drwx------ 2 root root 16384 Dec 5 06:03 lost+found
Then we will delete and recreate the pod, and check to make sure our data is still there:
$ kubectl delete pods/csi-example-pod
pod "csi-example-pod" deleted
$ kubectl create -f https://raw.githubusercontent.com/linode/linode-blockstorage-csi-driver/master/pkg/linode-bs/examples/kubernetes/csi-app.yaml
pod/csi-example-pod created
$ sleep 30; kubectl exec -it csi-example-pod -- /bin/sh -c "ls -l /data; cat /data/example.txt"
total 20
-rw-r--r-- 1 root root 12 Dec 5 13:06 example.txt
drwx------ 2 root root 16384 Dec 5 06:03 lost+found
persistence
The ability to encrypt a PVC with a user owned secret provides an additional security layer that gives control of the data to the cluster owner instead of the platform provider.
[!TIP] To use an encryption key per PVC you can make a new StorageClass/Secret combination each time.
allowVolumeExpansion: true
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
annotations:
storageclass.kubernetes.io/is-default-class: "true"
name: linode-block-storage-retain-luks
namespace: kube-system
provisioner: linodebs.csi.linode.com
reclaimPolicy: Retain
parameters:
linodebs.csi.linode.com/luks-encrypted: "true"
linodebs.csi.linode.com/luks-cipher: "aes-xts-plain64"
linodebs.csi.linode.com/luks-key-size: "512"
csi.storage.k8s.io/node-stage-secret-namespace: csi-encrypt-example
csi.storage.k8s.io/node-stage-secret-name: csi-encrypt-example-luks-key
---
apiVersion: v1
kind: Secret
metadata:
name: csi-encrypt-example-luks-key
namespace: csi-encrypt-example
stringData:
luksKey: "SECRETGOESHERE"
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: csi-example-pvc
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
storageClassName: linode-block-storage-retain
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: csi-example-pvcluks
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
storageClassName: linode-block-storage-retain-luks
This feature gives users the ability to add tags to volumes created by a
specific storageClass, to allow for better tracking of volumes.
Tags are added as a comma seperated string value for a parameter
linodebs.csi.linode.com/volumeTags
allowVolumeExpansion: true
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
annotations:
storageclass.kubernetes.io/is-default-class: "true"
name: linode-block-storage
namespace: kube-system
provisioner: linodebs.csi.linode.com
parameters:
linodebs.csi.linode.com/volumeTags: "test, foo, yolo"
require_size
less than the Linode
minimum Block Storage size will be fulfilled with a Linode Block Storage volume
of the minimum size (currently 10Gi
).
This is in accordance with the CSI
specification.
The upper-limit size constraint (limit_bytes
) will also be honored so the
size of Linode Block Storage volumes provisioned will not exceed this
parameter.Want to improve the linode-blockstorage-csi-driver? Please start here.
For general help or discussion, join the Kubernetes Slack channel #linode.
For development and debugging, join the Gopher's Slack channel #linodego.