--- name: satellite-storage-ibm-vpc-block-csi-driver title: Configuring Block Storage for VPC CSI driver for Satellite storage description: Learn how to manage IBM VPC block data volumes using the Block Storage for VPC Container Storage Interface (CSI) Driver in IBM Cloud Satellite for satellite storage configurations, including block storage provisioning for your clusters. last-updated: 2026-08-03 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/satellite?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Configuring Block Storage for VPC CSI driver for Satellite storage {: #storage-ibm-vpc-block-csi-driver} Learn how to manage IBM VPC block data volumes using the Block Storage for VPC Container Storage Interface (CSI) [Driver](https://github.com/kubernetes-sigs/ibm-vpc-block-csi-driver){: external} in IBM Cloud Satellite for satellite storage configurations, including block storage provisioning for your clusters. {: shortdesc} The template is currently in beta. Do not use it for production workloads. {: beta} Before you can deploy storage templates to clusters in your location, make sure you set up Satellite Config by selecting the **Enable cluster admin access for Satellite Config** option in the console or including the `--enable-config-admin` option when you create your cluster. {: important} You cannot scope Satellite storage service to resource groups. However, if you are scoping other resources such as location and cluster to resource groups, you need to add Satellite reader and link administrator role for all resources in the account. {: note} ## Prerequisites for Block Storage for VPC {: #sat-storage-vpc-csi-prereq} 1. [Create a Satellite location](https://cloud.ibm.com/docs/satellite?topic=satellite-locations&format=markdown). 1. [Create an API key for access to your clusters](https://cloud.ibm.com/iam/apikeys){: external} There is currently an issue with autocomplete in some browsers. If you don't see the IAM API Key field on the **Secrets** tab, try clearing the search field or a different web browser. {: note} ## Creating and assigning a configuration in the console {: #ibm-vpc-block-csi-driver-config-create-console} {: ui} 1. Review the [parameter reference](#ibm-vpc-block-csi-driver-parameter-reference). 1. [From the Locations console](https://cloud.ibm.com/satellite/locations){: external}, select the location where you want to create a storage configuration. 1. Select **Storage** > **Create storage configuration** 1. Enter a name for your configuration. 1. Select the **Storage type**. 1. Select the **Version** and click **Next** 1. If the **Storage type** that you selected accepts custom parameters, enter them on the **Parameters** tab. 1. If the **Storage type** that you selected requires secrets, enter them on the **Secrets** tab. 1. On the **Storage classes** tab, review the storage classes that are deployed by the configuration or create a custom storage class. 1. On the **Assign to service** tab, select the service that you want to assign your configuration to. 1. Click **Complete** to assign your storage configuration. ## Creating a configuration in the CLI {: #ibm-vpc-block-csi-driver-config-create-cli} {: cli} 1. Review the [parameter reference](#ibm-vpc-block-csi-driver-parameter-reference) for the template version that you want to use. 1. Log in to the IBM Cloud CLI. ```sh ibmcloud login ``` {: pre} 1. List your Satellite locations and note the `Managed from` column. ```sh ibmcloud sat location ls ``` {: pre} 1. Target the `Managed from` region of your Satellite location. For example, for `wdc` target `us-east`. For more information, see [Satellite regions](https://cloud.ibm.com/docs/satellite?topic=satellite-sat-regions&format=markdown). ```sh ibmcloud target -r us-east ``` {: pre} 1. If you use a resource group other than `default`, target it. ```sh ibmcloud target -g RESOURCE_GROUP ``` {: pre} 1. Copy one of the following example command for the template version that you want to use. For more information about the command, see `ibmcloud sat storage config create` in the [command reference](https://cloud.ibm.com/docs/satellite?topic=satellite-satellite-cli-reference&format=markdown#storage-config-create-cli). Example command to create a version 5.1 configuration. ```sh ibmcloud sat storage config create --location LOCATION --name NAME --template-name ibm-vpc-block-csi-driver --template-version 5.1 --param "g2_token_exchange_endpoint_url=G2_TOKEN_EXCHANGE_ENDPOINT_URL" --param "g2_riaas_endpoint_url=G2_RIAAS_ENDPOINT_URL" --param "g2_resource_group_id=G2_RESOURCE_GROUP_ID" --param "g2_api_key=G2_API_KEY" ``` {: pre} 1. Customize the command based on the settings that you want to use. 1. Run the command to create a configuration. 1. Verify your configuration was created. ```sh ibmcloud sat storage config get --config CONFIG ``` {: pre} ## Creating a configuration in the API {: #ibm-vpc-block-csi-driver-config-create-api} {: api} 1. Generate an API key, then request a refresh token. For more information, see [Generating an IBM Cloud IAM token by using an API key](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey&format=markdown). 1. Review the [parameter reference](#ibm-vpc-block-csi-driver-parameter-reference) for the template version that you want to use. 1. Copy one of the following example requests and replace the variables that you want to use. Example request to create a version 5.1 configuration. ```sh curl -X POST "https://containers.cloud.ibm.com/global/v2/storage/satellite/createStorageConfigurationByController" -H "accept: application/json" -H "Authorization: TOKEN" -H "Content-Type: application/json" -d "{ \"config-name\": \"string\", \"controller\": \"string\", \"storage-class-parameters\": [ { \"additionalProp1\": \"string\", \"additionalProp2\": \"string\", \"additionalProp3\": \"string\" } ], \"storage-template-name\": \"ibm-vpc-block-csi-driver\", \"storage-template-version\": \"5.1\", \"update-assignments\": true, \"user-config-parameters\": { \"entry.name\": \"G2_TOKEN_EXCHANGE_ENDPOINT_URL\", { \"entry.name\": \"G2_RIAAS_ENDPOINT_URL\", { \"entry.name\": \"G2_RESOURCE_GROUP_ID\",\"user-secret-parameters\": { \"entry.name\": \"G2_API_KEY\",} ``` {: pre} {: cli} 1. List your storage configurations and make a note of the storage configuration that you want to assign to your clusters. ```sh ibmcloud sat storage config ls ``` {: pre} 1. Get the ID of the cluster, cluster group, or service that you want to assign storage to. To make sure that your cluster is registered with Satellite Config or to create groups, see [Setting up clusters to use with Satellite Config](https://cloud.ibm.com/docs/satellite?topic=satellite-setup-clusters-satconfig&format=markdown). {: tip} Example command to list cluster groups. ```sh ibmcloud sat group ls ``` {: pre} Example command to list clusters. ```sh ibmcloud oc cluster ls --provider satellite ``` {: pre} Example command to list Satellite services. ```sh ibmcloud sat service ls --location LOCATION ``` {: pre} 1. Assign your storage configuration to the cluster, group, or service that you retrieved earlier. For more information, see the `ibmcloud sat storage assignment create` [command](https://cloud.ibm.com/docs/satellite?topic=satellite-satellite-cli-reference&format=markdown#storage-assignment-create-cli). Example command to assign a configuration to a cluster group. ```sh ibmcloud sat storage assignment create --group GROUP --config CONFIG --name NAME ``` {: pre} Example command to assign a configuration to a cluster. ```sh ibmcloud sat storage assignment create --cluster CLUSTER --config CONFIG --name NAME ``` {: pre} Example command to assign a configuration to a service cluster. ```sh ibmcloud sat storage assignment create --service-cluster-id CLUSTER --config CONFIG --name NAME ``` {: pre} 1. Verify that your assignment is created. ```sh ibmcloud sat storage assignment ls (--cluster CLUSTER | --config CONFIG | --location LOCATION | --service-cluster-id CLUSTER) ``` {: pre} {: api} 1. Copy one of the following example requests. Example request to assign a [configuration to a cluster](https://cloud.ibm.com/apidocs/kubernetes/containers-v1-v2#createassignmentbycluster-satellite){: external}. ```sh curl -X POST "https://containers.cloud.ibm.com/global/v2/storage/satellite/createAssignmentByCluster" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d "{ \"channelName\": \"CONFIGURATION-NAME\", \"cluster\": \"CLUSTER-ID\", \"controller\": \"LOCATION-ID\", \"name\": \"ASSIGNMENT-NAME\"}" ``` {: pre} Example request to [assign configuration to a cluster group](https://cloud.ibm.com/apidocs/kubernetes/containers-v1-v2#createassignment-satellite){: external}. ```sh curl -X POST "https://containers.cloud.ibm.com/global/v2/storage/satellite/createAssignment" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d "{ \"channelName\": \"CONFIGURATION-NAME\", \"cluster\": \"string\", \"groups\": [ \"CLUSTER-GROUP\" ], \"name\": \"ASSIGNMENT-NAME\"}" ``` {: pre} 1. Replace the variables with your details and run the request. 1. Verify the assignment was created by listing your assignments. ```sh curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignments" -H "accept: application/json" -H "Authorization: Bearer TOKEN" ``` {: pre} {: ui} You can use the [Satellite console](https://cloud.ibm.com/satellite/locations){: external} to apply the latest patch updates to your assignments. 1. From the **Locations** page in the [Satellite console](https://cloud.ibm.com/satellite/locations){: external}, select your location. 1. Click the **Storage** tab to view your configurations. 1. Click the configuration you want to update. 1. Click information **Information** (i) icon to apply the latest revision or patch. 1. **Optional**: Enable automatic patch updates for your storage assignment. Enabling automatic patch updates ensures that your assignment always has the latest security fixes. If you enable automatic patch updates, you must still apply major updates manually. {: note} {: cli} Upgrade an assignment to use the latest storage template revision. 1. List your Satellite storage assignments, make a note of the Satellite assignment you want to upgrade. ```sh ibmcloud sat storage assignment ls ``` {: pre} 1. List the Satellite storage templates to see the latest available versions. ```sh ibmcloud sat storage template ls ``` {: pre} 1. Upgrade the Satellite assignment. Example command to upgrade an assignment. ```sh ibmcloud sat storage assignment upgrade --assignment ASSIGNMENT ``` {: pre} {: cli} You can use the `sat storage assignment autopatch enable` CLI to enable automatic patch updates for your assignments. Enabling automatic patch updates applies the latest storage template revisions (patches) automatically. You must still apply major updates manually. 1. List your Satellite storage configurations. Make a note of the configuration ID. ```sh ibmcloud sat storage assignment ls ``` {: pre} 1. Run one of the following example commands to enable automatic patch updates for your configuration and its associated assignments. Enter the configuration ID that you retrieved in the previous step. Example command to enable automatic patch updates for an assignment. ```sh ibmcloud sat storage assignment autopatch enable --config CONFIG (--all | --assignment ASSIGNMENT-ID [--assignment ASSIGNMENT-ID]) ``` {: pre} Example command to enable automatic patch updates for all storage assignments under a given configuration. ```sh ibmcloud sat storage assignment autopatch enable --config CONFIG --all ``` {: pre} Example command to disable automatic patch updates for all assignments under a specific configuration. ```sh ibmcloud sat storage assignment autopatch disable --config CONFIG --all ``` {: pre} Example command to disable automatic patch updates for an single assignment and a specific configuration. ```sh ibmcloud sat storage assignment autopatch disable --config CONFIG --assignment ASSIGNMENT-ID ``` {: pre} Example command to disable automatic patch updates for an multiple assignment and a specific configuration. ```sh ibmcloud sat storage assignment autopatch disable --config CONFIG --assignment ASSIGNMENT-ID --assignment ASSIGNMENT-ID ``` {: pre} {: api} You can use the [`/v2/storage/satellite/updateAssignment`](https://cloud.ibm.com/apidocs/kubernetes/containers-v1-v2#updateassignment-storage){: external} API to update your assignments with new clusters or cluster groups. Set `updateConfigVersion` to `true` to apply the revision update. 1. Copy the following example request and replace the variables for the cluster groups and assignments that you want to update. ```sh curl -X PATCH "https://containers.cloud.ibm.com/global/v2/storage/satellite/updateAssignment" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d "{ \"groups\": [ \"CLUSTER-GROUPS\" ], \"name\": \"ASSIGNMENT-NAME\", \"updateConfigVersion\": true, \"uuid\": \"ASSIGNMENT-ID\"}" ``` {: pre} 1. Run the request. 1. Get the details of you assignment to verify the update. ```txt curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignment?uuid=ASSIGNMENT-ID" -H "accept: application/json" -H "Authorization: Bearer TOKEN" ``` {: pre} {: api} You can use the `/v2/storage/satellite/setAssignmentAutoupgrade` API to enable automatic patch updates for your assignments. Enabling automatic patch updates applies the latest storage template revisions (patches) automatically. You must still apply major updates manually. 1. Copy the following example request and replace the variables for the cluster groups and assignments that you want to update. ```txt curl -X PATCH "https://containers.cloud.ibm.com/global/v2/storage/satellite/setAssignmentAutoupgrade" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d { "config": "string", "controller": "string", "autopatch": boolean,"assignment" : { "all": boolean, "uuid": ["string", "string", ...], } } ``` {: pre} 1. Run the request. 1. Get the details of you assignment to verify the upgrade. ```sh curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignment?uuid=ASSIGNMENT-ID" -H "accept: application/json" -H "Authorization: Bearer TOKEN" ``` {: pre} ## Deploying an app that uses Block Storage for VPC {: #sat-storage-vpc-deploy-app} You can use the `ibm-vpc-block-csi-driver` to create PVCs that you can use in your cluster workloads. {: shortdesc} 1. Create a PVC that references a VPC storage class that you created earlier. ```yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: my-pvc spec: storageClassName: ibmc-vpc-block-5iops-tier accessModes: - ReadWriteOnce resources: requests: storage: 10Gi ``` {: codeblock} 1. Create the PVC in your cluster. ```sh oc apply -f pvc.yaml ``` {: pre} 1. Create a YAML configuration file for a pod that mounts the PVC that you created. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-deployment labels: app: my-app spec: replicas: 1 selector: matchLabels: app: my-app template: metadata: labels: app: my-app spec: containers: - name: my-container image: ngnix volumeMounts: name: my-volume mountPath: /mount-path volumes: name: my-volume persistentVolumeClaim: null claimName: my-pvc ``` {: codeblock} 1. Create the pod in your cluster. ```sh oc apply -f deployment.yaml ``` {: pre} 1. Verify that the pod is deployed. Note that it might take a few minutes for your app to get into a `Running` state. ```sh oc get pods ``` {: pre} ```sh NAME READY STATUS RESTARTS AGE my-deployment 1/1 Running 0 2m58s ``` {: screen} 1. Verify that the app can write to your block storage volume by logging in to your pod. ```sh oc exec my-deployment ``` {: pre} 1. View the contents of the `outfile` file to confirm that your app can write data to your persistent storage. ```sh cat / ``` {: pre} Example output ```sh Fri Jul 16 07:49:39 EDT 2021 Fri Jul 16 07:49:39 EDT 2021 Fri Jul 16 07:49:39 EDT 2021 ``` {: screen} 1. Exit the pod. ```sh exit ``` {: pre} ## Removing Block Storage for VPC storage from your apps {: #vpc-csi-rm-apps} If you no longer need your Block Storage for VPC configuration, you can remove your apps, PVCs, PVs, and assignment from your clusters. {: shortdesc} 1. List your PVCs and note the name of the PVC that you want to remove. ```sh oc get pvc ``` {: pre} 1. Remove any pods that mount the PVC. 1. List all the pods that currently mount the PVC that you want to delete. If no pods are returned, you do not have any pods that currently use your PVC. ```sh oc get pods --all-namespaces -o=jsonpath='{range .items[*]}{"\n"}{.metadata.name}{":\t"}{range .spec.volumes[*]}{.persistentVolumeClaim.claimName}{" "}{end}{end}' | grep "" ``` {: pre} Example output ```sh app ibmc-vpc-block-metro-5iops-tier ``` {: screen} 1. Remove the pod that uses the PVC. If the pod is part of a deployment or statefulset, remove the deployment or statefulset. ```sh oc delete pod ``` {: pre} ```sh oc delete deployment ``` {: pre} ```sh oc delete statefulset ``` {: pre} 1. Verify that the pod, deployment, or statefulset is removed. ```sh oc get pods ``` {: pre} ```sh oc get deployments ``` {: pre} ```sh oc get statefulset ``` {: pre} 1. Delete the PVC. ```sh oc delete pvc ``` {: pre} 1. Verify that your PV is automatically removed. ```sh oc get pv ``` {: pre} ## Removing the Block Storage for VPC storage configuration from your cluster {: #vpc-csi-template-rm} If you no longer plan on using your Block Storage for VPC in your cluster, you can use the CLI unassign your cluster from the storage configuration. {: shortdesc} Note that if you remove the storage configuration, the driver is then uninstalled from all assigned clusters. Your PVCs, PVs, and data are not removed. However, you might not be able to access your data until you re-install the driver in your cluster again. {: important} ### Removing the Block Storage for VPC storage configuration using the console {: #vpc-csi-rm-ui} {: ui} 1. From the Satellite storage dashboard, select the storage configuration you want to delete. 1. Select **Actions** > **Delete** 1. Enter the name of your storage configuration. 1. Select **Delete**. ### Removing the Block Storage for VPC storage configuration using the cli {: #vpc-csi-rm-cli} {: cli} 1. List your storage assignments and find the one that you used for your cluster. ```sh ibmcloud sat storage assignment ls (--cluster CLUSTER | --config CONFIG | --location LOCATION | --service-cluster-id CLUSTER) ``` {: pre} 2. Remove the assignment. After the assignment is removed, the driver pods and storage classes are removed from all clusters that were part of the storage assignment. ```sh ibmcloud sat storage assignment rm --assignment ``` {: pre} 3. Verify that the driver is removed from your cluster. 1. List of the storage classes in your cluster and verify that the storage classes are removed. ```sh oc get sc ``` {: pre} 2. List the pods in the `kube-system` namespace and verify that the storage driver pods are removed. ```sh oc get pods -n kube-system | grep vpc ``` {: pre} 4. Optional: Remove the storage configuration. 1. List the storage configurations. ```sh ibmcloud sat storage config ls ``` {: pre} 2. Remove the storage configuration. ```sh ibmcloud sat storage config rm --config ``` {: pre} ## Parameter reference {: #ibm-vpc-block-csi-driver-parameter-reference} ### 5.1 parameter reference {: #ibm-vpc-block-csi-driver-5.1-parameters} | Display name | CLI option | Type | Description | Default value | | --- | --- | --- | --- | --- | | IAM endpoint | `g2_token_exchange_endpoint_url` | Config | The IAM endpoint. For example 'https://iam.cloud.ibm.com'. | N/A | | VPC IaaS endpoint | `g2_riaas_endpoint_url`| Config | The VPC regional endpoint of your VPC cluster in the format`https://region.iaas.cloud.ibm.com`. Example:`https://eu-de.iaas.cloud.ibm.com`. For more information, see https://ibm.biz/vpc-endpoints | N/A | | Resource group ID | `g2_resource_group_id` | Config | The ID of the resource group where your VPC is located. You can find your resource group by running the 'ibmcloud is vpc VPC-ID' command and note the Resource group field. | N/A | | IAM API key | `g2_api_key` | Secret | The IAM API key of account where your VPC is located. You can use your existing API key or you can create an API key by running the 'ibmcloud iam api-key-create NAME' command. | N/A | {: caption="Table 1. 5.1 parameter reference" caption-side="bottom"} ## Storage class reference for Block Storage for VPC {: #sat-storage-vpc-ref} Review the Satellite storage classes for IBM VPC block storage. You can describe storage classes in the command line with the `oc describe sc ` command. {: shortdesc} Storage class name | Default Read IOPS per GB | Default Write IOPS per GB | Size range (per disk) | Hard disk | Reclaim policy | Volume Binding Mode | | --- | --- | --- | --- | --- | --- | --- | | `sat-vpc-block-gold-metro` **Default** | 10 | 10 | 10 GB - 4 TB | SSD | Delete | WaitForFirstConsumer | | `ibmc-vpc-block-metro-5iops-tier` | 5 | 5 | 10 GB - 9600 GB | SSD | Delete | WaitForFirstConsumer | | `ibmc-vpc-block-metro-custom` | Custom | Custom | Based on IOPS | SSD | Delete | WaitForFirstConsumer | | `ibmc-vpc-block-metro-general-purpose` | 3 | 3 | 10 GB - 16 TB | SSD | Delete | WaitForFirstConsumer | | `ibmc-vpc-block-metro-retain-10iops-tier` | 10 | 10 | 10 GB - 4 TB | SSD | Retain | WaitForFirstConsumer | | `ibmc-vpc-block-metro-retain-5iops-tier` | 5 | 5 | 10 GB - 9600 GB | SSD | Retain | WaitForFirstConsumer | | `ibmc-vpc-block-metro-retain-custom` | Custom | Custom | Based on IOPS | SSD | Retain | WaitForFirstConsumer | | `ibmc-vpc-block-metro-retain-general-purpose` | 3 | 3 | 10 GiB - 16 TB | SSD | Retain | WaitForFirstConsumer | {: caption="Storage class reference for IBM Block Storage for VPC" caption-side="bottom"} ## Getting help and support for Block Storage for VPC {: #sat-vpc-csi-support} 1. Review the FAQs in the [Block Storage for VPC docs](https://cloud.ibm.com/docs/vpc?topic=vpc-block-storage-vpc-faq&format=markdown). 1. Review the [troubleshooting documentation](https://cloud.ibm.com/docs/satellite?topic=satellite-storage-must-gather&format=markdown) to troubleshoot and resolve common issues. 1. Check the status of the IBM Cloud platform and resources by going to the [Status page](https://cloud.ibm.com/status){: external}. 1. Review [Stack Overflow](https://stackoverflow.com/questions/tagged/ibm-cloud){: external} to see whether other users experienced the same problem. Tag any questions with ibm-cloud and Block Storage for VPC, so that it's seen by the IBM Cloud development teams. 1. If you run into an issue with Block Storage for VPC submit a support request with [IBM Cloud® Support](https://www.ibm.com/products/cloud/support){: external}.