IBM Cloud Object Storage Driver

You can use the IBM Cloud Object Storage driver template to create and access data in multiple s3 storage providers such as IBM, AWS, Wasabi, Azure, and more. Review the following steps to deploy the IBM Cloud Object Storage driver to your Satellite clusters.

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.

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.

Prerequisites

Create a Satellite location.
Create a set of service credentials in your object storage provider.
Create a secret that contains your s3 credentials.

Creating a secret in your cluster that contains your object storage credentials

Create the Kubernetes secret in your cluster that contains your service credentials.

Follow the steps based on your object storage provider to create a secret in your cluster. When you create your secret, all values are automatically encoded to base64. In the following example, the secret name is cos-write-access.

IBM Cloud Object Storage

Find your service instance ID.

ibmcloud resource service-instance <service_name> | grep GUID

Create the secret in your cluster.

oc create secret generic cos-write-access --type=ibm/ibmc-s3fs --from-literal=api-key=API-KEY --from-literal=service-instance-id=SERVICE-INSTANCE-ID

AWS or Wasabi

oc create secret generic cos-write-access --type=ibm/ibmc-s3fs --from-literal=access-key=ACCESS-KEY-ID --from-literal=secret-key=SECRET-ACCESS-KEY

Creating and assigning a configuration in the console

Review the parameter reference.
From the Locations console, select the location where you want to create a storage configuration.
Select Storage > Create storage configuration
Enter a name for your configuration.
Select the Storage type.
Select the Version and click Next
If the Storage type that you selected accepts custom parameters, enter them on the Parameters tab.
If the Storage type that you selected requires secrets, enter them on the Secrets tab.
On the Storage classes tab, review the storage classes that are deployed by the configuration or create a custom storage class.
On the Assign to service tab, select the service that you want to assign your configuration to.
Click Complete to assign your storage configuration.

Creating a configuration in the CLI

Review the parameter reference for the template version that you want to use.
Log in to the IBM Cloud CLI.
```
ibmcloud login
```
List your Satellite locations and note the Managed from column.
```
ibmcloud sat location ls
```
Target the Managed from region of your Satellite location. For example, for wdc target us-east. For more information, see Satellite regions.
```
ibmcloud target -r us-east
```
If you use a resource group other than default, target it.
```
ibmcloud target -g <resource-group>
```

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.

Example command to create a version 2.2 configuration.

ibmcloud sat storage config create --location LOCATION --name NAME --template-name ibm-object-storage-plugin --template-version 2.2 --param "helm-release-name=HELM-RELEASE-NAME"  [--param "parameters=PARAMETERS"]  --param "license=LICENSE"  [--param "s3provider=S3PROVIDER"]  --param "cos-storageclass=COS-STORAGECLASS"  [--param "cos-endpoint=COS-ENDPOINT"]

Customize the command based on the settings that you want to use.
Run the command to create a configuration.

Verify your configuration was created.

ibmcloud sat storage config get --config CONFIG

Creating a configuration in the API

Generate an API key, then request a refresh token. For more information, see Generating an IBM Cloud IAM token by using an API key.
Review the parameter reference for the template version that you want to use.

Copy one of the following example requests and replace the variables that you want to use.

Example request to create a version 2.2 configuration.

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-object-storage-plugin\", \"storage-template-version\": \"2.2\", \"update-assignments\": true, \"user-config-parameters\": { \"entry.name\": \"HELM-RELEASE-NAME\", { \"entry.name\": \"PARAMETERS\", { \"entry.name\": \"LICENSE\", { \"entry.name\": \"S3PROVIDER\", { \"entry.name\": \"COS-STORAGECLASS\", { \"entry.name\": \"COS-ENDPOINT\",\"user-secret-parameters\": }

Creating a storage assignment in the console

If you didn't assign your configuration to a cluster or service when you created it, you can create an assignment by completing the following steps.

Open the Satellite console in your browser.
Select the location where you created your storage configuration.
Click the Locations tab, then click Storage.
Click the storage configuration that you want to assign to a cluster group.
On the Configuration details page, click Create storage assignment.
In the Create an assignment pane, enter a name for your assignment.
From the Version drop-down list, select the storage configuration version that you want to assign.
Click Create to create the assignment.
Verify that your storage configuration is deployed to your cluster.
1. From the Satellite console, navigate to your Location and select Storage
2. Click the storage configuration that you created and review the Assignments tab.
3. Click the Assignment that you created and review the Rollout status for your configuration.

Creating an assignment in the CLI

List your storage configurations and make a note of the storage configuration that you want to assign to your clusters.
```
ibmcloud sat storage config ls
```
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.

