WEKA CSI Plugin
This page describes the WEKA CSI Plugin prerequisites, capabilities, deployment, and usage.
Last updated
This page describes the WEKA CSI Plugin prerequisites, capabilities, deployment, and usage.
Last updated
The (CSI) is a standard for exposing arbitrary block and file storage systems to containerized workloads on Container Orchestration Systems (COs) like Kubernetes.
The WEKA CSI Plugin provides the creation and configuration of persistent storage external to Kubernetes. CSI replaces plugins developed earlier in the Kubernetes evolution. It replaces the hostPath
method to expose WEKA mounts as Kubernetes volumes.
CSI protocol: 1.0-1.2
Kubernetes: 1.18 - 1.2x
WEKA: 3.8 and up
Non-converged WEKA cluster
SELinux is supported (AppArmor for Ubuntu is not supported yet)
The privileged mode must be allowed on the Kubernetes cluster
The following Kubernetes feature gates must be enabled: DevicePlugins, CSINodeInfo, CSIDriverRegistry, ExpandCSIVolumes (if not changed, they should be enabled by default)
A WEKA cluster is installed and accessible from the Kubernetes worker nodes
The WEKA client is installed on the Kubernetes worker nodes
It is recommended to use a rather than a
If the Kubernetes nodes are part of the WEKA cluster (converged mode on the WEKA servers), make sure the WEKA processes come up before kubelet
Filesystems are pre-configured on the WEKA system
Static and dynamic volumes provisioning
Mounting a volume as a WEKA filesystem directory
All volume access modes are supported: ReadWriteMany, ReadWriteOnce, and ReadOnlyMany
Volume expansion
Quota enforcement on persistent volumes
Snapshots
On your workstation (assuming connectivity to Kubernetes cluster), add the csi-wekafs
repository:
Install the plugin by issuing the following command:
On successful installation the following output is provided:
If the previous version was installed using Helm, you can safely skip this section.
Download the csi-wekafs
git repository
Assuming connectivity to the Kubernetes cluster is valid, run the following script to remove the CSI driver components:
Execute the following command:
A successful upgrade provides the following output:
The CSI Plugin fetches the WekaFS cluster capabilities during the first login to the API endpoint and caches it throughout the login refresh token validity period, to improve the efficiency and performance of the plugin.
However, the WekaFS cluster upgrade might come unnoticed if performed during this time window, continuing to provision new volumes in legacy mode.
To expedite the update of the Weka cluster capabilities, it is recommended to delete all the CSI Plugin pods, to invalidate the cache. The pods will then be restarted.
The Weka CSI Plugin supports both dynamic (persistent volume claim) and static (persistent volume) volume provisioning. For provisioning either type of a persistent volume, a Storage Class must exist in Kubernetes deployment that matches the Weka cluster configuration.
This model assumes no API connectivity to the Weka cluster. As a result, the functionality provided by the Weka CSI Plugin is limited.
It is first required to define a storage class to use the Weka CSI Plugin.
Parameter
Description
Limitations
filesystemName
The name of the Weka filesystem to create directories in as Kubernetes volumes
The filesystem should exist in the Weka cluster
Apply the StorageClass and check it has been created successfully:
It is possible to define multiple storage classes with different filesystems.
In the API-based model, the API endpoint addresses and authentication credentials must be provided to the Weka CSI Plugin in order to establish a REST API connection with the Weka cluster and perform configuration tasks on it.
Note: It is recommended to deploy the CSI plugin in API-Based communication model even if the Weka cluster is below version v3.13.0
Volumes provisioned using the API-Based model on older Weka clusters, do not support capacity enforcement, and are still considered "Legacy". However, they can be easily upgraded to capacity enforcement capabilities after the Weka cluster upgrade.
Key
Description
Notes
username
The user name for API access to the Weka cluster, in base64 encoding.
Must have at least read-write permissions in the organization. It is recommended to create a separate user with admin privileges for the CSI plugin
password
The user password for API access to the Weka cluster, in base64 encoding.
organization
The Weka organization name for the user, in base64 encoding (use Root
if you only have one organization).
Multiple secrets may be used to provide access to multiple organizations, which in turn will be specified in different storage classes
scheme
The URL scheme used to commnicate with the Weka cluster API.
http
or https
can be used. The user must ensure that the Weka cluster was configured to use the same connection scheme.
endpoints
Comma-separated list of endpoints consisting of IP address and port, e.g.
172.31.15.113:14000,172.31.12.91:14000
The management IP addresses of at least 2 backend servers should be provided for redundancy.
Apply the Secret and check it has been created successfully:
Parameter
Description
filesystemName
The name of the Weka filesystem to create directories in as Kubernetes volumes.
The filesystem must exist on the Weka cluster
The filesystem may not be defined as "authenticated"
capacityEnforcement
Can be HARD
or SOFT
HARD
: strictly enforce quota and deny any write operation to the persistent volume consumer until space is freed up
SOFT
: do not strictly enforce the quota, but create an alert on the Weka cluster
ownerUid
Effective User ID of the owner user for the provisioned CSI volume. Might be required for application deployments running under non-root accounts. Defaults to 0
ownerGid
Effective Group ID of the owner user for the provisioned CSI volume. Might be required for application deployments running under non-root accounts. Defaults to 0
permissions
Unix permissions for the provisioned volume root directory, in octal format. Must be set in quotes. Defaults to "0775"
csi.storage.k8s.io/provisioner-secret-name
Name of the K8s secret, e.g. csi-wekafs-api-secret
It is recommended to use an anchor definition in order to avoid mistakes since the same value has to be entered in additional fields below, according to the CSI spec definitions. Refer to the example above for exact formatting.
csi.storage.k8s.io/provisioner-secret-namespace
The namespace the secret is located in.
The secret does not have to be located in the same namespace as the CSI plugin is installed.
It is recommended using an anchor definition in order to avoid mistakes since the same value has to be entered in additional fields below, accordings to the CSI spec definitions. Refer to the example above for exact formatting.
Apply the StorageClass and check it has been created successfully:
It is possible to define multiple storage classes with different filesystems.
The same secret may be reused for multiple storage classes, as long as credentials are valid to access the filesystem
Several secrets may be used, e.g., for different organizations on the same Weka cluster, or for different Weka clusters spanning across the same Kubernetes cluster
Using a similar storage class to the above, it is possible to define a persistent volume claim (PVC) for the pods.
Parameter
Description
Limitations
spec.accessModes
The volume access mode
ReadWriteMany
, ReadWriteOnce
, or ReadOnlyMany
spec.storageClassName
The storage class to use to create the PVC
Must be an existing storage class
spec.resources.requests.storage
A desired capacity for the volume
The capacity quota is not enforced but is stored on the filesystem directory extended attributed for future use
Apply the PersistentVolumeClaim and check it has been created successfully:
The Kubernetes admin can prepare some persistent volumes in advance to be used by pods, they should be an existing directory, and can contain pre-populated data to be used by the PODs.
It can be a directory previously provisioned by the CSI or a pre-existing directory in WekaFS. To expose an existing directory in WekaFS via CSI, define a persistent volume, and link a persistent volume claim to this persistent volume.
Parameter
Description
Limitations
spec.accessModes
The volume access mode
ReadWriteMany
, ReadWriteOnce
, or ReadOnlyMany
spec.storageClassName
The storage class to use to create the PV
Must be an existing storage class
spec.capacity.storage
A desired capacity for the volume
The capacity quota is not enforced but is stored on the filesystem directory extended attributed for future use
spec.csi.volumeHandle
A string specifying a previously created path
A string containing the volumeType (dir/v1
) filesystem name, and the directory path. E.g. dir/v1/podsFilesystem/my-dir
Must be an existing filesystem and path
Apply the PersistentVolume and check it has been created successfully:
Now, bind a PVC to this specific PV, use the volumeName
parameter under the PVC spec
and provide it with the specific PV name.
Parameter
Description
Limitations
spec.accessModes
The volume access mode
ReadWriteMany
, ReadWriteOnce
, or ReadOnlyMany
spec.storageClassName
The storage class to use to create the PVC
Must be the same storage class as the PV requested to bind in spec.volumeName
spec.resources.requests.storage
A desired capacity for the volume
The capacity quota is not enforced but is stored on the filesystem directory extended attributed for future use
spec.volumeName
A name of a pre-configured persistent volume
Must be an existing PV name
Apply the PersistentVolumeClaim and check it has been created successfully:
The PV will change the status to Bound
and state the relevant claim it is bounded to:
Now that we have a storage class and a PVC in place, we can configure the Kubernetes pods to provision volumes via the Weka system.
We'll take an example application that echos the current timestamp every 10 seconds, and provide it with the previously created pvc-wekafs-dir
PVC.
Note that multiple pods can share a volume produced by the same PVC as long as the accessModes
parameter is set to ReadWriteMany
.
Apply that pod:
Kubernetes will allocate a persistent volume and attach it to the pod, it will use a directory within the WekaFS filesystem as defined in the storage class mentioned in the persistent volume claim. The pod will be in Running
status, and the temp.txt
file will get updated with occasional date
information.
When installing the Weka CSI Plugin on the SELinux-enabled Kubernetes cluster, pods might be denied access to the persistent volumes provisioned on top of the Weka filesystem. The reason is a lack of permissions for containers to access objects stored on the Weka cluster.
A custom SELinux policy is provided with all the necessary security configurations to enable pod access to WekaFS-based persistent volumes. Apply the customized SELinux policy on each Kubernetes worker node that is intended to serve the WekaFS-based persistent volumes.
The provided policy allows processes with container_t
seclabel to access objects having a wekafs_t
label, which is set for all files and directories of mounted CSI volumes.
To use the Weka CSI Plugin with SELinux enforcement, perform the following:
Distribute the SELinux policy package to all Kubernetes nodes using one of the following options:
Clone Weka CSI Plugin Github repository:
Copy the content of selinux
directory directly to Kubernetes nodes
Apply the policy package directly:
Verify that the policy is applied correctly:
If the output matches mentioned above, skip to step 4. Otherwise, proceed to step 3 to build the policy from the sources.
In certain circumstances, the pre-compiled policy installation could fail. For example, in a different Kernel version or Linux distribution. In this case, build the policy and install it from the source using the following steps:
NOTE: For this purpose, the
policycoreutils-devel
package (or its alternative in case of Linux distribution different from the RedHat family) is required.
Verify that the policy is applied correctly:
The policy provides a boolean setting that allows on-demand enablement of relevant permissions. To enable WekaFS CSI volumes access from pods, run the command:
To disable access, perform the command:
The configuration changes are applied immediately.
To label volumes correctly, install the Weka CSI Plugin in an SELinux-compatible mode. To do that, set the selinuxSupport
value to "enforced"
or "mixed”
by editing the file values.yaml
or passing the parameter directly in the helm
installation command.
Example:
Follow these considerations:
Weka CSI pluging supports both the enforced
and mixed
modes of selinuxSupport
. The installation depends on the following mode settings:
When selinuxSupport
is set to enforced
, only SELinux-enabled CSI plugin node components are installed.
When selinuxSupport
is set to mixed
, both non-SELinux and SELinux-enabled components are installed.
When selinuxSupport
is set to off
, only non-SELinux CSI plugin node components are installed.
The SELinux status cannot be known from within the CSI plugin pod. Therefore, a way of distinguishing between SELinux-enabled and non-SELinux nodes is required. Weka CSI plugin relies on the node affinity mechanism by matching the value of a certain node label, in a mutually exclusive way. That is, only when the label exists and is set to "true"
, an SELinux-enabled node component will start on that node, otherwise non-SELinux node component will start.
To ensure that the plugin starts in compatibility mode, set the following label on each SELinux-enabled Kubernetes node:
If another label stating SELinux support is already maintained on nodes, you can modify the expected label name in the selinuxNodeLabel
parameter by editing the file values.yaml
or by setting it directly during the Weka CSI Plugin installation.
Example:
If a node label is modified after installing the Weka CSI Plugin node component on that node, terminate the csi-wekafs-node-XXXX component on the affected node. As a result, a replacement pod is automatically scheduled on the node but with the correct SELinux configuration.
Monitor the pod logs using the following command (expect no printing in the log files):
If the command returns a repeating message like the following one, it is most likely that the node on which the relevant pod is running is misconfigured:
Obtain the node name from the pod:
Connect to the relevant node and check if the Weka CSI SELinux policy is installed and enabled:
If the result matches the example, proceed to the next step.
If the policy is off, enable it and check the pod output again by running:
Check if the node is labeled with plugin is operating in SELinux-compatible mode by running the following command:
NOTE: If the label was missing and added by you during troubleshooting, the CSI node server component must be restarted on the node. Perform the following command to terminate the relevant pod and another instance will start automatically:
If the output matches example, proceed to next step
Collect CSI node server logs from the matching Kubernetes nodes and contact Weka Customer Success Team:
Capacity enforcement and integration with WekaFS directory quotas require several prerequisites:
Weka CSI plugin version 0.7.0 and up
WekaFS software version v3.13.0 and up
Weka CSI plugin ability to communicate with WekaFS using REST API, and correlate between a certain persistent volume and the WekaFS cluster serving this volume.
Kubernetes does not allow modification of StorageClass parameters, hence every volume created with the legacy-model storage class will never report its credentials.
Weka CSI Plugin 0.7.0 provides a special configuration mode in which legacy volumes can be bound to a single secret, in turn referring to a single WekaFS cluster API connection parameters. In this configuration mode, every request to serve (create, delete, expand...) a legacy Persistent Volume (or Persistent Volume Claim) that originates from a Legacy Storage Class (without reference to an API secret) will be communicated to that cluster.
This configuration can be applied following these two steps:
Create a Kubernetes secret that describes the API communication parameters for legacy volumes.
This secret must be located in the same Kubernetes namespace of the Weka CSI Plugin
Set the legacyVolumeSecretName
parameter to match the name of secret above during plugin upgrade or installation
This can be done by directly modifying the values.yaml
or by explicitly setting the parameter during the Helm upgrade:
Note: The Kubernetes secret must be created before executing the helm upgrade. Otherwise, the CSI Plugin components will remain in a Pending
state after the upgrade.
Once the volume to API binding configuration described in the previous section is performed, the volumes may be migrated by binding a new WekaFS directory quota object to an existing persistent volume.
Weka provides a migration script that automates the process.
Check out the csi-wekafs
repository from any server that is connected to WekaFS cluster:
Execute the migration script by issuing the following command, where <filesystem_name>
states the filesystem name on which the CSI volumes are located, and optional <csi_volumes_dir>
parameter states the directory inside the filesystem where CSI volumes are stored (only if the directory differs from default values)
For example:
Here are some useful basic commands to check the status and debug the service:
To workaround the Kubernetes issue (required only if the default memory for the client has been increased):
If the Weka client is installed on the K8s nodes via a manual stateless client mount, set the reserve_1g_hugepages
mount option to false
in the mount command.
Note: Quota enforcement on persistent volumes requires WEKA version 3.13 and up. For additional information about enforcing quotas on existing persistent volumes, see the section.
The WEKA CSI Plugin deployment can be performed with a from the official WEKA ArtifactHub repository.
Note: Upgrading a plugin deployed directly (via deploy.sh
script) is not supported. This section describes the procedure to clean up the existing CSI plugin components. After cleanup, proceed to the section.
Note: If you plan to upgrade existing Weka CSI Plugin deployment and enable directory quota enforcement for already existing volumes, please refer to the section.
If not yet configured, add the Helm repository as defined in the section.
In the , the Weka CSI Plugin does not communicate with the Weka cluster via API and solely relies on in-band communication via the data plane. This configuration does not provide extended configuration abilities.
In the , the Weka CSI Plugin communicates with the Weka cluster using REST API, leveraging this integration to provide extended abilities, such as strict enforcement of volume capacity usage via integration with WekaFS functionality.
The information is stored securely in , which is, in turn, referred to by the Storage Class.
The policy is provided both as a Type Enforcement file (csi-wekafs.te
) and a Precompiled Policy package (csi-wekafs.pp
), found in .
Make sure you have configured a valid CSI API . Create a valid Weka CSI Plugin .
Provision a .
Provision a , to enable access of all pods on all nodes.
If no result, the policy is not installed. Perform the procedure.
If the output is empty, proceed to .
In the model, Kubernetes StorageClass refers to a secret that describes all the required parameters for API calls to the Weka cluster. However, this is not the situation in the , where the storage class doesn't specify the API credentials.
The format of the secret is identical to the secret defined in the section
Due to a Kubernetes v1.18 issue with allocating mixed hugepages sizes () is required that the Weka system will not try to allocate mixed sizes of hugepages on the Kubernetes nodes.
If this is a Weka server or a Weka client, which is part of the Weka cluster, contact the .