This documentation shows how to install Alluxio on Kubernetes via Operator, a Kubernetes extension for managing applications.
Prerequisites
Kubernetes
A Kubernetes cluster with version at least 1.19, with feature gates enabled
Ensure the cluster’s Kubernetes Network Policy allows for connectivity between applications (Alluxio clients) and the Alluxio Pods on the defined ports
The Kubernetes cluster has helm 3 with version at least 3.6.0 installed
Image registry for storing and managing container image
Hardware
Each node should have at least 8 CPUs and 32GB of memory
Each node should have at least 100GB of storage space
Permission to create CRD (Custom Resource Definition)
Permission to create ServiceAccount, ClusterRole, and ClusterRoleBinding for the operator pod
Permission to create namespace that the operator will be in
Preparation
Download the files for Alluxio operator and Alluxio cluster
Please visit the Alluxio download page and select Alluxio Enterprise AI to download. After the download is complete, extract the files using the following command:
$ tar zxf alluxio-enterprise-k8s-ai-trial.tar.gz
After extraction, you will obtain the following files:
alluxio-operator-2.0.0-helmchart.tgz is the helm chart for deploying Alluxio operator
alluxio-operator-2.0.0-docker.tar is the docker image for all Alluxio operator components
alluxio-enterprise-AI-3.3-7.0.0-docker.tar is the docker image for Alluxio
Upload the images to an image registry
An image registry is a centralized location for storing and sharing your container images. It can be either public or private. Cloud provider may come with its container registry as a service. For example, Amazon Elastic Container Registry(ECR), Azure Container Registry (ACR), and Google Container Registry (GCR). You can even run your private registry on your local system or inside your organization.
This example shows how to upload the Alluxio operator images.
# load the image to local$ docker load -i alluxio-operator-2.0.0-docker.tar$ docker load -i alluxio-enterprise-AI-3.3-7.0.0-docker.tar# retag the image with your private registry$ docker tag alluxio/operator:2.0.0 <YOUR.PRIVATE.REGISTRY.HERE>/alluxio-operator:2.0.0$ docker tag alluxio/alluxio-enterprise:AI-3.3-7.0.0 <YOUR.PRIVATE.REGISTRY.HERE>/alluxio-enterprise:AI-3.3-7.0.0# push to the remote registry$ docker push <YOUR.PRIVATE.REGISTRY.HERE>/alluxio-operator:2.0.0$ docker push <YOUR.PRIVATE.REGISTRY.HERE>/alluxio-enterprise:AI-3.3-7.0.0
Extract the helm chart for operator
# the command will extract the files to the directory alluxio-operator/$ tar zxf alluxio-operator-2.0.0-helmchart.tgz
The extracted alluxio-operator directory contains the Helm chart files responsible for deploying the operator.
Deployment
Deploy Alluxio operator
Create the alluxio-operator/alluxio-operator.yaml file to specify the image and version used for deploying the operator. The following example shows how to specify the operator and csi images and versions:
Move to the alluxio-operator directory and execute the following command to deploy the operator:
$ cd alluxio-operator# the last parameter is the directory to the helm chart, "." means the current directory$ helm install operator -f alluxio-operator.yaml .NAME: operatorLAST DEPLOYED: Wed May 15 17:32:34 2024NAMESPACE: defaultSTATUS: deployedREVISION: 1TEST SUITE: None# verify iftheoperatorisrunningasexpected$ kubectl get pod -n alluxio-operatorNAME READY STATUS RESTARTS AGEalluxio-cluster-controller-5647cc664d-lrx84 1/1 Running 0 14salluxio-collectinfo-controller-667b746fd6-hfzqk 1/1 Running 0 14salluxio-csi-controller-7bd66df6cf-7kh6k 2/2 Running 0 14salluxio-csi-nodeplugin-9cc9v 2/2 Running 0 14salluxio-csi-nodeplugin-fgs5z 2/2 Running 0 14salluxio-csi-nodeplugin-v22q6 2/2 Running 0 14salluxio-ufs-controller-5f6d7c4d66-drjgm 1/1 Running 0 14s
Deploying alluxio operator requires pulling dependent images from the public image repository. If you fail to deploy alluxio-operator because the network environment cannot access the public image repository, please refer to Configuring alluxio-operator image.
Deploy Alluxio
Create the alluxio-operator/alluxio-cluster.yaml file to deploy the Alluxio cluster. The file below shows the minimal configuration.
The properties specified under the .spec.properties field will be appended to the alluxio-site.properties configuration file and the Alluxio processes will read that file. You can find your configurations in the Alluxio coordinator, worker pod by looking at /opt/alluxio/conf/alluxio-site.properties.
The operator has already set the recommended configuration by default, which can start an Alluxio cluster. If you need to modify the configuration, you can edit the .spec.properties field in the alluxio-cluster.yaml file.
If your training data is stored in S3, OSS, or other storage, and the training task can access the data via s3:// or oss://, you can accelerate training by mounting the under file system into Alluxio through creating UFS resources after starting the Alluxio cluster.
If your training task accesses the training data through PVC or NAS, you need to mount the training data's PVC or NAS to the Alluxio pods when creating the Alluxio cluster. Please refer to Mount storage to Alluxio for details on mounting PVC or NAS/hostPath, and modify the alluxio-operator/alluxio-cluster.yaml accordingly.
Move to the alluxio-operator directory and execute the following command to deploy the Alluxio cluster:
$ cd alluxio-operator$ kubectl create -f alluxio-cluster.yamlalluxiocluster.k8s-operator.alluxio.com/alluxio created# the cluster will be starting$ kubectl get podNAME READY STATUS RESTARTS AGEalluxio-coordinator-0 0/1 Init:0/1 0 7salluxio-etcd-0 0/1 ContainerCreating 0 7salluxio-etcd-1 0/1 ContainerCreating 0 7salluxio-etcd-2 0/1 ContainerCreating 0 7salluxio-monitor-grafana-847fd46f4b-84wgg 0/1 Running 0 7salluxio-monitor-prometheus-778547fd75-rh6r6 1/1 Running 0 7salluxio-worker-76c846bfb6-2jkmr 0/1 Init:0/2 0 7salluxio-worker-76c846bfb6-nqldm 0/1 Init:0/2 0 7s# check the status of the cluster$ kubectl get alluxioclusterNAME CLUSTERPHASE AGEalluxio Ready 2m18s# and check the running pods after the cluster is ready$ kubectl get podNAME READY STATUS RESTARTS AGEalluxio-coordinator-0 1/1 Running 0 2m3salluxio-etcd-0 1/1 Running 0 2m3salluxio-etcd-1 1/1 Running 0 2m3salluxio-etcd-2 1/1 Running 0 2m3salluxio-monitor-grafana-7b9477d66-mmcc5 1/1 Running 0 2m3salluxio-monitor-prometheus-78dbb89994-xxr4c 1/1 Running 0 2m3salluxio-worker-85fd45db46-c7n9p 1/1 Running 0 2m3salluxio-worker-85fd45db46-sqv2c 1/1 Running 0 2m3s
In Alluxio 3.x, the coordinator is a stateless control component that serves jobs like distributed load and acts as API gateway for the operator.
If some components in the cluster do not reach the Running state, you can use kubectl describe pod to view detailed information and identify the issue. For specific issues encountered during deployment, refer to the FAQ section.
Alluxio cluster also includes etcd and monitoring components. If the image cannot be pulled from the public image registry, causing etcd and monitoring to fail to start, please refer to Configuring Alluxio Cluster Image.
Mount storage to Alluxio
Alluxio supports integration with various underlying storage systems, including S3, HDFS, OSS, COS, and TOS. Please refer to the Storage Integration Overview.
With the operator, you can mount underlying storage by creating UnderFileSystem resources. An UnderFileSystem corresponds to a mount point for Alluxio. Regarding the Alluxio and the underlying storage namespace, please refer to Alluxio Namespace and Under File System Namespaces.
Below, we provide several examples of commonly used underlying storage mounts.
S3
Create the alluxio-operator/ufs.yaml file to specify the UFS configuration. The following example shows how to mount an S3 bucket to Alluxio:
To ensure that the Alluxio pods have access to NAS storage, you need to first mount the NAS to a path on the node. Alluxio operator supports mounting node local paths to Alluxio pods. Before creating the Alluxio cluster, you need to add the mount paths in alluxio-operator/alluxio-cluster.yaml. When the Alluxio cluster is started, these paths will be mounted into the Alluxio components.
The key is the host path on the node, and the value is the mounted path in the container
If using a NAS as the UFS, the same path needs to be mounted to the coordinator, workers and FUSE processes so that the FUSE can fall back if any error occurs
Create the alluxio-operator/ufs.yaml file to specify the UFS configuration. The following example shows how to mount a NAS or host path to Alluxio:
Originally, the user's training task accessed data by mounting a PVC to a specific path inside the container. The path inside the training task's container was bound to the PVC, allowing the task to access data via this mounted path.
Now, we're improving this process using Alluxio. When deploying the Alluxio cluster, you need to mount the training data's PVC (which was previously used for storing training data) to a path inside the Alluxio component's container. Then, this path inside the Alluxio component's container should be mounted to the Alluxio cluster. In this way, the training data's PVC is successfully mounted to the Alluxio cluster, allowing the data to be accessed and processed through Alluxio's interface.
you need to add the mount path in alluxio-cluster.yaml before creating the Alluxio cluster, mounting the existing PVC for training data to a path in the Alluxio components:
The key is the PVC, and the value is the mounted path in the container
If using a PVC as the UFS, the same path needs to be mounted to the coordinator, workers and FUSE processes so that the FUSE can fallback if any error occurs
Create the alluxio-operator/ufs.yaml file to specify the UFS configuration. The following example shows how to mount a PVC to Alluxio:
First, ensure that the Alluxio cluster is up and running with a Ready status. (Or if the status is WaitingForReady, can also mount UFS)
# check the status of the cluster$ kubectl get alluxioclusterNAME CLUSTERPHASE AGEalluxio Ready 2m18s
Execute the following command to create the UnderFileSystem resource and mount that to Alluxio namespace:
$ cd alluxio-operator$ kubectl create -f ufs.yamlunderfilesystem.k8s-operator.alluxio.com/alluxio-s3 created# verify the status of the storage$ kubectl get ufsNAME PHASE AGEalluxio-s3 Ready 46s# also check the mount table via Alluxio command line$ kubectl exec -it alluxio-coordinator-0 -- alluxio mount list 2>/dev/nullListing all mount pointss3://my-bucket/path/to/mount on /s3/ properties={s3a.secretKey=xxx, alluxio.underfs.s3.region=us-east-1, s3a.accessKeyId=xxx}
Monitoring
The Alluxio cluster enables monitoring by default. You can view various Alluxio metrics visually through Grafana. Please refer to the Monitoring and Metrics section on Kubernetes Operator.
Data Access Acceleration
In the steps above, you deployed the Alluxio cluster and mounted the under file system to Alluxio. Training tasks that read data through Alluxio can improve training speed and GPU utilization. Majorly, Alluxio provides three ways for applications to access data:
The container will never be able to access the resource over the limits, and the requests are used during scheduling. For more information, please refer to Resource Management for Pods and Containers
The limit of the memory should be a little bit over the sum of the heap size(-Xmx) and the direct memory size(-XX:MaxDirectMemorySize=10g) to avoid out-of-memory problems.
The key is the name of the ConfigMap, and the value if the mounted path in the container
The /opt/alluxio/conf is already mounted by default. The custom config maps need to mount to other paths
Use the root user
The FUSE pod will always use the root user. The other processes use the user with uid 1000 by default. In the container, the user is named alluxio. To change it to the root user, use this configuration:
Sometimes it’s enough to specify the .spec.fsGroup = 0 only when the files can be accessed by the root group
The ownership of the mounted host path, such as the page store path and log path, will be transferred to root if changing to the root user.
FAQ
ETCD pod stuck in pending status
For example, if three etcd pods remain in the Pending state, you can use kubectl describe pod to view detailed information:
# Check the status of the podskubectl get podNAME READY STATUS RESTARTS AGEalluxio-coordinator-0 0/1 Init:1/2 0 73salluxio-etcd-0 0/1 Pending 0 73salluxio-etcd-1 0/1 Pending 0 73salluxio-etcd-2 0/1 Pending 0 73salluxio-monitor-grafana-79db8c7dd9-lsq2l 1/1 Running 0 73salluxio-monitor-prometheus-7c6cbc4b4c-9nk25 1/1 Running 0 73salluxio-worker-8c79d5fd4-2c994 0/1 Init:1/2 0 73salluxio-worker-8c79d5fd4-jrchj 0/1 Init:1/2 0 73s# Check detailed information about the etcd podkubectl describe pod alluxio-etcd-0Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning FailedScheduling 3m57s default-scheduler 0/3 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/3 nodes are available: 3 Preemption is not helpful for scheduling., .
# Check the PVC Status in the Cluster# If you find that the etcd PVCs are stuck in the Pending state (note that the alluxio-alluxio-csi-fuse-pvc being in Pending state is normal), you can investigate further.
kubectl get pvcNAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGEalluxio-alluxio-csi-fuse-pvc Pending alluxio-csi-storage-class 5m31sdata-alluxio-etcd-0 Pending 3h41mdata-alluxio-etcd-1 Pending 3h41mdata-alluxio-etcd-2 Pending 3h41m# Check the PVC descriptionkubectl describe pvc data-alluxio-etcd-0Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal FailedBinding 4m16s (x889 over 3h44m) persistentvolume-controller no persistent volumes available for this claim and no storage class is set
Based on the error message, the etcd pods are stuck in the Pending state because no storage class is set. You can resolve this issue by specifying the storage class for etcd in the alluxio-operator/alluxio-cluster.yaml file:
Another issue is the etcd PVC specifies a storage class, but both the etcd pod and PVC remain in a pending state. For example, as shown in the detailed information of the PVC below, the storage class specified for the etcd PVC does not support dynamic provisioning, and the storage volume needs to be manually created by the cluster administrator.
# Check the PVC descriptionkubectl describe pvc data-alluxio-etcd-0Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal WaitForFirstConsumer 25s persistentvolume-controller waiting for first consumer to be created before binding
Normal ExternalProvisioning 8s (x3 over 25s) persistentvolume-controller Waiting for a volume to be created either by the external provisioner 'none' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
For similar issues where etcd pods remain in the Pending state, you can use the above method for troubleshooting.
alluxio-alluxio-csi-fuse-pvc in pending status
After creating the cluster, you might notice that alluxio-alluxio-csi-fuse-pvc is in the Pending status. This is normal. The PVC will automatically bind to a PV and its status will change to Bound when it is used by a client pod.
Unable to access public image registry
Configuring alluxio-operator image
Deploying the Alluxio operator requires pulling dependent images from an accessible image registry. If your network environment cannot access the public image registry, you will encounter a timeout error when pulling the images:
You may notice that the cluster controller, ufs controller and collectinfo controller have started successfully, but the csi controller and csi nodeplugin remain in the ContainerCreating state. This is due to a timeout while pulling the dependent images. By using kubectl describe pod to view detailed information, you will see error messages similar to the following:
$ kubectl -n alluxio-operator describe pod -l app.kubernetes.io/component=csi-controllerEvents: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 10m default-scheduler Successfully assigned alluxio-operator/alluxio-csi-controller-c85f8f759-sqc56 to cn-beijing.10.0.0.252
Normal AllocIPSucceed 10m terway-daemon Alloc IP 10.0.0.27/24 took 28.443992ms Normal Pulling 10m kubelet Pulling image "registry.xxx.com/alluxio/operator:2.0.0"
Normal Pulled 10m kubelet Successfully pulled image "registry.xxx.com/alluxio/operator:2.0.0" in 5.55s (5.55s including waiting)
Normal Created 10m kubelet Created container csi-controller Normal Started 10m kubelet Started container csi-controller Warning Failed 8m20s (x2 over 10m) kubelet Failed to pull image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": failed to pull and unpack image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": failed to resolve reference "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": failed to do request: Head "https://us-west2-docker.pkg.dev/v2/k8s-artifacts-prod/images/sig-storage/csi-provisioner/manifests/v2.0.5": dial tcp 142.251.8.82:443: i/o timeout
Warning Failed 8m20s (x3 over 10m) kubelet Error: ErrImagePull Warning Failed 7m40s (x5 over 10m) kubelet Error: ImagePullBackOff Warning Failed 6m56s (x2 over 9m19s) kubelet Failed to pull image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": rpc error: code = DeadlineExceeded desc = failed to pull and unpack image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": failed to resolve reference "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5": failed to do request: Head "https://us-west2-docker.pkg.dev/v2/k8s-artifacts-prod/images/sig-storage/csi-provisioner/manifests/v2.0.5": dial tcp 64.233.187.82:443: i/o timeout
Normal Pulling 5m29s (x5 over 10m) kubelet Pulling image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5"
Normal BackOff 30s (x28 over 10m) kubelet Back-off pulling image "registry.k8s.io/sig-storage/csi-provisioner:v2.0.5"
You can download the dependent images locally, upload them to your private image registry, and then modify the image addresses in the alluxio-operator.yaml file before redeploying the operator.
Move to the alluxio-operator directory and execute the following command to deploy the operator:
$ cd alluxio-operator# the last parameter is the directory to the helm chart, "." means the current directory$ helm install operator -f alluxio-operator.yaml .NAME: operatorLAST DEPLOYED: Wed May 15 17:32:34 2024NAMESPACE: defaultSTATUS: deployedREVISION: 1TEST SUITE: None# verify iftheoperatorisrunningasexpected$ kubectl get pod -n alluxio-operatorNAME READY STATUS RESTARTS AGEalluxio-cluster-controller-5647cc664d-lrx84 1/1 Running 0 14salluxio-collectinfo-controller-667b746fd6-hfzqk 1/1 Running 0 14salluxio-csi-controller-7bd66df6cf-7kh6k 2/2 Running 0 14salluxio-csi-nodeplugin-9cc9v 2/2 Running 0 14salluxio-csi-nodeplugin-fgs5z 2/2 Running 0 14salluxio-csi-nodeplugin-v22q6 2/2 Running 0 14salluxio-ufs-controller-5f6d7c4d66-drjgm 1/1 Running 0 14s
configuring Alluxio cluster image
Starting the Alluxio cluster also involves etcd and monitoring components. If you cannot access the public image registry, you need to replace the image addresses for etcd and monitoring components with those from your private image registry. Modify the image addresses in the alluxio-operator/alluxio-cluster.yaml file accordingly.