{"id":37126714,"url":"https://github.com/jparklab/synology-csi","last_synced_at":"2026-01-14T14:41:33.596Z","repository":{"id":48513653,"uuid":"162019193","full_name":"jparklab/synology-csi","owner":"jparklab","description":"Container Storage Interface (CSI) for Synology","archived":false,"fork":false,"pushed_at":"2022-02-02T17:50:27.000Z","size":141,"stargazers_count":155,"open_issues_count":14,"forks_count":34,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-06-18T21:42:07.724Z","etag":null,"topics":["csi","csi-plugin","kubernetes","storage","synology"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jparklab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-16T16:21:28.000Z","updated_at":"2024-06-12T13:50:18.000Z","dependencies_parsed_at":"2022-09-18T12:21:04.793Z","dependency_job_id":null,"html_url":"https://github.com/jparklab/synology-csi","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jparklab/synology-csi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jparklab%2Fsynology-csi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jparklab%2Fsynology-csi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jparklab%2Fsynology-csi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jparklab%2Fsynology-csi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jparklab","download_url":"https://codeload.github.com/jparklab/synology-csi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jparklab%2Fsynology-csi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28423968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T13:30:50.153Z","status":"ssl_error","status_checked_at":"2026-01-14T13:29:08.907Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csi","csi-plugin","kubernetes","storage","synology"],"created_at":"2026-01-14T14:41:33.091Z","updated_at":"2026-01-14T14:41:33.591Z","avatar_url":"https://github.com/jparklab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# synology-csi ![Docker image](https://github.com/jparklab/synology-csi/workflows/Docker%20image/badge.svg) ![Go Report Card](https://goreportcard.com/badge/github.com/jparklab/synology-csi)\n\nA [Container Storage Interface](https://github.com/container-storage-interface) Driver for Synology NAS.\n\n# Platforms Supported\n\n The driver supports linux only since it requires `iscsiadm` to be installed on the host. It is currently tested with Ubuntu 16.04, Ubuntu 18.04, and [Alpine](https://alpinelinux.org/).\n\n We have pre-built Docker [images](https://hub.docker.com/r/jparklab/synology-csi) for amd64, arm64, armv7 architectures.\n\n# Quickstart Guide\n\n## Synology Configuration:\n\n 1. Create a Storage Pool\n 2. Create a Volume\n 3. Go to Control Panel \u003e Security \u003e General: Enable \"Enhance browser compatibility by skipping IP checking\"\n 4. Go to Control Panel \u003e Security \u003e Account: Disable \"Auto block\"\n 5. Create a Storage User service account and add it to the \"administrators\" group\n\n## Synology CSI Configuration and Setup\n\n 1. Clone the repository\n 2. Perform the following on all your Kubernetes cluster nodes (Ubuntu):\n   * Install the build dependencies: `apt-get update \u0026\u0026 apt-get install -y open-iscsi make \u0026\u0026 snap install go --classic`\n   * Change (`cd`) to the cloned repository\n   * Run the Makefile build: `make`\n   * Create the kubelet plugins directory: `mkdir -p /var/lib/kubelet/plugins/csi.synology.com/`\n   * Copy the built binary from `\u003ccloned repository path\u003e/bin/` to the kubelet plugin directory: `cp ./bin/synology-csi-driver /var/lib/kubelet/plugins/csi.synology.com/`\n 3. Edit the appropriate deployment for your Kubernetes version as needed\n   * You will probably want to adjust the `storage_class.yml` based on your Synology volume, filesystem, and provisioning type (thick/thin) and additionally the name of the class as well to meet your requirements/preferences.\n   * You may also have to build containers depending on your hardware architecture and adjust the container images in the deployments.  This will involve building the container images for this project and the following projects:  \n       - https://github.com/kubernetes-csi/node-driver-registrar\n       - https://github.com/kubernetes-csi/external-provisioner\n       - https://github.com/kubernetes-csi/external-attacher\n 4. Create a [syno-config.yml](syno-config.yml)\n 5. Create the namespace: `kubectl create ns synology-csi`\n 6. Create a secret from the customized [syno-config.yml](syno-config.yml): `kubectl create secret -n synology-csi generic synology-config --from-file=syno-config.yml`\n 7. Apply the deployment: `kubectl apply -f deploy/\u003ckubernetes version\u003e`\n\n At this point you should be able to deploy persistent volume claims with the new storage class.\n\n---\n\n# Install Details\n\nMake sure that `iscsiadm` is installed on all the nodes where you want this attacher to run.\n\n# Build\n\n## Build package\n\n```bash\nmake\n```\n\n## Build Docker Image\n\n```bash\n# e.g. docker build -t jparklab/synology-csi .\ndocker build [-f Dockerfile] -t \u003crepo\u003e[:\u003ctag\u003e] .\n```\n\n## Build Docker Multi-architecture Images\n\nIn order to build a multiarch image, you must have Docker 19.03 or higher version that supports [buildx](https://docs.docker.com/buildx/working-with-buildx/)\n\n```bash\n# e.g. ./build.sh -t jparklab/synology-csi\n./build.sh -t \u003crepo\u003e[:\u003ctag\u003e] .\n```\n\n# Test\n\nHere we use [gocsi](https://github.com/rexray/gocsi) to test the driver.\n\n## Create a Configuration File for Testing\n\nYou need to create a config file that contains information to connect to the Synology NAS API. See [Create a config file](#config) below\n\n## Start Plugin Driver\n\n```bash\n# You can specify any name for nodeid\ngo run cmd/syno-csi-plugin/main.go \\\n  --nodeid CSINode \\\n  --endpoint tcp://127.0.0.1:10000 \\\n  --synology-config syno-config.yml\n```\n\n## Get plugin info\n\n```bash\ncsc identity plugin-info -e tcp://127.0.0.1:10000\n```\n\n## Create a volume\n\n```bash\ncsc controller create-volume \\\n  --req-bytes 2147483648 \\\n  -e tcp://127.0.0.1:10000 \\\n  test-volume\n\"8.1\" 2147483648 \"iqn\"=\"iqn.2000-01.com.synology:kube-csi-test-volume\" \"mappingIndex\"=\"1\" \"targetID\"=\"8\"\n```\n\n## List Volumes\n\nThe first column in the output is the volume D\n\n```bash\ncsc controller list-volumes -e tcp://127.0.0.1:10000\n\"8.1\" 2147483648 \"iqn\"=\"iqn.2000-01.com.synology:kube-csi-test-volume\" \"mappingIndex\"=\"1\" \"targetID\"=\"8\"\n```\n\n## Delete the Volume\n\n```bash\n# e.g.\n## csc controller delete-volume  -e tcp://127.0.0.1:10000 8.1\ncsc controller delete-volume  -e tcp://127.0.0.1:10000 \u003cvolume id\u003e\n```\n# Deploy\n\n## Ensure Kubernetes Cluster is Configured for CSI Drivers\n\n  For Kubernetes v1.12, and v1.13, feature gates need to be enabled to use CSI drivers.\n  Follow instructions on https://kubernetes-csi.github.io/docs/csi-driver-object.html and https://kubernetes-csi.github.io/docs/csi-node-object.html\n  to set up your Kubernetes cluster.\n\n## Create a config file \u003ca name='config'\u003e\u003c/a\u003e\n\n```yaml\n---\n# syno-config.yml file\nhost: \u003chostname\u003e           # ip address or hostname of the Synology NAS\nport: 5000                 # change this if you use a port other than the default one\nsslVerify: false           # set this true to use https\nusername: \u003clogin\u003e          # username\npassword: \u003cpassword\u003e       # password\nloginApiVersion: 2         # Optional. Login version. From 2 to 6. Defaults to \"2\".\nloginHttpMethod: \u003cmethod\u003e  # Optional. Method. \"GET\", \"POST\" or \"auto\" (default). \"auto\" uses POST on version \u003e= 6\nsessionName: Core          # You won't need to touch this value\nenableSynoToken: no        # Optional. Set to 'true' to enable syno token. Only for versions 3 and above.\nenableDeviceToken: yes     # Optional. Set to 'true' to enable device token. Only for versions 6 and above.\ndeviceId: \u003cdevice-id\u003e      # Optional. Only for versions 6 and above. If not set, DEVICE_ID environment var is read.\ndeviceName: \u003cname\u003e         # Optional. Only for versions 6 and above.\n```\n\n\n## Create a Secret from the syno-config.yml file\n\n    kubectl create secret -n synology-csi generic synology-config --from-file=syno-config.yml\n\n### (Optional) Use https with self-signed CA\n\n  To use https with certificate that is issued by self-signed CA. CSI drivers needs to access the CA's certificate.\n  You can add the certificate using configmap.\n\n  Create a configmap with the certificate\n\n```bash\n# e.g.\n##  kubectl create configmap synology-csi-ca-cert --from-file=self-ca.crt\nkubectl create configmap synology-csi-ca-cert --from-file=\u003cca file\u003e\n```\n\n  Add the certificate to the deployments\n\n```yaml\n# Add to attacher.yml, node.yml, and provisioner.yml\n..\nspec:\n...\n- name: csi-plugin\n...\n  volumeMounts:\n  ...\n  - mountPath: /etc/ssl/certs/self-ca.crt\n    name: cert\n    subPath: self-ca.crt      # this should be the same as the file name that is used to create the configmap\n...\nvolumes:\n- configMap:\n    defaultMode: 0444\n    name: synology-csi-ca-cert\n```\n\n## Deploy to Kubernetes\n\n```bash\nkubectl apply -f deploy/kubernetes/v1.15\n```\n\n### Parameters for the StorageClass and Synology\n\nBy default, iscsi LUN will be created on Volume 1 (`/volume1`) location with thin provisioning.\nYou can set parameters in `storage_class.yml` to choose different locations or volume type.\n\n```yaml\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nname: synology-iscsi-storage\n...\nprovisioner: csi.synology.com\nparameters:\n  location: '/volume2'\n  type: 'FILE'          # if the location has ext4 file system, use FILE for thick provisioning, and THIN for thin provisioning.\n                        # for btrfs file system, use BLUN_THICK for thick provisioning, and BLUN for thin provisioning.\nreclaimPolicy: Delete\nallowVolumeExpansion: true # support from Kubernetes 1.16\n```\n\n***NOTE:*** if you have already created storage class, you would need to delete the storage class and recreate it.\n\n# Synology Configuration Details\n\nAs multiple logins are executed from this service at almost the same time, your Synology might block the\nrequests and you will see `407` errors (with version 6) or `400` errors in your log. It is advisable to\ndisable Auto block and IP checking if you want to get this working properly.\n\nMake sure you do the following:\n- go to Control Panel / Security / General: Enable \"Enhance browser compatibility by skipping IP checking\"\n- go to Control Panel / Security / Account: Disable \"Auto block\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjparklab%2Fsynology-csi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjparklab%2Fsynology-csi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjparklab%2Fsynology-csi/lists"}