SAP BTP deployment

Figaf Tool can run in the Cloud Foundry environment of SAP BTP, in the same subaccount as the SAP systems it works with.

This page explains what the deployment consists of, what you need to prepare and how to keep it up to date. The step-by-step procedure, with screenshots of the SAP BTP cockpit, is in the Deploy to BTP article.

1. What gets deployed

The deployment descriptor in the Figaf-BTP-Deployment repository pushes two Cloud Foundry applications:

Application

The Figaf Tool backend, running the figaf/app:<version>-btp Docker image. It’s published on an internal route only, so it isn’t reachable from outside directly.

Application router

An SAP application router on the Node.js buildpack. It holds the public route, authenticates every request and forwards the token to the backend.

Both are bound to two services that you create beforehand:

  • figaf-db - a PostgreSQL instance. The application reads its credentials from the service binding, so no database host or password is configured anywhere.

  • figaf-xsuaa - an XSUAA instance that provides authentication and the Figaf roles.

2. Prerequisites

  • A subaccount with the PostgreSQL entitlement - both the standard plan and the storage plan are needed - and the Cloud Foundry Runtime entitlement.

  • Cloud Foundry enabled on the subaccount, and a space to deploy into.

  • The Cloud Foundry CLI, version 8.

  • A Docker Hub account. The image is pulled anonymously unless you set DOCKER_USERNAME, and anonymous pulls are rate limited, which shows up as a toomanyrequests: You have reached your pull rate limit error during deployment.

  • A license key. See License installation.

Setting up the subaccount is described in the Setting up SAP BTP Account to deploy Figaf in Cloud Foundry article.

Running Figaf Tool in Google datacenters isn’t supported yet, because the database there requires a certificate.

3. Sizing

Setting Value

Instance memory

4G minimum for a productive account, 3700M for a trial account

Maximum heap

50% of the instance memory

Disk quota

10 GB

PostgreSQL service plan

standard or larger

PostgreSQL engine

16

Don’t use the free or trial PostgreSQL plan for anything but a first look. The application writes a warning to its log when it starts on one of them, because their performance limitations affect the whole tool.

4. Configuration

Everything you configure lives in vars.yml, which is read by cf push. The descriptor also contains manifest.yml, db.json, xs-security.json and the app router, none of which normally need editing.

Key Description

ID

Prefix for the names and routes of both applications. Avoid underscores and special characters.

LANDSCAPE_APPS_DOMAIN

The domain of your Cloud Foundry landscape, in cfapps.xxxxx.hana.ondemand.com format. Run cf domains to find it.

DOCKER_IMAGE_VERSION

The image tag to deploy, for example 2608-btp. Always a -btp tag, written without the figaf/app: prefix. See the available tags.

DOCKER_USERNAME

Your Docker Hub user name, used to pull the image as an authenticated user.

LOCATION_ID

Location id of the Cloud connector. Required to reach SAP PI/PO systems, and an on-premise SMTP server, from the subaccount.

LOGS_TOTAL_SIZE_CAP

Maximum total size of the logs folder.

INSTANCE_MEMORY

RAM allocated to the backend application.

MAX_RAM_PERCENTAGE

Share of that memory used as the maximum Java heap.

ENABLE_INSTANCE_MONITORING

Enables the Glowroot agent and the /instance-monitoring endpoint, which is accessible to users with the IRTAdmin role.

USE_CLOUD_CONNECTOR_FOR_SMTP_INTEGRATION

Whether e-mail is sent through an SMTP server reached over the Cloud connector.

CLOUD_CONNECTOR_DESTINATION_NAME_FOR_SMTP_INTEGRATION

Name of the destination in the SAP BTP Destination service that holds that SMTP server’s host and port.

Newer releases add keys to this file, so take vars.yml from the repository for the release you’re deploying and fill it in, rather than carrying an old copy forward.

5. Deploy

In outline, deployment is:

  1. Log in with cf login -a <API endpoint of your subaccount>.

  2. Download the descriptor from the repository and fill in vars.yml.

  3. Create the figaf-db and figaf-xsuaa services. Creating the database can take up to ten minutes, and cf push fails until it’s finished.

  4. Assign the Figaf role collections to your users.

  5. Run cf push --vars-file vars.yml.

  6. Open the application router URL and add your license key on the Configuration → License page.

Follow the Deploy to BTP article for the full procedure.

6. Login and roles

Authentication is handled by SAP BTP, so a BTP deployment has no local users and no superUser account. Anyone who can open the application router URL signs in with their SAP BTP identity.

What each user may do is controlled by the role collections that xs-security.json creates. They’re named after the Figaf Tool roles and map onto them one to one, so IRTAdmin, IRTDevOpsManager, IRTSupportToolOperator and the rest behave exactly as they do in any other deployment. The one role without a collection is IRTSuperUser, which belongs to the root administrator that a BTP deployment doesn’t have. Assign the collections in the subaccount under Security → Users.

Assign IRTAdmin to the first user, so that somebody can configure the instance.

Releases occasionally add roles. When the change log says a new role is available on BTP, take the latest descriptor and deploy again, otherwise the role collection doesn’t exist in your subaccount.

7. How a BTP deployment differs

Database

Credentials come from the figaf-db service binding.

Memory

The heap is sized with MAX_RAM_PERCENTAGE as a share of INSTANCE_MEMORY, instead of the fixed XMX_VALUE used elsewhere.

Instance monitoring

Enabled by default, and unlike other deployments a direct link to a page inside the Glowroot UI works.

On-premise systems

SAP PI/PO systems and a local SMTP server are reached through the Cloud connector, configured with LOCATION_ID.

Agent connection test

Connection tests include a user API availability check that only runs on BTP. Disable it with the irt.config.agent.skip-pi-user-access-api-availability-test application property if your PI system doesn’t expose that API.

8. Upgrade to a new version

  1. Download the descriptor for the new release and set DOCKER_IMAGE_VERSION in vars.yml to its -btp tag.

    Take the whole descriptor, not just the tag. Releases have changed manifest.yml, vars.yml, approuter/package.json and approuter/xs-app.json, and the Change log records which release changed what.

  2. Delete the running applications:

    cf delete <ID>-router -f
cf delete <ID>-app -f

  3. Deploy again:

    cf push --vars-file vars.yml

The services aren’t touched, so the database and all its data survive the upgrade.

9. Remove the deployment

Delete both applications as above, then delete the figaf-db and figaf-xsuaa service instances. Deleting figaf-db destroys the database and everything in it.

To clean up the objects Figaf Tool created on your SAP systems, follow Uninstallation before you delete anything.