Introducing Cloud Management Tools – CLI and APIs for SAP Cloud Platform (PART 1)

[Neuert]

We're currently renovating and adding core functionalities to SAP Cloud Platform. As part of this journey, we have added two new long-awaited features that can serve as alternatives to the SAP Cloud Platform cockpit:

• CLI (command line interface) for SAP Cloud Platform


• APIs (application programming interfaces) for SAP Cloud Platform

These features are available only to SAP Cloud Platform accounts that are running cloud management tools feature set B, which is already available in Trial. We are planning to migrate enterprise accounts from the existing cloud management tools feature set A to the renovated cloud management tools feature set B, and this will be a phased rollout. So, cloud management tools feature sets A and B will coexist for some time. See “What are the differences between the two cloud management tools feature sets?”.

In this blog, I want to share with you an overview of how you can use the sapcp CLI for convenient account management tasks and to automate these procedures. For example:

• Manage global accounts, directories, and subaccounts


• Set entitlements


• Work with environments


• Work with multitenant applications


• Manage users and their authorizations

 

In a second blog post (part 2) I also want to show you how to consume REST APIs to manage, build, and extend the cloud operation capabilities of SAP Cloud Platform. For example:

• Manage global accounts, directories, and subaccounts


• Get information about events relating to administrative operations in your accounts


• Assign entitlements for services and applications to directories and subaccounts


• Manage the provisioning of environment instances and get information relating to provisioned services


• Manage subaccount subscriptions to multitenant applications and their dependencies


• Generate reports based on the resource and cost consumption within your accounts.

PART 1: Using the Command Line Interface (sapcp btp CLI)

UPDATE: With the release of version 2.0.0 on March 25, 2021, the executable file of the CLI client was renamed from sapcp to btp. All commands remain compatible, and we will support the sapcp CLI until September 2021. (see for more information help.sap.com)

The CLI for SAP Cloud Platform is an alternative to the cockpit letting you carry out all account administration tasks on your global account, directories, and subaccounts via the terminal.

If you go down the account model hierarchy starting with the global account, the last task you can use the CLI for is to create environment instances (for example, a Cloud Foundry org). If you want to stay within the command line framework, from here on, you'll need to use the Cloud Foundry CLI (cf CLI) or Neo CLI (console client).

First, you need to download and install the client. Check out these links:

1. Download and Start Using the CLI for SAP Cloud Platform


2. Download and Install the Cloud Foundry Command Line Interface


3. Console Client for the Neo Environment

After you've installed the sapcp CLI, you can run “sapcp --help” to see all the available commands. Before using any of the commands, you need to log in to your account with the “sapcp login” command. The login command requires some input parameters, which you might not be familiar with:

1. CLI server URL: you can find the URL in the subaccount of your account under API Endpoint. In the URL, replace "api" with "cpcli". For example, if your API endpoint from the cockpit is "https://api.cf.eu10.hana.ondemand.com", then your CLI server URL is "https://cpcli.cf.eu10.hana.ondemand.com".


2. Global account subdomain: You can find the subdomain in the details of your global account in the cockpit.


3. User and password: This is your e-mail address and password that you use to log in to SAP Cloud Platform.

CLI commands and command syntax

After entering

sapcp --help

you'll see something like this depending on the version you have installed:

sapcp --help

Each command consists of the base call "sapcp" followed by a verb (the action), a combination of a group and object, and parameters.

The sapcp CLI uses this syntax:

Command structure

To get detailed help for each command, add --help after sapcp or at the end: sapcp --help <action> <group/object>

For example:

sapcp --help list accounts/subaccount

sapcp list accounts/subaccount --help

sapcp list accounts/subaccount --help

The examples included in the command help for each command are extremely helpful for getting your commands in the right format.

Example: Creating a directory with subaccounts and setting entitlements

In this example, I'm going to show you how to create a directory with three subaccounts and to configure the auto-entitlement of the three subaccounts to the SAP HANA Cloud service and the Alert Notification service. Afterwards, we'll see how enable SAP HANA Cloud.

This is the account model we want to achieve (ignore the "Cloud Management" and "trial" subaccounts"):

Directories

First, I will create a directory with the name “DIRECTORY” and include some additional parameters and custom properties parameters:

sapcp create accounts/directory --global-account <subdomain> 

--features DEFAULT,ENTITLEMENTS,AUTHORIZATIONS --display-name DIRECTORY 

--description 'example of a script' --directory-admins '["myname@sap.com"]' 

--custom-properties '[{"key": "Landscape","value": "Dev"},

{"key": "Department","value": "HR"},{"key": "Flagged","value": ""}]'

subdomain:  The subdomain is the same as the one you used in the sapcp login.

--features DEFAULT,ENTITLEMENTS,AUTHORIZATIONS: IT's a directory that manages its own entitlements and authorizations. For example, subaccounts in this directory will get their quota limit from this directory, and the directory has its own directory admin/viewer authorizations.

