Jon's Blog

Category: Homelab

All things homelab.

  • The Curious Case of the Synology CSI

    Recently, I’ve been spending a good chunk of time getting up to speed on all things Kubernetes. This includes use cases in the homelab. As I just so happen to have a Synology DS923+ as my primary NAS device, I decided I’d dig into the Synology CSI and see what options that it presented to me with my Kubernetes cluster.

    In the beginning…

    First things first, you need to snag the open-source CSI installer from Synology’s GitHub page. It’s available here.

    Easy enough, it’s a simple git clone operation and configuring a few files. Let’s start with the first file…

    Navigate into the synology-csi/config folder. There should exist a template for the file you need to create. Make a copy of the client-info-template.yml file and call it client-info.yml. Edit the file so that it looks a little something like this:

    ---
clients:
  - host: 192.168.1.1 <Your DSM IP Address>
    port: 5001 <Your DSM port>
    https: true
    username: <Your DSM Username>
    password: <Your DSM password>

    The installer will create a Kubernetes Secret out of this file to contain the proper information for connecting to your Synology device.

    Let’s change directories for a moment and edit another configuration file that is very important to the CSI installer. Navigate to the synology-csi/deploy/kubernetes/v1.20 directory. In this directory, you’ll see a storage-class.yml file. By default, this file configures your CSI installer to register a storage class using iSCSI on the Synology NAS. In my use case, I decided to work with iSCSI, but there are other options that you can configure, or even other storage classes you can register by making a copy of this file and editing it. Let’s take a look at my configured file:

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: synology-iscsi-storage
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: csi.san.synology.com
parameters:
   dsm: '192.168.1.1'
   location: '/volume1'
   fsType: 'ext4'
     # formatOptions: '--nodiscard'
reclaimPolicy: Delete
allowVolumeExpansion: true

    Some of the main points if this file are as follows:

    • We are registering this storage class as the default storage class for our Kubernetes cluster
    • In the parameters section, we supply the specific DSM’s IP and location on the DSM’s file system. In my case, I have a single volume and a single storage pool, which corresponds to the location of “/volume1”
    • I’ve set my reclaimPolicy to Delete. This means when I give up the PersistentVolumeClaim, the iSCSI target and LUN will be deleted on the Synology
    • allowVolumeExpansion is set to True. This allows for dynamic expansion of all parts from the PersistentVolumeClaim, PersistentVolume, and the iSCSI LUN/target on the Synology

    Save the file. I should note a something about the usage of iSCSI with this CSI. When using iSCSI, the LUN that will be created by the CSI will be created as thin-provisioned. This will allow for snapshots to be taken of the LUN (which will come in handy later, especially if you plan on doing any backup/recovery workflows within the Kubernetes cluster).

    If you wanted to create other storage classes this is where you could make a copy of the file and edit. Based on the Synology CSI documentation, besides iSCSI, you can create a storage class that uses the SMB protocol (although there’s a bit of extra configuration for creating a Secret object to specify what user will have the rights to the SMB share) or you can create a storage class using the NFS protocol.

    Caveat Time

    Now, if you choose to use the NFS protocol, there’s a slight bug you’ll have to workaround. Let’s take a look at the storage class YAML file:

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: synostorage-nfs
provisioner: csi.san.synology.com
parameters:
  protocol: "nfs"
  dsm: "192.168.1.1"
  location: '/volume1/k8s'
  mountPermissions: '0755'
mountOptions:
  - nfsvers=4.1
reclaimPolicy: Delete
allowVolumeExpansion: true

    Notice I’ve specified a directory under /volume1. In this example, it’s the subfolder k8s. Unfortunately, there is an existing bug with v1.20 that doesn’t accept subfolders under the volume root directory. At this time, you’ll get an error message stating something to the effect that “Couldn’t find any host available to create Volume”. There appears to be a known issue documented in the Github pages for this project and we are waiting on a fix to be deployed to ensure NFS can point to subdirectories under the volume root. For the time being, set location to ‘/volume1 ‘

    Volume Snapshots

    Lastly, let’s configure the YAML file for the volume snapshot feature of the Synology CSI. Navigate to the following folder: /synology-csi/deploy/kubernetes/v1.20/snapshotter

    In this folder, you will find the file volume-snapshot-class.yml. Edit this file.

    apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: synology-snapshotclass
  annotations:
    storageclass.kubernetes.io/is-default-class: "false"
    k10.kasten.io/is-snapshot-class: "true"
driver: csi.san.synology.com
deletionPolicy: Delete
  #parameters:
  #description: 'Kubernetes CSI' ＃ only for iscsi protocol
  #is_locked: 'false'

    Nothing major here except added line for Veeam Kasten that specifies this VolumeSnapshotClass as “true”. I’ll blog more about Kasten in my environment, but this was a special add to let Kasten initiate the volume snapshots in my environment for backup purposes.

    Installation

    Now that we have the files configured, we need to actually perform the installation of the CSI into the Kubernetes environment. In my case, I decided against building the local containers in Docker and instead opted for the installation to pull the latest versions of the containers from Docker Hub. To do that, I performed the following command while in the synology-csi folder:

    ./scripts/deploy.sh install –all

    This command ensures that all the options, including the VolumeSnapshotClass, is registered within your Kubernetes cluster. In fact, your Kubernetes cluster will get a variety of containers registered, like so:

    jon@k8s-control:~$ kubectl get pods -n synology-csi
NAME                         READY   STATUS    RESTARTS       AGE
synology-csi-controller-0    4/4     Running   0              9d
synology-csi-node-6jbfp      2/2     Running   0              9d
synology-csi-node-949q2      2/2     Running   0              9d
synology-csi-node-snxhz      2/2     Running   0              9d
synology-csi-node-wml75      2/2     Running   0              9d
synology-csi-snapshotter-0   2/2     Running   0              9d

    As you can see, the primary controller and snapshotter were configured in the cluster, as well as a node container put on each node in the Kubernetes cluster.

    Conclusion

    I really enjoyed working on this little project. I’ve been meaning to get deeper into Kubernetes and it’s interaction layers with hardware. So in this case, I was able to setup persistent storage to my Synology DS923+ AND have it configured to backup and recover via snapshots. This was a far cry from just using generic storage providers that were limited in what they could perform. While there are a couple of nuances to getting this CSI working properly, I do recommend that if you have a Synology device and want to experiment with the CSI, go ahead and do so. Hopefully, you’ll have as much fun as I did getting this running.