Example command to list cluster groups.
```
ibmcloud sat group ls
```
Example command to list clusters.
```
ibmcloud oc cluster ls --provider satellite
```
Example command to list Satellite services.
```
ibmcloud sat service ls --location <location>
```
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.

Example command to assign a configuration to a cluster group.
```
ibmcloud sat storage assignment create --group GROUP --config CONFIG --name NAME
```
Example command to assign a configuration to a cluster.
```
ibmcloud sat storage assignment create --cluster CLUSTER --config CONFIG --name NAME
```
Example command to assign a configuration to a service cluster.
```
ibmcloud sat storage assignment create --service-cluster-id CLUSTER --config CONFIG --name NAME
```

Verify that your assignment is created.

ibmcloud sat storage assignment ls (--cluster CLUSTER | --config CONFIG | --location LOCATION | --service-cluster-id CLUSTER)

Creating a storage assignment in the API

Copy one of the following example requests.

Example request to assign a configuration to a cluster.

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\"}"

Example request to assign configuration to a cluster group.

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\"}"

Replace the variables with your details and run the request.

Verify the assignment was created by listing your assignments.

curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignments" -H "accept: application/json" -H "Authorization: Bearer TOKEN"

Updating storage assignments in the console

You can use the Satellite console to apply the latest patch updates to your assignments.

From the Locations page in the Satellite console, select your location.
Click the Storage tab to view your configurations.
Click the configuration you want to update.
Click information Information (i) icon to apply the latest revision or patch.
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.

Manually upgrading assignments in the CLI

Upgrade an assignment to use the latest storage template revision.

List your Satellite storage assignments, make a note of the Satellite assignment you want to upgrade.
```
ibmcloud sat storage assignment ls
```
List the Satellite storage templates to see the latest available versions.
```
ibmcloud sat storage template ls
```
Upgrade the Satellite assignment.

Example command to upgrade an assignment.
```
ibmcloud sat storage assignment upgrade --assignment ASSIGNMENT
```

Enabling automatic patch updates for configurations and assignments in the 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.

List your Satellite storage configurations. Make a note of the configuration ID.
```
ibmcloud sat storage assignment ls
```
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.
```
ibmcloud sat storage assignment autopatch enable --config CONFIG  (--all | --assignment ASSIGNMENT-ID [--assignment ASSIGNMENT-ID])
```
Example command to enable automatic patch updates for all storage assignments under a given configuration.
```
ibmcloud sat storage assignment autopatch enable --config CONFIG --all
```
Example command to disable automatic patch updates for all assignments under a specific configuration.
```
ibmcloud sat storage assignment autopatch disable --config CONFIG --all
```
Example command to disable automatic patch updates for an single assignment and a specific configuration.
```
ibmcloud sat storage assignment autopatch disable --config CONFIG --assignment ASSIGNMENT-ID
```
Example command to disable automatic patch updates for an multiple assignment and a specific configuration.
```
ibmcloud sat storage assignment autopatch disable --config CONFIG --assignment ASSIGNMENT-ID --assignment ASSIGNMENT-ID
```

Upgrading a configuration and assignments in the API

You can use the /v2/storage/satellite/updateAssignment API to update your assignments with new clusters or cluster groups. Set updateConfigVersion to true to apply the revision update.

Copy the following example request and replace the variables for the cluster groups and assignments that you want to update.

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\"}"

Run the request.

Get the details of you assignment to verify the update.

curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignment?uuid=ASSIGNMENT-ID" -H "accept: application/json" -H "Authorization: Bearer TOKEN"

Enabling automatic patch updates for assignments in the 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.

Copy the following example request and replace the variables for the cluster groups and assignments that you want to update.

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", ...], } }

Run the request.

Get the details of you assignment to verify the upgrade.

curl -X GET "https://containers.cloud.ibm.com/global/v2/storage/satellite/getAssignment?uuid=ASSIGNMENT-ID" -H "accept: application/json" -H "Authorization: Bearer TOKEN"

Deploying an app that uses IBM Cloud Object Storage

You can use the ibm-object-s3fs driver to create PVCs that you can use in your cluster workloads.

Create a PVC that references your object storage configuration.

kind: PersistentVolumeClaim
apiVersion: v1
metadata: 
  name: demo #Enter a name for your PVC.
  namespace: default
  annotations: 
  ibm.io/auto-create-bucket: "false"
  ibm.io/auto-delete-bucket: "false" 
  ibm.io/bucket: BUCKET-NAME #Enter the name of your object storage bucket.
  ibm.io/secret-name: SECRET-NAME #Enter the name of the secret you created earlier.
  ibm.io/secret-namespace: NAMESPACE #Enter the namespace where you want to create the PVC.
