Setting up your CLI and API environment

Before you can create an IBM® Storage Ceph® as a Service by using the API, or CLI, set up your environment.

General prerequisites

Set up your account to access IBM Storage Ceph as a Service. Make sure that your account is upgraded to a paid account.
Make sure that you have the list of on-prem endpoints that were provided for deployment handy.

You can set the endpoints as environment variables.

CLI prerequisites

Before you can use the CLI, you must install the IBM Cloud CLI and the IBM Storage Ceph as a Service CLI plug-in.

Make sure that your environment from which the CLI will be run is connected to the on-premises network before using the CLI on the on-premises deployment of IBM Storage Ceph as a Service.

Install the IBM Cloud CLI.
Install the IBM CephaaS CLI plug-in software-defined-storage.
```
ibmcloud plugin install software-defined-storage
```
The IBM Storage Ceph as a Service CLI actions also use the aliases sds. To learn how to use the CLI commands, you can run:
```
ibmcloud sds help
ibmcloud sds help volume-create
ibmcloud sds help host-create
```

Accessing CLI through the API endpoint

To set the CLI to use the API endpoint, follow these steps:

If you need to download the IBM Cloud CLI and associated plug-ins, you must be able to access the public repository where they are located.

Ensure that the core IBM Cloud CLI and IBM CephaaS service plug-in are updated to the latest version:
```
ibmcloud update
```
```
ibmcloud plugin update software-defined-storage
```
To specify an API endpoint, enter the following command:
```
ibmcloud login -a https://cloud.ibm.com
```
For more information on CLI option details, see ibmcloud login.

Setup IAM Token

Before you can use the CLI to create your IBM CephaaS, you must get an IAM token, store the endpoint as a variable, and verify that you have access to the CephaaS service.

IAM_TOKEN=$(ibmcloud iam oauth-tokens --output json | jq -r '.iam_token)

API prerequisites

Before you can use the API to create your IBM CephaaS, you must get an IAM token, store the endpoint as a variable, and verify that you have access to the CephaaS API service.

The following examples use the us-south regional endpoint.

Step 1: Store your API key as a variable

Run the following command to store the API key for your account in an environment variable. If you don't have an API key, see Creating an API key.

apikey="<YOUR_API_KEY>"

Step 2: Get an IBM Identity and Access Management (IAM) token

Run the following command to get and parse an IAM token by using the JSON processing utility jq. You can modify the command to use another parsing tool, or you can remove the last part of the command if you prefer to manually parse the token.

IAM_TOKEN=`curl -k -X POST \
  --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=$apikey" \
  "https://iam.cloud.ibm.com/identity/token"  |jq -r '(.token_type + " " + .access_token)'`

To view the IAM token, run echo $IAM_TOKEN. The result should look like this:

Bearer <your token>

The Authorization header expects the token to begin with "Bearer". If the result doesn't include "Bearer", update the IAM_TOKEN variable to include it. These examples assume that "Bearer" is included in the IAM_TOKEN.

An IAM token is valid for up to 60 minutes, and it is subject to change. When a token expires, you must generate a new one. Use the property expires_in for the expiration of the IAM token that you have just created.

Step 3: Store the API endpoint as a variable

The $sds_endpoint is an environment variable that points to the endpoint provided to you when IBM CephaaS was configured. It is in the URL form. For example, https://sds-cephaas.<cephaas-instance-id>.software-defined-storage.appdomain.cloud:{port number}. Run the following command to store the API endpoint in a variable so it can be reused later in your session.

For example:

sds_api_endpoint="https://sds-cephaas.936481b2-379d-4ca6-94ed-4dc1911d749f.software-defined-storage.appdomain.cloud:33173"

To verify that this variable was saved, run echo $sds_endpoint and make sure that the response is not empty.

Step 4: Verify that you have API access

Now that you have an endpoint and your IAM token, verify your API access via one of the APIs described in the API Reference.

If you run into unexpected results, add the --verbose (debug) flag after the curl command to obtain detailed logging information.