Writing Function-as-a-Service [0.1]: Preparation

With other words:

How to write serverless Functions
with
SAP Cloud Platform Serverless Runtime
:
Preparation

This blog is part of a series of tutorials explaining how to write serverless functions using the Function-as-a-Service offering in SAP Cloud Platform Serverless Runtime

Quicklinks:
Series
Service Instance
Quick Guide

Overview

Before we can write our first serverless function, a few preparation steps are required.
However, not all explained steps have to be done by everybody

• Prepare Service Instance
• Prepare development environment in the cloud
• Prepare development environment on local machine
• SAP Business Application Studio
• Appendix: Entitlements
• Appendix: Assign Roles
• Appendix: Control Center

Prerequisites

• Access to SAP Cloud Platform
  You need access to a productive account of SAP Cloud Platform
  Note:
  This service is not (yet) available in Trial
• Node.js / Javascript
  Functions are written in Javascript for Node.js runtime
  As such, some knowledge is helpful
  However, most of the tutorials can be followed without any knowledge
• Local development is possible, such that installing Node.js and an IDE like Visual Studio Code is helpful

For everybody: Prepare Service Instance

For writing serverless “Functions-as-a-Service”, we need to create an instance of Service Serverless Runtime

In Cockpit of SAP Cloud Platform, go to your Subaccount and your Space
On the left menu, click on Services -> Service Marketplace
Search for the tile Serverless Runtime

If you don’t find it:
Try the computer search (enter e.g. “serverless” in the search box)

If the computer search doesn’t find it:
…At least you have the good feeling that computer is not better than human

So, if you don’t have the service in your marketplace, you need to configure “entitlements”.
See appendix for info

If you find this tile

you can click it
Then click “Instances” on the left menu, afterwards “New Instance”
In the wizard, choose the Service Plan “default”, then press next.
In the Parameters page, enter the following snippet:

{
   "extensions": true,
   "odp": false
}

Explanation:
This means that we want to use “Extensions”, but no “OData Provisioning” (can be changed later)
“Extensions” means to create projects for Functions-as-a-Service
About “OData Provisioning”, you can read SAP Help Portal

Skip the next page, as we don’t have application
In the last page, enter a name for the service instance which will be created, e.g. xfsr_instance
Confirm the dialog

What now?
What can we do with this service?

Now you have the choice: blue or black
(Yes, I know, the colors in that famous movie are different…)
I mean, now you can start writing functions.
Almost
You have the choice if you prefer to use the “Extensions Center” (in the cloud) or if you prefer your local environment (on your local machine)
Both options require a few additional preparation steps

For users of cloud UI: Prepare Extension Center

SAP Cloud Platform Serverless Runtime offers a tool which helps to create functions.
It is called Extension Center and can be accessed via Subscription

Subscribe

Go to Subaccount -> Subscriptions
Find the tile Extension Center and click on it
Click on “Subscribe”
After subscription has happened, it is possible to open the application

But don’t click on “Go to application”
Not yet.

Reason:
To enter the application, you need a role

Required role

Typically, the usage of those dashboards in the SAP Cloud Platform is ruled by user profiles, based on roles.

“Functions-as-a-Service” provides 2 access profiles (note that I’m always talking about functions only, not OData Provisioning):

FunctionRead	Read only
FunctionManage	Read and write (and delete)

Our user needs to have one of these roles. Obviously, we choose the more powerful one
As such, we go ahead and assign the FunctionManage role to our user
See appendix for detailed description

Open Extension Center

After the role is assigned to your user, you can click on “Go to application”
Enter your user credentials
Then you should see the Extension Center UI:

Now you can proceed to next tutorial and create your first function

For fans of local development: Prepare Command Line

1. Cloud Foundry CLI

The Command Line Tool for Functions manages a service instance in Cloud Foundry Environment of SAP Cloud Platform
To do so, it uses the Command Line Client for Cloud Foundry 
As such, it is necessary that the Command Line Client for Cloud Foundry is installed on our computer.
Install the Cloud Foundry command line client (CLI)
A blog for beginners can be found here

2. Service Key

To connect to the Serverless Runtime we need to authenticate
The credentials are provided by the service instance via “Service Key”
The service key has to be obtained from the service instance created above
A service key can be created in the Cloud Cockpit and via Cloud Foundry CLI

2.1. Create Service Key via Cockpit

To create a service key in the cloud cockpit:

Go to your Subaccount and Space
Choose Services -> Service Instances
Click on your service instance of type xfs-runtime
In the left menu, click on Service Keys
Click on “Create Service Key”
Enter a name of your choice
Remember it

Confirm the dialog

2.2. Create Service Key via Command Line

To create a service key on the command line, we use the Cloud Foundry Command Line Client
Login to cloud foundry and go to your org and space
Check the service instance of Serverless Runtime and remember its name

command:
cf services
Example:

To create a service key, run the following command:

cf create-service-key <my_XF_sr_instance> <name_of_my_choice>

Where the first param is the instance name (as remembered above)
And the second param is a name of your choice for the new service key
Make sure to choose a silly name, such that you can easily remember it

Optional:
After executing the command, you can verify the new service key with the following command:
cf service-key <my_XF_sr_instance> <my_key_name>

3. Functions CLI

The correct name is of course:
SAP Cloud Platform Serverless Runtime CLI

After going through the 2 prerequisites, we can now download the Command Line Tool for Functions

3.1. Download Functions CLI

Download SAP Cloud Platform Serverless Runtime CLI from https://tools.hana.ondemand.com/#cloud
Unzip the archive to a folder of your choice
The archive contains an .exe file:
This is the executable command which we’ll be using

Note:
As usual, to execute the command, you have to step into the folder where the executable is located
Alternatively, type the full path to the executable
Alternatively, add the “folder of your choice” to the PATH variable

3.2. Use the Functions CLI

Once you’ve downloaded the command line tool and created a service key, you’re ready to use the tool

Login:
Your first command every day will be to login to the XF serverless runtime:

xfsrt-cli login

The login command needs to know the name of the service instance, and also the service key.
The convenient way of obtaining it, is to ask for it in an interactive step.
Nice:

Note:
If you get an error, just execute the login command again

Note:
The description above is based on version 2 of the command line tool
The older version requires the following command:
xfsrt-cli login -n <my_XF_sr_instance> -k <my_key_name>
in my example
xfsrt-cli login -n xfsr_instance -k servicekey_functions

SAP Business Application Studio

See documentation

Quick Guide

• Create instance of XFSR with parameters:
  {“extensions”: true,”odp”: false}
• Extension Center
  • Subscribe
  • Assign roles
• Command Line Tool for Functions
  • Install CLI for Cloud Foundry
  • Create Service Key
  • Download CLI for Functions

Appendix 1: Configure Entitlements

Go to your subaccount
In the left menu pane, click on Entitlements
In the Entitlements screen of your subaccount, you can search for “Serverless R”
It shouldn’t be there

Click on Configure Entitlements
This makes the page editable
Which is not enough
To add more services, we need to click on Add Service Plans
In the dialog, in the list on the left side , search for “serverless”
You should find the entry “Serverless Runtime”
Click it, and on the right side the available Service Plans are listed
In this case, it is only one, the “default”
You should be able to select it

If the checkbox is disabled, you need to purchase quota
This is done in the Control Center, by somebody who is entitled to spend money in the cloud
See appendix for info about using Control Center
After selecting the checkbox, close the dialog with the button “Add 1 Service Plan”
Back in the “Entitlements” page, don’t forget to press “save”

Appendix 2: Assign Role

Assign role to me

1. Create Role Collection

Go to your Subaccount -> Security -> Role Collections
Create a Role Collection with a name of your choice
Click on the new Role Collection hyperlink
Click “Add Role”
Choose the Application Identifier for Serverless Runtime:
xfsrt-application!t27765
Then choose the Role Template FunctionsManage

This role allows us to not only view the functions, but also create and delete etc
After pressing save, we do have a role collection which contains one role

Now we need to assign the role collection to our user

2. Assign Role Collection

Go to Subaccount -> Security -> Trust Configuration
Click on SAP ID Service (or your Identity Provider)
To assign the role collection to a single user, enter the E-Mail Address of your cloud user
Then press Show Assignments
Then press Assign, to assign the new role collection

That’s it. Now the user should be able to access the Extension Center

Appendix 3: Control Center

If you have permission, open the SAP CP Control Center at
https://controlcenter.ondemand.com/index.html

Choose the landscape and the global account
Press Edit
Step through the wizard
Assign the Service “Serverless Runtime”

In the Entitlements page, choose the service, plan, region and increase quota

If you’re sure that the cost will be covered, confirm the dialog
Then enjoy the SAP Cloud Platform Serverless Runtime