spec: 
    accessModes:
    - ReadWriteOnce
    resources:
        requests:
            storage: 10Gi
    storageClassName: ibmc-s3fs-cos #The storage class that you want to use.

Create the PVC in your cluster.
```
oc apply -f pvc-cos.yaml
```

Create a YAML configuration file for a pod that mounts the PVC that you create.

apiVersion: v1
kind: Pod
metadata:
  name: demo-pod
  namespace: default
spec:
  securityContext:
    runAsUser: 2000
    fsGroup: 2000
  volumes:
  - name: demo-vol
    persistentVolumeClaim:
        claimName: demo
  containers:
  - name: test
    image: nginxinc/nginx-unprivileged
    imagePullPolicy: Always
    volumeMounts:
    - name: demo-vol
      mountPath: /mnt/cosvol

Create the pod in your cluster.
```
oc apply -f demo-pod.yaml
```

Verify that the pod is deployed. Note that it might take a few minutes for your app to get into a Running state.

oc get pods

NAME                                READY   STATUS    RESTARTS   AGE
demo-pod                            1/1     Running   0          2m58s

Verify that the app can write to your block storage volume by logging in to your pod.

oc exec demo-pod -- bash -c "touch /mnt/cosvol/test.txt && ls /mnt/cosvol" test.txt

Removing the IBM Cloud Object Storage storage configuration using the console

From the Satellite storage dashboard, select the storage configuration you want to delete.
Select Actions > Delete
Enter the name of your storage configuration.
Select Delete.

Removing the IBM Cloud Object Storage storage configuration using the command line

If you no longer need your IBM Cloud Object Storage configuration, you can remove your apps, PVCs, PVs, and assignment from your clusters.

List your storage assignments and find the one that you used for your cluster.

ibmcloud sat storage assignment ls (--cluster CLUSTER | --config CONFIG | --location LOCATION | --service-cluster-id CLUSTER)

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.
```
ibmcloud sat storage assignment rm --assignment <assignment_ID>
```
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.
```
oc get sc
```
2. List the pods in the kube-system namespace and verify that the storage driver pods are removed.
```
oc get pods -n kube-system | grep cos
```
Optional: Remove the storage configuration.
1. List the storage configurations.
```
ibmcloud sat storage config ls
```
2. Remove the storage configuration.
```
ibmcloud sat storage config rm --config <config_name>
```

Parameter reference

2.2 parameter reference

Table 1. 2.2 parameter reference
Display name	CLI option	Type	Description	Required?	Default value
Release name	`helm-release-name`	Config	Helm chart release name.	true	`ibm-object-storage-plugin`
Helm Chart additional parameters	`parameters`	Config	Helm Chart additional parameters.	false	N/A
Object Storage plug-in license	`license`	Config	Object storage plug-in license: Apache license Version 2.0. Set to `true` to accept the license and install the plug-in.	true	N/A
Object Storage provider	`s3provider`	Config	Available providers are `IBM`, `AWS` and `Wasabi`. For providers other than these, you must provide the `Object Storage service endpoint` parameter.	false	N/A
Object Storage region	`cos-storageclass`	Config	Enter the region where your object storage is located. For IBM COS regions, see https://ibm.biz/cos-endpoints-list. For Wasabi, see https://ibm.biz/wasabi-endpoints. For AWS, see https://ibm.biz/aws-endpoints.	true	N/A
Object Storage service endpoint	`cos-endpoint`	Config	Object Storage service endpoint. Required when using Object Storage providers other than IBM, AWS or Wasabi. Preference is given to `Object Storage provider` when both are set.	false	N/A

Storage class reference for IBM Cloud Object Storage

Table 2. Cloud Object storage class reference
Storage class name	Volume binding mode	Retain
`ibm-s3fs-cos`	Immediate	False
`ibm-s3fs-cos-perf`	Immediate	False

Getting help and support for IBM Cloud Object Storage

When you use IBM Cloud Object Storage, try the following resources before you open a support case.

Review the FAQs in the Block Storage for VPC docs.
Review the troubleshooting documentation to troubleshoot and resolve common issues.
Check the status of the IBM Cloud platform and resources by going to the Status page.
Review Stack Overflow to see whether other users experienced the same problem. Tag any questions with ibm-cloud and COS.
If you run into an issue with Block Storage for VPC, submit a support request with IBM Cloud® Support.