Console
    Contact Us Start free

    Create and connect to a Parallelstore instance from Google Kubernetes Engine

    Parallelstore is available by invitation only. If you'd like to request access to Parallelstore in your Google Cloud project, contact your sales representative.

    This guide describes how you can create a new Kubernetes volume backed by a Parallelstore CSI driver in GKE with dynamic provisioning . This lets you create storage backed by fully managed Parallelstore instances on-demand, and access them as volumes for your stateful workloads.

    Before you begin

    Before you start, make sure that you have performed the following tasks:

    • Enable the Parallelstore API and the Google Kubernetes Engine API.
      • Enable APIs
    • If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update .

    Create a new volume using the Parallelstore CSI driver

    The following sections describe the typical process for creating a Kubernetes volume backed by a Parallelstore CSI driver in GKE:

    1. (Optional) Create a StorageClass .
    2. Use a PersistentVolumeClaim to access the volume .
    3. (Optional) Configure resources for the sidecar container .
    4. Create a workload that consumes the volume .

    (Optional) Create a storage class

    When the Parallelstore CSI driver is enabled, GKE automatically creates a StorageClass named parallelstore-rwx for provisioning Parallelstore instances. This StorageClass directs the CSI driver to provision Parallelstore instances in the same region as your GKE cluster to ensure optimal I/O performance.

    Optionally, you can create a custom StorageClass with a specific topology. To do so, follow these steps:

    1. Save the following StorageClass manifest in a file named parallelstore-class.yaml :

      Pod mount

        apiVersion 
 : 
  
 storage.k8s.io/v1 
 kind 
 : 
  
 StorageClass 
 metadata 
 : 
  
 name 
 : 
  
 parallelstore-class 
 provisioner 
 : 
  
 parallelstore.csi.storage.gke.io 
 volumeBindingMode 
 : 
  
 Immediate 
 reclaimPolicy 
 : 
  
 Delete 
 allowedTopologies 
 : 
 - 
  
 matchLabelExpressions 
 : 
  
 - 
  
 key 
 : 
  
 topology.gke.io/zone 
  
 values 
 : 
  
  LOCATION

      Replace the following:

      • LOCATION : the Compute Engine zone containing the cluster. You must specify a supported zone for the Parallelstore CSI driver.

      For the full list of fields that are supported in the StorageClass, refer to the Parallelstore CSI reference documentation .

      Node mount

      The Parallelstore CSI driver lets you mount volumes directly on your nodes. Node mount is supported on GKE clusters version 1.32.3 and later.

      Node-level mounting allows all Pods on a node to share the same mount point. Sharing the same mount point improves scalability because the number of mounts increases with the number of nodes, not the number of Pods (as with the sidecar mode).

      As a result, you can run more Pods while sharing the same Parallelstore instance.

      Note:This feature is enabled by specifying the mountLocality: nodeparameter. The default value for Pod mount locality is mountLocality: pod. The dfuse CPU, memory requests, and limit flags work only with the mountLocality: nodesetting.

      If either the value of the request or the limit is set and the other is unset, they will both be set to the same, specified value.

      You can use `'0'` as the value to unset any resource limits. For example, dfuseMemoryLimit: '0'removes the memory limit for the dfuse process.
         
 apiVersion 
 : 
  
 storage.k8s.io/v1 
  
 kind 
 : 
  
 StorageClass 
  
 metadata 
 : 
  
 name 
 : 
  
 parallelstore-class 
  
 provisioner 
 : 
  
 parallelstore.csi.storage.gke.io 
  
 volumeBindingMode 
 : 
  
 Immediate 
  
 reclaimPolicy 
 : 
  
 Delete 
  
 allowedTopologies 
 : 
  
 - 
  
 matchLabelExpressions 
 : 
  
 - 
  
 key 
 : 
  
 topology.gke.io/zone 
  
 values 
 : 
  
  LOCATION 
 
  
 parameters 
 : 
  
 mountLocality 
 : 
  
 node 
  
 dfuseCPURequest 
 : 
  
  DFUSE_CPU_REQUEST 
 
  
 dfuseMemoryRequest 
 : 
  
  DFUSE_MEMORY_REQUEST 
 
  
 dfuseCPULimit 
 : 
  
  DFUSE_CPU_LIMIT 
 
  
 dfuseMemoryLimit 
 : 
  
  DFUSE_MEMORY_LIMIT

      Replace the following:

      • LOCATION : the Compute Engine zone containing the cluster. You must specify a supported zone for the Parallelstore CSI driver.
      • DFUSE_CPU_REQUEST : the CPU request for the dfuse process. The default is 250m .
      • DFUSE_MEMORY_REQUEST : the memory request for the dfuse process. The default is 512Mi .
      • DFUSE_CPU_LIMIT : the CPU limit for the dfuse process. The default is unset.
      • DFUSE_MEMORY_LIMIT : the memory limit for the dfuse process. The default is 10Gi .

      For the full list of fields that are supported in the StorageClass, refer to the Parallelstore CSI reference documentation .

    2. Create the StorageClass by running this command:

       kubectl  
