neoDeploy

Description

Deploys an Application to SAP BTP (SAP CP) using the SAP BTP Console Client (Neo Java Web SDK).

Prerequisites

• SAP BTP account - the account to where the application is deployed. To deploy MTA (deployMode: mta) an over existing Java application, free Java Quota of at least 1 is required, which means that this will not work on trial accounts.
• SAP BTP user for deployment - a user with deployment permissions in the given account.
• Jenkins credentials for deployment - must be configured in Jenkins credentials with a dedicated Id.

• Neo Java Web SDK 3.39.10 or compatible version - can be downloaded from Maven Central. This step is capable of triggering the neo deploy tool provided inside a docker image. We provide docker image ppiper/neo-cli. neo.sh needs to be contained in path, e.g by adding a symbolic link to /usr/local/bin.

• Java 8 or compatible version - needed by the Neo-Java-Web-SDK. Java environment needs to be properly configured (JAVA_HOME, java exectutable contained in path).

Parameters

name	mandatory	default	possible values
deployMode	no	mta	'mta', 'warParams', 'warPropertiesFile'
dockerEnvVars	no
dockerImage	no	ppiper/neo-cli
dockerOptions	no
extensions	no	[]
mavenDeploymentModule	no	.
neo/account	for deployMode=warParams
neo/application	for deployMode=warParams
neo/azDistribution	no		1, 2
neo/credentialType	no	UsernamePassword
neo/credentialsId	no	CI_CREDENTIALS_ID
neo/environment	no
neo/host	for deployMode=warParams
neo/invalidateCache	no		true, false
neo/oauthCredentialId	no
neo/portalLandscape	no	cloudnwcportal
neo/propertiesFile	for deployMode=warPropertiesFile
neo/runtime	for deployMode=warParams
neo/runtimeVersion	for deployMode=warParams
neo/siteId	no
neo/size	no	lite
neo/vmArguments	no
script	yes
source	yes
warAction	no	deploy	'deploy', 'rolling-update'

• deployMode - The deployment mode which should be used. Available options are: 'mta' - default, 'warParams' - deploying WAR file and passing all the deployment parameters via the function call, *'warPropertiesFile' - deploying WAR file and putting all the deployment parameters in a .properties file.
• dockerEnvVars - Environment variables to set in the container, e.g. [http_proxy: 'proxy:8080'].
• dockerImage - Name of the docker image that should be used. Configure with empty value to execute the command directly on the Jenkins system (not using a container). Omit to use the default image (cf. default_pipeline_environment.yml) Overwrite to use custom Docker image.
• dockerOptions - Docker only: Docker options to be set when starting the container (List or String).
• extensions - Extension files. Provided to the neo command via parameter --extensions (-e). Only valid for deploy mode mta.
• mavenDeploymentModule - Path to the maven module which contains the deployment artifact.
• neo/account - The SAP BTP account to deploy to.
• neo/application - Name of the application you want to manage, configure, or deploy.
• neo/azDistribution - Availability zone of BTP NEO into which the application is deployed.
• neo/credentialType - The Jenkins credential of type 'UsernamePassword' or 'SecretFile'.
• neo/credentialsId - The Jenkins credentials containing either user and password (UsernamePassword type credential) or json containing clientId, client secret and oauth service url (SecretFile type credential) used for SAP CP deployment.
• neo/environment - Map of environment variables in the form of KEY: VALUE.
• neo/host - The SAP BTP host to deploy to.
• neo/invalidateCache - Boolean to enable/disable invalidating the cache after deployment.
• neo/oauthCredentialId - UsernamePassword type credential containing SAP BTP OAuth client ID and client secret.
• neo/portalLandscape - Portal landscape region subscribed to in SAP BTP.
• neo/propertiesFile - The path to the .properties file in which all necessary deployment properties for the application are defined.
• neo/runtime - Name of SAP BTP application runtime.
• neo/runtimeVersion - Version of SAP BTP application runtime.
• neo/siteId - Site ID of the SAP Fiori Launchpad containing the SAP Fiori app. If not set, the cache of the default site, as defined in the Portal service, is invalidated.
• neo/size - Compute unit (VM) size. Acceptable values: lite, pro, prem, prem-plus.
• neo/vmArguments - String of VM arguments passed to the JVM.
• script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
• source - The path to the archive for deployment to SAP CP. If not provided the following defaults are used based on the deployMode: 'mta' - The mtarFilePath from common pipeline environment is used instead. 'warParams' and 'warPropertiesFile' - The following template will be used "/target/."
• warAction - Action mode when using WAR file mode. Available options are deploy (default) and rolling-update which performs update of an application without downtime in one go.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
deployMode		X
dockerEnvVars		X
dockerImage		X
dockerOptions		X
extensions		X
mavenDeploymentModule		X
neo/account	X	X
neo/application	X	X
neo/azDistribution	X	X
neo/credentialType	X	X
neo/credentialsId	X	X
neo/environment	X	X
neo/host	X	X
neo/invalidateCache	X	X
neo/oauthCredentialId	X	X
neo/portalLandscape	X	X
neo/propertiesFile	X	X
neo/runtime	X	X
neo/runtimeVersion	X	X
neo/siteId	X	X
neo/size	X	X
neo/vmArguments	X	X
script
source		X
warAction

Dependencies

The step depends on the following Jenkins plugins

• credentials-binding
• docker
• kubernetes
• lockable-resources
• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps-global-lib
• workflow-durable-task-step

The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

Side effects

none

Exceptions

• Exception:
• If source is not provided.
• If propertiesFile is not provided (when using 'WAR_PROPERTIESFILE' deployment mode).
• If application is not provided (when using 'WAR_PARAMS' deployment mode).
• If runtime is not provided (when using 'WAR_PARAMS' deployment mode).
• If runtimeVersion is not provided (when using 'WAR_PARAMS' deployment mode).
• AbortException:
• If neo-java-web-sdk is not properly installed.
• CredentialNotFoundException:
• If the credentials cannot be resolved.

Example

neoDeploy script: this, source: 'path/to/archiveFile.mtar', neo: [credentialsId: 'my-credentials-id', host: hana.example.org]

Example configuration:

steps:
  <...>
  neoDeploy:
    deployMode: mta
    neo:
      account: <myDeployAccount>
      host: hana.example.org

Example for invalidating the cache

Set the parameter invalidateCache to true to clean up the cache of an SAP Fiori launchpad site by refreshing the content of HTML5 applications deployed in it.

Note: This section is only applicable for HTML5 applications accessed through an SAP Fiori launchpad site.

Setting this parameter to true requires additional configuration:

Create an OAuth credential

1. In your subaccount, choose OAuth.

   

2. In the Subscription field, select the portal landscape to which you would like to subscribe, for example, portal/nwc or portal/sandbox.

   

3. From the drop-down menu in the Authorization Grant field, choose Client Credentials.

4. In the Secret field, enter a user-defined password and save your changes.

5. In Jenkins, create new username/password credentials. As username, use the client ID and as password, use the client secret.

Configure the site ID

When you're logged in to the portal service, you can retrieve the site ID. Either configure it in your configuration file or set the site as default through the Site Directory tile. If you don't set it as default, configure the parameter siteId as follows in your configuration file:

steps:
  <...>
  neoDeploy:
    neo:
      account: <myDeployAccount>
      host: hana.example.org
      credentialsId: 'my-credentials-id'
      invalidateCache: true
      portalLandscape: "cloudnwcportal"
      oauthCredentialId: <OAUTH_CREDENTIAL_ID>
      siteId: <PORTAL_SITE_ID> # not required, if the default site is already set in the portal service (SAP BTP)