{"id":13582476,"url":"https://github.com/travisghansen/freenas-iscsi-provisioner","last_synced_at":"2025-09-10T10:33:41.003Z","repository":{"id":54739212,"uuid":"140656077","full_name":"travisghansen/freenas-iscsi-provisioner","owner":"travisghansen","description":"FreeNAS iscsi provisioner","archived":false,"fork":false,"pushed_at":"2025-01-28T17:30:16.000Z","size":145,"stargazers_count":29,"open_issues_count":1,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-30T06:47:45.824Z","etag":null,"topics":["csi","freenas","iscsi","kubernetes","provisioner"],"latest_commit_sha":null,"homepage":"","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/travisghansen.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-12T03:27:09.000Z","updated_at":"2024-03-29T08:58:50.000Z","dependencies_parsed_at":"2025-04-20T09:17:08.755Z","dependency_job_id":null,"html_url":"https://github.com/travisghansen/freenas-iscsi-provisioner","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/travisghansen/freenas-iscsi-provisioner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisghansen%2Ffreenas-iscsi-provisioner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisghansen%2Ffreenas-iscsi-provisioner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisghansen%2Ffreenas-iscsi-provisioner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisghansen%2Ffreenas-iscsi-provisioner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/travisghansen","download_url":"https://codeload.github.com/travisghansen/freenas-iscsi-provisioner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/travisghansen%2Ffreenas-iscsi-provisioner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266276180,"owners_count":23903983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","freenas","iscsi","kubernetes","provisioner"],"created_at":"2024-08-01T15:02:45.219Z","updated_at":"2025-07-21T09:33:51.677Z","avatar_url":"https://github.com/travisghansen.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Deprecation Notice\n\nNon-csi drivers are no longer receiving updates from the Kubernetes team.\nAs such this driver has been deprecated and replaced with a newer `csi` based\nimplementation - https://github.com/democratic-csi/democratic-csi\n\nThe new implementation works with all the fancy `csi` features such as snapshots,\nresizing, etc. Enjoy!\n\nNote that a conversion script has been created to facilitate migrating volumes\ncreated using this project to `democratic-csi`. Please visit the project for\nmore details.\n\n# What is freenas-provisioner\n\nFreeNAS-iscsi-provisioner is a Kubernetes external provisioner.\nWhen a `PersisitentVolumeClaim` appears on a Kube cluster, the provisioner will\nmake the corresponding calls to the configured FreeNAS API to create an iscsi\ntarget/lun usable by the claim. When the claim or the persistent volume is\ndeleted, the provisioner deletes the previously created resources.\n\nSee this for more info on external provisioner:\nhttps://github.com/kubernetes-incubator/external-storage\n\nUnless you have a very specific use-case for iscsi/block devices, it is\nrecommended to use the NFS variant of this project available here:\nhttps://github.com/nmaupu/freenas-provisioner\n\n# Usage\n\nThe scope of the provisioner allows for a single instance to service multiple\nclasses (and/or FreeNAS servers). The provisioner itself can be deployed into\nthe cluster or ran out of cluster, for example, directly on a FreeNAS server.\n\nEach `StorageClass` should have a corresponding `Secret` created which contains\nthe credentials and host information used to communicate with with FreeNAS API.\nIn essence each `Secret` corresponds to a FreeNAS server.\n\nThe `Secret` namespace and name may be customized using the appropriate\n`StorageClass` `parameters`. By default `kube-system` and `freenas-iscsi` are\nused. While multiple `StorageClass` resources may point to the same server\nand hence same `Secret`, it is recommended to create a new `Secret` for each\n`StorageClass` resource.\n\nIt is **highly** recommended to read `deploy/class.yaml` to review available\n`parameters` and gain a better understanding of functionality and behavior.\n\n## FreeNAS Setup\n\nYou must manually create a dataset. You may simply use a pool as the parent\ndataset but it's recommended to create a dedicated dataset.\n\nAdditionally, you need to enable the iscsi service with it's corresponding\nresources such as portal, initiator, and group.\n\n## Provision the provisioner\n\nRun it on the cluster:\n\n```\nkubectl apply -f deploy/rbac.yaml -f deploy/deployment.yaml\n```\n\nAlternatively, for advanced use-cases you may run the provisioner out of cluster\nincluding directly on the FreeNAS server if desired. Running out of cluster is\nnot currently recommended.\n\n```\n./bin/freenas-iscsi-provisioner-freebsd --kubeconfig=/path/to/kubeconfig.yaml\n```\n\n## Create `StorageClass` and `Secret`\n\nAll the necessary resources are available in the `deploy` folder. At a minimum\n`secret.yaml` must be modified (remember to `base64` the values) to reflect the\nserver details. You may also want to read `class.yaml` to review available\n`parameters` of the storage class. For instance to set the `datasetParentName`.\n\n```\nkubectl apply -f deploy/secret.yaml -f deploy/class.yaml\n```\n\n## Example usage\n\nNext, create a `PersistentVolumeClaim` using the storage class\n(`deploy/test-claim.yaml`):\n\n```\n---\nkind: PersistentVolumeClaim\napiVersion: v1\nmetadata:\n  name: freenas-test-iscsi-pvc\nspec:\n  storageClassName: freenas-iscsi\n  accessModes:\n    - ReadWriteOnce\n  resources:\n    requests:\n      storage: 1Mi\n```\n\nUse that claim on a testing pod (`deploy/test-pod.yaml`):\n\n```\n---\nkind: Pod\napiVersion: v1\nmetadata:\n  name: freenas-test-iscsi-pod\nspec:\n  containers:\n  - name: freenas-test-isci-pod\n    image: gcr.io/google_containers/busybox:1.24\n    command:\n      - \"/bin/sh\"\n      - \"-c\"\n      - \"--\"\n    args: [ \"date \u003e\u003e /mnt/file.log \u0026\u0026 while true; do sleep 30; done;\" ]\n    volumeMounts:\n      - name: freenas-test-volume\n        mountPath: \"/mnt\"\n  restartPolicy: \"Never\"\n  volumes:\n    - name: freenas-test-volume\n      persistentVolumeClaim:\n        claimName: freenas-test-iscsi-pvc\n```\n\nThe underlying zvol, target, extent, etc should be quickly appearing on the\nFreeNAS side. In case of issue, follow the provisioner's logs using:\n\n```\nkubectl -n kube-system logs -f freenas-iscsi-provisioner-\u003cid\u003e\n```\n\n## CHAP settings\n\nYou should create a secret which holds CHAP authentication credentials based on `deploy/freenas-iscsi-chap.yaml`.\n- If you have authentication enabled for the portal (discovery) then set `discovery*` parameters in the secret, and in StorageClass you should set `targetDiscoveryCHAPAuth` to `true`.\n- If you want authentication for the targets, then set `node*` parameters in the secret, and in StorageClass you should set `targetGroupAuthtype` and `targetGroupAuthgroup` accordingly, and also set `targetSessionCHAPAuth` to `true`.\n\n# Performance\n\n100 10MiB PVCs\nCreating took ~10 minutes\n\nDeleting took ~6 minutes\n\n# Testing\n\nChoas testing has been performed to ensure the various actions are idempotent.\n\n# Development\n\n```\nmake vendor \u0026\u0026 make\n```\n\nBinary is located into `bin/freenas-iscis-provisioner`. It is compiled to be\nrun on `linux-amd64` by default, but you may run the following for different\nbuilds:\n\n```\nmake vendor \u0026\u0026 make darwin\n# OR\nmake vendor \u0026\u0026 make freebsd\n```\n\nTo run locally with an appropriate `$KUBECONFIG` you may run:\n\n```\n./local-start.sh\n```\n\nTo format code before committing:\n\n```\nmake fmt\n```\n\n- https://github.com/kubernetes-incubator/external-storage/blob/v4.0.0/lib/controller/controller.go\n- https://github.com/kubernetes-sigs/sig-storage-lib-external-provisioner/blob/master/controller/controller.go\n- https://gianarb.it/blog/kubernetes-shared-informer\n- https://engineering.bitnami.com/articles/a-deep-dive-into-kubernetes-controllers.html\n\n## Docs\n\n- https://github.com/kubernetes/community/tree/master/contributors/design-proposals/storage\n- https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/volume-provisioning.md\n- https://kubernetes.io/docs/concepts/storage/storage-classes/\n- https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#-strong-api-overview-strong-\n- https://docs.openshift.org/latest/install_config/persistent_storage/persistent_storage_iscsi.html\n- http://api.freenas.org\n- https://doc.freenas.org/11/sharing.html#block-iscsi\n- https://github.com/kubernetes-incubator/external-storage/blob/master/iscsi/targetd/provisioner/iscsi-provisioner.go\n- https://github.com/dghubble/sling\n\n## TODO\n\n- volume resizing - https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/grow-volume-size.md\n- volume snapshots - https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/volume-snapshotting.md\n- mount options - https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/mount-options.md\n- ~~CHAP~~\n- fsType\n- properly handle `zvol` API differences with `volsize` getting sent as string and returned as int\n- loop GetBy\u003cfoo\u003e requests that require `limit` param\n- ~~recursive zvol delete in v1 api~~\n\n## Notes\n\nTo sniff API traffic between host and server:\n\n```\nsudo tcpdump -i any -A -s 0 'host \u003cserver ip\u003e and tcp port 80 and (((ip[2:2] - ((ip[0]\u00260xf)\u003c\u003c2)) - ((tcp[12]\u00260xf0)\u003e\u003e2)) != 0)'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravisghansen%2Ffreenas-iscsi-provisioner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravisghansen%2Ffreenas-iscsi-provisioner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravisghansen%2Ffreenas-iscsi-provisioner/lists"}