create  
-f  
parallelstore-class.yaml

    Use a PersistentVolumeClaim to access the volume

    You can create a PersistentVolumeClaim resource that references the Parallelstore CSI driver's StorageClass.

    The following manifest file shows an example of how to create a PersistentVolumeClaim in ReadWriteMany access mode that references the StorageClass you created earlier.

    1. Save the following manifest in a file named parallelstore-pvc.yaml :

         
 apiVersion 
 : 
  
 v1 
  
 kind 
 : 
  
 PersistentVolumeClaim 
  
 metadata 
 : 
  
 name 
 : 
  
 parallelstore-pvc 
  
 spec 
 : 
  
 accessModes 
 : 
  
 - 
  
 ReadWriteMany 
  
 resources 
 : 
  
 requests 
 : 
  
 storage 
 : 
  
  STORAGE_SIZE 
 
  
 storageClassName 
 : 
  
 parallelstore-class

      Replace STORAGE_SIZE with the storage size; for example, 12000Gi . The value must be in the range from 12,000 GiB to 100,000 GiB (in multiples of 4,000 GiB).

    2. Create the PersistentVolumeClaim by running this command:

         
kubectl  
create  
-f  
parallelstore-pvc.yaml

    (Optional) Configure resources for the sidecar container

    Note:You can only configure resources for the sidecar container if you use the Pod mount locality, that is, the mountLocalityvolume attribute in your PersistentVolume is either unset or set to pod

    When you create a workload Pod that uses Parallelstore-backed volumes, the CSI driver determines whether your volume is based on Parallelstore instances.

    If the driver detects that your volume is Parallelstore-based, or if you specify the annotation gke-parallelstore/volumes: "true" , the CSI driver automatically injects a sidecar container named gke-parallelstore-sidecar into your Pod. This sidecar container mounts the Parallelstore instance to your workload.

    By default, GKE configures the sidecar container with the following resource requests, with resource limits unset:

    • 250 m CPU
    • 512 MiB memory
    • 10 MiB ephemeral storage

    To overwrite these values, you can optionally specify the annotation gke-parallelstore/[cpu-request|memory-request|cpu-limit|memory-limit|ephemeral-storage-request] as shown in the following example:

      apiVersion 
 : 
  
 v1 
 kind 
 : 
  
 Pod 
 metadata 
 : 
  
 annotations 
 : 
  
 gke-parallelstore/volumes 
 : 
  
 "true" 
  
 gke-parallelstore/cpu-request 
 : 
  
 500m 
  
 gke-parallelstore/memory-request 
 : 
  
 1Gi 
  
 gke-parallelstore/ephemeral-storage-request 
 : 
  
 500Mi 
  
 gke-parallelstore/cpu-limit 
 : 
  
 1000m 
  
 gke-parallelstore/memory-limit 
 : 
  
 2Gi 
  
 gke-parallelstore/ephemeral-storage-limit 
 : 
  
 1Gi

    Use the following considerations when deciding the amount of resources to allocate:

    • If one of the request or limit values is set and another is unset, they will both be set to the same, specified value.
    • Allocate more CPU to the sidecar container if your workloads need higher throughput. Insufficient CPU will cause I/O throttling.
    • You can use "0" as the value to unset any resource limits on Standard clusters; for example, gke-parallelstore/memory-limit: "0" removes the memory limit for the sidecar container. This is useful when you cannot decide on the amount of resources gke-parallelstore-sidecar needs for your workloads, and want to let the sidecar consume all the available resources on a node.

    Create a workload that consumes the volume

    This section shows an example of how to create a Pod that consumes the PersistentVolumeClaim resource you created earlier.

    Multiple Pods can share the same PersistentVolumeClaim resource.

    1. Save the following manifest in a file named my-pod.yaml .

         
 apiVersion 
 : 
  
 v1 
  
 kind 
 : 
  
 Pod 
  
 metadata 
 : 
  
 name 
 : 
  
 my-pod 
  
 spec 
 : 
  
 containers 
 : 
  
 - 
  
 name 
 : 
  
 nginx 
  
 image 
 : 
  
 nginx 
  
 volumeMounts 
 : 
  
 - 
  
 name 
 : 
  
 parallelstore-volume 
  
 mountPath 
 : 
  
 /data 
  
 volumes 
 : 
  
 - 
  
 name 
 : 
  
 parallelstore-volume 
  
 persistentVolumeClaim 
 : 
  
 claimName 
 : 
  
 parallelstore-pvc

    2. Run the following command to apply the manifest to the cluster.

         
