Plugin: cos: IBM Cloud Object Storage🔗
IBM Cloud Object Storage supports high-speed transfers using the FASP protocol. These transfers leverage the same service used by Aspera on Cloud, called the Aspera Transfer Service (ATS). You can check the list of available ATS regions here: https://status.aspera.io. There are two ways to provide credentials:
- Using existing credentials
If you already have the endpoint, API key, and Resource Instance ID (CRN), use this method.
- Using IBM Cloud Console access
If you do not have credentials but have access to the IBM Cloud Console, use this alternative method.
Using endpoint, API key and Resource Instance ID (CRN)🔗
If you already have these parameters, provide the following options to ascli:
| Option | Description |
|---|---|
bucket |
Bucket name |
endpoint |
Storage endpoint URL for example, https://s3.hkg02.cloud-object-storage.appdomain.cloud |
apikey |
API Key |
crn |
Resource instance ID |
Example: Create a Default Configuration
ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --endpoint=https://s3.us-east.cloud-object-storage.appdomain.cloud --apikey=<API_KEY> --crn=<CRN>
ascli config preset set default cos <COS_PRESET_NAME>
Once configured, proceed to the transfer example.
Using service credential file🔗
If you are the COS administrator and do not yet have credentials, you can create them directly from the IBM Cloud Console (Web UI):
Steps:
- → Navigation Menu
- → Resource List
- → Storage
- → Select your storage instance
- → Service Credentials
- → New credentials (Leave default role: Writer, no special options)
- → Copy to clipboard
Save the copied JSON value to a file, for example: $HOME/cos_service_creds.json
Or, using the IBM Cloud CLI:
ibmcloud resource service-keys
ibmcloud resource service-key <SERVICE_KEY_NAME> --output JSON|jq '.[0].credentials'>$HOME/service_creds.json
Note
If jq is not installed, you can manually extract the credentials section from the JSON output.
The service credential file consists of the following structure:
{
"apikey": "<API_KEY>",
"cos_hmac_keys": {
"access_key_id": "<ACCESS_KEY>",
"secret_access_key": "<SECRET>"
},
"endpoints": "https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints",
"iam_apikey_description": "<DESCRIPTION>",
"iam_apikey_name": "<NAME>",
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
"iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/xxxxxxx.....",
"resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/xxxxxxx....."
}
The field mappings are as follows:
resource_instance_id→ optioncrnapikey→ optionapikey
Note
Endpoints for regions can be found by querying the endpoints URL in the JSON file or from the IBM Cloud Console.
The required options for this method are:
| Option | Description |
|---|---|
bucket |
Bucket name |
region |
Bucket region for example, eu-de |
service_credentials |
JSON information saved from IBM Cloud console. |
Example: Create a Default Configuration
ascli config preset update <COS_PRESET_NAME> --bucket=mybucket --service-credentials=@val:@json:@file:~/service_creds.json --region=us-south
ascli config preset set default cos <COS_PRESET_NAME>
Operations, transfers🔗
After creating a default configuration using one of the previous methods (otherwise, specify the access options directly on the command line), you can perform a subset of node plugin operations, which correspond to the Node API.
ascli cos node info
ascli cos node upload 'faux:///sample1G?1g'
Note
The file sample1G is a dummy file of size 1 GiB, generated using the faux PVCL scheme (see previous section and man ascp).
To upload a real file, replace the faux:///... URI with the actual file path.
Tested commands for cos🔗
Note
Add ascli cos in front of the following commands:
node download test_file.bin --to-folder=.
node info --bucket=my_bucket --endpoint=my_endpoint --apikey=<API_KEY> --crn=<RESOURCE_INSTANCE_ID>
node info --bucket=my_bucket --region=my_region --service-credentials=@json:@file:<COS_SVC_CRED_FILE>
node info --log-level=trace2
node upload test_file.bin