Technical Articles
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
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
Hello Carlos Roggan,
thanks for you nice blog. I have problems with the extension center. Whenever I try to open it, I get an error "No service instance available. Create a service instance to continue. If you have an existing service instance, update it with the name parameter."
Of course I have created a service instance. What could be the reason?
Thanks an best regards,
Michael
Hello Michael-Peter Liermann
sorry for the late reply, due to vacation season.
This problem can occur, if UI was enabled before creating the service instance.
If that is the case, it can be resolved by disabling/deleting everything and start again with creating the instance first.
I hope this helps to solve your problem?
Kind Regards,
Carlos
Hello Carlos Roggan,
thanks, SAP support could somehow solve the problem and I can open the extension center now.
Unfortunately I have one more problems: I am able to create extensions, but when I try to open "Services", "Monitoring" or "Configurations" the error message "You are not authorized to access the user interface. Get the appropriate role assigned and log in again." appears.
But I have assigned myself all authorizations that are mentioned in the documentation (FunctionsManage, FunctionsRead, ODPAPIAccess, ODPManage).
Any ideas?
Do you know if it is possible to connect to SAP HANA Cloud (the new one, not Hana as a service) with functions?
Thanks a lot and best regards,
Michael
Your advice "recreate everything from scratch" also solved this authorization problem. Thanks.
Hello Michael-Peter Liermann ,
good to know that your previous problem has been resolved.
About the authorization-issue, I would ask, just in case:
did you completely refresh your browser after adding the ODP roles? This could explain the issue, in case you didn't assign all roles to your user at the same time. Can be tedious to close all browser instances in order to fully clear the cache
Kind Regards, Carlos
I recreated the role collection. Somehow that solved the problem.
Do you know if it is possible to connect to SAP HANA Cloud (the new one, not Hana as a service) with functions?
Best regards,
Michael
Hi, good to know that problem was solved.
In general, you can connect to any services in Cloud Foundry, as long as the service supports service keys, i.e. if the service allows to be called from external
I don't have specific experience with Hana service
Kind Regards,
Carlos
Hi Carlos Roggan I'm trying to create a serverless function but cannot get past the `xfsrt-cli login` step. It gives the following error after showing the org and space that I'm logged into:
I have tried this in the BAS and also after downloading the cli on my local PC and get the same error. I have deleted and recreated my xfs-runtime service instance and key many times.
Any idea how we get past this?
Hi Jason Scott ,
I think the CLI cannot find the service instance and gives misleading error message. Probably you only need to login in CF before: cf login -u <youruser> ...
Have you done xfsrt-cli login ?
Kind Regards,
Carlos
Hi Carlos Roggan – yes I have done cf login first and then xfsrt-cli login and every time it fails with same error regardless of doing it in BAS or local macbook. Have deleted the instance and re-created with different names and everything else I can think of. It's broken. ;-(
Hi Jason Scott
There's one more prerequisite for finding the instance: there must be a service key
And one more observation on my side was, I had to execute the login command twice. For some reason, the instance was found only when executed the second time
If nothing works, maybe it could be related to 2-factor-authentication?
If that's the case, it could explain why I cannot repro
Are you able to run any CF command on your command prompt?
Kind Regards,
Carlos
Thanks again Carlos Roggan . Yes I can login to CF fine and use all the other commands and can deploy a cap application and so on.
I do have a service key on the serverless instance and I have tried many times to login.
You’ve intrigued my by your comment about 2-factor auth though - why would there be 2 factor auth involved?
Hi Jason Scott , not sure about it. Does it help if you try the option --skip-ssl-validation ?
Tried that : "xfsrt-cli login -skip-ssl-validation" - same error unfortunately. Is there a way to turn on verbose logging maybe to try and get some more relevant info?
Carlos Roggan
sorry, the param was meant for cf login, with 2 hyphens
About logs:
I've done xfsrt-cli login -h
The docu is good and it shows that there's an option -v for verbose, when doing the login
Good idea 😉
Carlos Roggan I've tried all combinations as well as specifying the service instance name and key name. Interestingly the verbose options adds no further info. 😉
Using:
on cf login makes no difference either.
I wonder why the endpoint field below is empty?? When I run cf login it shows the correct endpoint.
Hi Jason Scott ,
good point. The xfsrt-cli uses the cf cli under the hood, so the endpoint should be the same and should not be empty (it is never empty in my case)
Can we move to the messaging-area to continue investigating?
BTW, which version of the CLI are you using?
It would be useful, if you found the solution, to repost it here. There might be others that run into the same problem. I know I did.
Hi Henrik Holst , you mean the solution for Jasons problem? There was an issue related to the name of the subaccount.