kubectl  
apply  
-f  
my-pod.yaml

      The Pod will wait until the PersistentVolumeClaim is provisioned before it starts running. This operation might take several minutes to complete.

    Manage the Parallelstore CSI driver

    This section covers how you can enable and disable the Parallelstore CSI driver, if needed.

    Enable the Parallelstore CSI driver on a new cluster

    To enable the Parallelstore CSI driver when creating a new Standard cluster, run the following command with the Google Cloud CLI:

     gcloud  
container  
clusters  
create  
 CLUSTER_NAME 
  
 \ 
  
--location = 
 LOCATION 
  
 \ 
  
--network = 
 NETWORK_NAME 
  
 \ 
  
--addons = 
ParallelstoreCsiDriver  
 \ 
  
--cluster-version = 
 VERSION

    Replace the following:

    • CLUSTER_NAME : the name of your cluster.
    • LOCATION : the Compute Engine zone containing the cluster. You must specify a supported zone for the Parallelstore CSI driver.
    • NETWORK_NAME : name of the VPC network you created in Configure a VPC network .
    • VERSION : the GKE version number. You must specify a supported version number to use this feature, such as GKE version 1.29 or later. Alternatively, you can use the --release-channel flag and specify a release channel .

    Enable the Parallelstore CSI driver on an existing cluster

    To enable the driver on an existing GKE Standard cluster, run the following command with the Google Cloud CLI:

      gcloud container clusters update CLUSTER_NAME 
\ 
  
 --location= LOCATION 
\ 
  
 --update-addons=ParallelstoreCsiDriver=ENABLED

    Replace the following:

    • CLUSTER_NAME : the name of your cluster.
    • LOCATION : the Compute Engine zone containing the cluster. You must specify a supported zone for the Parallelstore CSI driver.

    Make sure that your GKE cluster is running in the same VPC network that you set up in Configure a VPC network . To verify the VPC network for a GKE cluster, you can check in the Google Cloud console, or through the command gcloud container clusters describe $(CLUSTER) --format="value(networkConfig.network)" --location=$(LOCATION) .

    Disable the Parallelstore CSI driver

    You can disable the Parallelstore CSI driver on an existing Autopilot or Standard cluster by using the Google Cloud CLI.

      gcloud container clusters update CLUSTER_NAME 
\ 
  
 --location= LOCATION 
\ 
  
 --update-addons=ParallelstoreCsiDriver=DISABLED

    Replace the following:

    • CLUSTER_NAME : the name of your cluster.
    • LOCATION : the Compute Engine zone containing the cluster. You must specify a supported zone for the Parallelstore CSI driver.

    Use fsGroup with Parallelstore volumes

    The Parallelstore CSI driver supports changing the group ownership of the root level directory of the mounted file system to match a user-requested fsGroup specified in the Pod's SecurityContext . This feature is only supported in GKE clusters version 1.29.5 or later, or version 1.30.1 or later.

    Troubleshooting

    For troubleshooting guidance, refer to the Troubleshooting page in the Parallelstore documentation.

    What's next
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: