Introduction

With the IBM® Storage Ceph® as a Service Block Storage API, you can programmatically provision and manage block storage resources within a IBM Storage Ceph as a Service deployment, including volumes, hosts, and volume to host mappings. For more information, see About IBM Storage Ceph as a Service APIs.

SDKs

SDK for Go is available for this API. The client libraries that are provided by the SDK implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries.

For more details about using IBM Storage Ceph as a Service, see docs.

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/sds-go-sdk/sdsaasv1"
)

Go get

go get -u github.com/IBM/sds-go-sdk/sdsaasv1

View on GitHub

https://github.com/IBM/sds-go-sdk

Endpoint URLs

IBM Storage Ceph as a Service Block Storage API is available in all IBM Storage Ceph as a Service deployments. To get the endpoint URL that you can use for a deployment, contact your Storage Administrator.

Authentication

The IBM Storage Ceph as a Service Block Storage API uses Identity and Access Management (IAM) to authenticate requests. To call each API method, you must be assigned a role that has access to the parent service instance. Check your access on the IBM Cloud console by navigating to Users > User > Access.

Learn about obtaining an IAM token for an authenticated user or service ID in the IAM Identity Services API.

If you first create an API key, you can use it to generate an IAM token.

To use the API, add a valid IAM token to the HTTP Authorization request header. For example, -H 'Authorization: Bearer {token}'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key.
By defining the API key in external configuration properties, and then by using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key.

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

IAM action information

To call each method, you need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with your IAM API key.

Setting client options through external configuration

Example environment variables, where {SERVICE_URL} is the endpoint URL and {API_KEY} is your IAM API key

export GLOBAL_SEARCH_URL={SERVICE_URL}
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY={API_KEY}

Example of constructing the service client

import {
    "github.com/IBM/sds-go-sdk/sdsaasv1"
}
...
authenticator := &core.IamAuthenticator{
		ApiKey: <apiKey>,
	}

sdsaasServiceOptions := &sdsaasv1.SdsaasV1Options{
		URL:           <serviceEndpoint>,
		Authenticator: authenticator,
	}

sdsaasService, err = sdsaasv1.NewSdsaasV1(sdsaasServiceOptions)
	if err != nil {
		panic(err)
	}

Auditing

You can monitor API activity within your account. Whenever an API method is called, an event is generated which you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.

For more information about how to track IBM Storage Ceph as a Service activity, see Auditing the events for IBM Storage Ceph as a Service.

Error handling

This API uses standard HTTP response codes to indicate whether a method was completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

| HTTP Error Code | Description | Recovery | |-----------------|-----------------------|-----------------------------------------------------------------------------| | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all the required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized to perform the requested operation. You do not have valid access through IAM access policies. If this error persists, contact the account owner to check your permissions. | | 404 | Not Found | The requested resource could not be found. | | 405 | Method Not Allowed | The requested resource does not support the request method. | | 406 | Not Acceptable | The resource the client had requested is not available in a format that is allowed by the Accept header that is supplied by the client. | | 408 | Request timeout | The connection to the server timed out. Wait a few minutes, then try again. | | 409 | Conflict | The request cannot be completed because of a conflict between the request and the current state of the resource. | | 500 | Internal Server Error | The request cannot be processed because the client encountered an unexpected condition on the server. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support. | | 501 | Not Implemented | The server either does not recognize the request method, or it lacks the ability to fulfill the request. | | 502 | Bad Gateway | The server was acting as a gateway or proxy and received an invalid response from the upstream server. | | 503 | Service Unavailable | The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition could also be due to an unplanned outage of a service that is needed to process the request. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support. | 504 | Gateway timeout | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server. | | 505 | HTTP Version Not Supported | The server does not support the HTTP protocol version that is used in the request. |

Versioning

Requests to the IBM CephaaS Block Storage API require a major version as the first segment of the request path (/v1/).

IBM CephaaS Block Storage Management API | IBM Cloud API Docs