csi-driver-smb/docs/driver-parameters.md

Driver Parameters

Bring your own Samba server before using this driver.

Storage Class Usage

get an example

Name	Meaning	Available Value	Mandatory	Default value
source	Samba Server address	//smb-server-address/sharename (Azure File format: //accountname.file.core.windows.net/filesharename)	Yes
subDir	sub directory under smb share		No	if sub directory does not exist, this driver would create a new one
onDelete	when volume is deleted, keep the directory if it's retain	delete(default), retain, archive	No	delete
csi.storage.k8s.io/provisioner-secret-name	secret name that stores username, password(domain is optional); if secret is provided, driver will create a sub directory with PV name under source	existing secret name	No
csi.storage.k8s.io/provisioner-secret-namespace	namespace where the secret is	existing secret namespace	No
csi.storage.k8s.io/node-stage-secret-name	secret name that stores username, password(domain is optional)	existing secret name	Yes
csi.storage.k8s.io/node-stage-secret-namespace	namespace where the secret is	existing secret namespace	Yes

• VolumeID(volumeHandle) is the identifier of the volume handled by the driver, format of VolumeID:

{smb-server-address}#{sub-dir-name}#{share-name}

example: smb-server.default.svc.cluster.local/share#subdir#

PV/PVC Usage

get an example

Name	Meaning	Available Value	Mandatory	Default value
volumeHandle	Specify a value the driver can use to uniquely identify the share in the cluster.	A recommended way to produce a unique value is to combine the smb-server address, sub directory name and share name: {smb-server-address}#{sub-dir-name}#{share-name}.	Yes
volumeAttributes.source	Samba Server address	//smb-server-address/sharename (Azure File format: //accountname.file.core.windows.net/filesharename)	Yes
volumeAttributes.subDir	existing sub directory under smb share		No	sub directory must exist otherwise mount would fail
nodeStageSecretRef.name	secret name that stores username, password(domain is optional)	existing secret name	Yes
nodeStageSecretRef.namespace	namespace where the secret is	k8s namespace	Yes

• Use kubectl create secret to create smbcreds secret to store Samba Server username, password

append --from-literal domain="DOMAIN" if you have a domain

kubectl create secret generic smbcreds --from-literal username=USERNAME --from-literal password="PASSWORD"

Kerberos ticket support for Linux

These are the conditions that must be met:

• Kerberos support should be set up and cifs-utils must be installed on every node.
• The directory /var/lib/kubelet/kerberos/ needs to exist, and it will hold kerberos credential cache files for various users.
• This directory is shared between the host and the smb container.
• The kerberos cache files are created for each volume and cleaned up during UnstageVolume phase
• Each node should know to look up in that directory, here's example script for that, expected to be run on node provision:

mkdir -p /etc/krb5.conf.d/
echo "[libdefaults]
default_ccache_name = FILE:/var/lib/kubelet/kerberos/krb5cc_%{uid}" > /etc/krb5.conf.d/ccache.conf

• Mount flags should include sec=krb5,uid=1000,cruid=1000
  • sec=krb5 enables using credential cache
  • cruid=1000 provides information for what user credential cache will be looked up. This should match the secret entry.
  • uid=1000 is the owner of mounted files. This doesn't have to be the same as cruid.

Pass kerberos ticket in kubernetes secret

To pass a ticket through secret, it needs to be acquired. Here's example how it can be done:

export KRB5CCNAME="/var/lib/kubelet/kerberos/krb5cc_1000"
kinit USERNAME # Log in into domain
kvno cifs/lowercase_server_name # Acquire ticket for the needed share, it'll be written to the cache file
CCACHE=$(base64 -w 0 $KRB5CCNAME) # Get Base64-encoded cache

And passing the actual ticket to the secret, instead of the password. Note that key for the ticket has included credential id, that must match exactly cruid= mount flag. In theory, nothing prevents from having more than single ticket cache in the same secret.

kubectl create secret generic smbcreds-krb5 --from-literal krb5cc_1000=$CCACHE

See example of the StorageClass

Tips

subDir parameter supports following pv/pvc metadata conversion

if subDir value contains following string, it would be converted into corresponding pv/pvc name or namespace

• ${pvc.metadata.name}
• ${pvc.metadata.namespace}
• ${pv.metadata.name}

provide mountOptions for DeleteVolume

since DeleteVolumeRequest does not provide mountOptions, following is the workaround to provide mountOptions for DeleteVolume

• create a secret smbcreds with mountOptions

kubectl create secret generic smbcreds --from-literal username=USERNAME --from-literal password="PASSWORD" --from-literal mountOptions="dir_mode=0777,file_mode=0777,uid=0,gid=0,mfsymlinks"

• set csi.storage.k8s.io/provisioner-secret-name: "smbcreds" in storage class