Automated instance mapping for SAP HANA Cloud instances

[tom_slee]

"Instance mapping" is the term for making a HANA Cloud instance (provisioned in a subaccount, or in a Cloud Foundry (CF) space) available to Business Application Studio and the HDI deployment tool from other CF spaces or from a Kyma namespace. See the documentation for more information. Instance mapping enables one HANA Cloud instance to host HDI Containers (tenants) in numerous different CF spaces, which is often a useful property for customers with numerous projects: you can keep the projects separate without the overhead of provisioning a HANA Cloud instance in each space.

Since the initial release, you have had to use HANA Cloud Central to perform instance mapping on a HANA Cloud database. Now, with the release of new APIs, you can carry out instance mapping from a command line (using curl) or other environment that lets you make HTTP calls. The blog post walks through the process of instance mapping using curl.

First, some other resources:

• Product documentation: Access Administration APIs | SAP Help Portal
• Product documentation on instance mapping: Map an SAP HANA Database to another Environment Context | SAP Help Portal
• A tutorial: Access SAP HANA Cloud Alerts and Metrics using a REST API | SAP Tutorials
• Rest API documentation on SAP Business Accelerator Hub REST API | SAP HANA Cloud | SAP Business Accelerator Hub

The steps involved are:

1. Create an instance of the admin-api-access service plan, which governs access to the APIs
2. Create a binding to the service instance
3. Using curl, obtain a JWT token that lets you access the API
4. Get the instance ID for a named instance of interest
5. Assign an instance mapping

Create an instance of admin-api-access

This task is carried out from the BTP Cockpit. You must be a subaccount administrator to carry out this task.

Create an instance of the SAP HANA Cloud admin-api-access service plan from BTP Cockpit in your subaccount. 

Here is the New Instance wizard. I choose the "Other" runtime environment.

On the Parameters page, enter this JSON:

{"technicalUser": true}

Then create a binding to this instance, from SAP BTP Cockpit, which will provide the authentication information you need.

Obtain a JWT token

The authentication service used here is "XSUAA", which is the default authentication and authorization service for BTP. Here is a command to obtain a JWT bearer token from XSUAA for use with the admin-api-access instance.

> # Obtain a JWT bearer token from XSUAA for authentication
> curl -s $url/oauth/token -X POST -d 'grant_type=client_credentials&client_id=$clientid$&client_secret=$clientsecret$'

where $url, $clientid, and $clientsecret are shell variables that represent the values from the service binding. The "url" entry is found inside the "uaa" entry of the binding.

If you want to store the bearer token in a bash script variable for use you can do this, building on the very useful "jq" utility for parsing JSON. Unfortunately I cannot edit the embedded code here, so please note that "jr" should be "jq".

> bearer_access_token=$(curl -s $url/oauth/token -X POST -d 'grant_type=client_credentials&client_id=$clientid$&client_secret=$clientsecret$' | jr -r .access_token)

Get the instance ID for a named instance of interest

Assuming you know the instance name ($hana_instance_name) for the HANA instance you wish to map, you can get the instance ID with this command (split over several lines for convenience). Again, I mistyped "jr" where it should be "jq". Also, please see Michael's comment for the correct positioning of the parentheses.

> hana_instance_id=$(curl -s $baseurl/inventory/v2/serviceInstances -X GET \
-H "Authorization: Bearer $bearer_access_token)" \
| jr -r ".data[] | select(.name==\"$hana_instance_name\" | .id" )

Assign an instance mapping

You need to know the org ID (cf_org_id) and space ID (cf_space_id) of the target CF spaces. You can do this with the CF command:

> cf org <ORG> --guid

To get the information you need if you wish to map to a Kyma namespace, see the product documentation here. Once you have these values in variables, you can create an instance mapping as follows:

> curl -s \
$baseurl/inventory/v2/serviceInstances/$hana_instance_id/instanceMappings \
-X POST \
-H 'Authorization: Bearer $bearer_access_token' \
-H 'Content-Type: application/json' \
-d "{\"isDefault\": true, \"platform\": \"cloudfoundry\", \"primaryID\": \"$cf_org_id\", \"secondaryID\": \"$cf_space_id\"}"

In the -d argument, the whole argument is enclosed in double quotes so that variables will be replaced with their values, and then each internal double quote must be escaped with a backslash.
Other commands are available from REST API | SAP HANA Cloud | SAP Business Accelerator Hub under Instance Management.

We look forward to filling out the admin APIs over the coming months.