Directory - Basic Information

--display-name DIRECTORY --description 'example of a script': in the screenshot above you see the Display Name and Description.

--directory-admins '["name@sap.com"]': here name@sap.com was added as Directory Administrator.

Directory - Authorizations

--custom-properties '[{"key": "Landscape","value": "Dev"},{"key": "Department","value": "HR"},{"key": "Flagged","value": ""}]: Here we are adding three different custom properties to the directory. This is optional. You can see here how  the custom properties screen looks like for directories in the cockpit.

Directory - Custom Properties

The assignment of entitlements is a separate command in the CLI, and we assign one service plan at a time:

1. Alert Notification:

sapcp assign accounts/entitlement --to-directory <directoryid> --for-service alert-notification --plan standard --distribute 'true' --auto-assign 'true' --enable 'true'

2. HANA Cloud:

sapcp assign accounts/entitlement --to-directory <directoryid> --for-service hana-cloud-trial --plan hana --enable 'true' --auto-assign 'true'

Directory - Entitlement

The command starts with sapcp assign accounts/entitlement --to-directory <directoryid>: The <directoryid> you will get via command line:

sapcp get accounts/global-account --show-hierarchy

or via the cockpit

Directory - Information

The second part of the assignment of entitlements for service “Alert Notification” starts with:

--for-service alert-notification: The name of the service that you want to assign as an entitlement

--plan standard: The name of the actual service plan that you want to assign

--auto-distribute-amount <n>: The quota of the specified plan to automatically allocate to any new subaccount that is created in the future in the directory. The 'auto-assign' param must also be set to true

--distribute 'true': Assigns the plan with the quota specified in '--auto-distribute-amount' to subaccounts currently located in the specified directory.

--auto-assign 'true': Automatically allocates the plans of entitlements that have a numeric quota with the amount specified in '--auto-distribute-amount' to any new subaccount that is added to the directory in the future. If '--distribute' is also set to true, the same assignment is made to all subaccounts currently in the directory. Entitlements are subject to available quota in the directory.

Now, that we have a directory and configured its entitlements, we can ahead and create subaccount.

sapcp create accounts/subaccount --display-name "Mars" --subdomain <subdomain> --region eu10 --subaccount-admins '["name@sap.com"]' --directory <directory ID>

sapcp create accounts/subaccount --display-name "Mars": Creates the subaccount with name “Mars”.

--subdomain <subdomain>: The subdomain that becomes part of the path used to access the authorization tenant of the subaccount. Must be unique within the defined region.

--region eu10: The region in which to create the subaccount. “eu10” is AWS Europe. See also command “sapcp list accounts/available-region” to get all available regions for your subaccount.

--subaccount-admins '["name@sap.com"]': Assign an additional subaccount administrator for subaccount.

--directory <directory ID>: See earlier in this blog how you can get the directory ID from the CLI or the cockpit.

In the next step, the Cloud Foundry environment has to be enabled in the subaccount :

sapcp create accounts/environment-instance --subaccount <subaccount ID> --environment cloudfoundry --display-name <Org. Name> --service cloudfoundry --plan standard --parameters "{\" instance_name\":\"<yourinstancename\"}" : Creates a Cloud Foundry org for your newly created subaccount with the name that you specify (this is name of the environment instance). The display name is not unique since the system will also generate an ID for the environment instance. <Service> and <Plan> you'll get for your subaccount via following statement: sapcp list accounts/available-environment --subaccount <subaccount ID>. 

To create a HANA instance, we first have to create a space From now on, we will switch from the sapcp CLI to cf CLI:

cf create-space <space name> -o <org name>: Creates space in the org that was created when we enabled the environment.

To be sure that we create the HANA Cloud instance in the correct subaccount and space, we use this command: cf target -s <space name> -o <org name>

With this statement, we create the HANA Cloud instance:

cf create-service hana-cloud-trial hana <instance name> -c '{

	"data": {

		"edition": "cloud",

		"memory": 30,

		"serviceStopped": false,

		"storage": 120,

		"systempassword": "<your password>",

		"vcpu": 0,

		"versionIndicator": "",

		"whitelistIPs": []

	},

	"metadata": {}

}'

Where “hana-cloud-trial’ is the service, “hana” the service plan and <instance name> the name for your instance.

If the service needs JSON parameters, as does HANA Cloud, you can enter it with -c '{

"data":.. }

So, let's recap… with these commands, we've created a directory and a subaccount. The entitlements we assigned to the directory were automatically inherited to subaccount (and to any new subaccount that is added to the directory, as long as the directory quota has not been used up). Afterwards, we enabled the Cloud Foundry environment in the subaccount and created an org and space. Then, we activated the trial of SAP HANA Cloud in this space.

Now let's talk about using the new APIs!! --> but that will happen in Part 2. See Link.