Improve CF documentation (#5274)

* Improve CF documentation

* Lint fix

---------

Co-authored-by: maxcask <[email protected]>

documentation/docs/steps/cloudFoundryDeploy.md

@@ -4,22 +4,37 @@
 
 ### Additional Hints
 
-Deployment can be done
+#### Standard CF deployments
 
-* in a standard way
-* in a zero-downtime manner (using a [blue-green deployment approach](https://martinfowler.com/bliki/BlueGreenDeployment.html))
+`deployType` parameter defaults to value `standard`.<br>
+This means that CF CLI is called by piper and command `cf push` is run by piper
 
-!!! note "Deployment supports multiple deployment tools"
-    Currently the following are supported:
+#### Blue green deployments
 
-    * Standard `cf push` and [Bluemix blue-green plugin](https://github.com/bluemixgaragelondon/cf-blue-green-deploy#how-to-use)
-    * [MTA CF CLI Plugin](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin)
+**With CF CLI**
 
-!!! note "Blue-Green Deployment with MTA CF CLI Plugin"
-    The Multiapps Plugin offers 2 different strategies:
+* Blue green deployments are deprecated, but [rolling deployment strategy](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html) is supported.<br>
+* For rolling deployment strategy , set parameter `cfNativeDeployParameters:'--strategy rolling'`
+
+**With [MTA CF CLI Plugin](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin) for MTA applications**
 
-    * [Blue-Green Deployment Strategy](https://github.com/SAP-samples/cf-mta-examples/tree/main/blue-green-deploy-strategy) - where the production environments are called “live” and “idle” during deployment. This strategy is activated with `mtaDeployParameters: --strategy blue-green --skip-testing-phase` and `deployType=standard`. After deployment, appnames are not appeneded by any suffix like `-live` or `-idle`.
-    * [Legacy Blue-Green Deployment](https://github.com/SAP-samples/cf-mta-examples/tree/main/blue-green-deploy-legacy) - where the productive environments are called “blue” and “green. Activated by `deployType=blue-green`. After deployment, appnames are appeneded by suffix like `-blue` or `-green`
+The Multiapps Plugin offers 2 different strategies:<br>
+
+* [Blue-Green Deployment Strategy](https://github.com/SAP-samples/cf-mta-examples/tree/main/blue-green-deploy-strategy) - where the production environments are called “live” and “idle” during deployment. This strategy is activated with `mtaDeployParameters: --strategy blue-green --skip-testing-phase` and `deployType=standard`. After deployment, appnames are not appeneded by any suffix like `-live` or `-idle`.<br>
+* [Legacy Blue-Green Deployment](https://github.com/SAP-samples/cf-mta-examples/tree/main/blue-green-deploy-legacy) - where the productive environments are called “blue” and “green. Activated by `deployType=blue-green`. After deployment, appnames are appeneded by suffix like `-blue` or `-green`
+
+Following table summarizes the different combinations of the step parameters `deployType` and `deployTool` and their impact.
+Parameter `buildTool`  is used to differentiate between MTA and Non MTA applications. If `buildTool` is not available in the environment, user will have to provide `deployTool` explicitly.
+
+#### Deployment Strategy Comparison
+
+This table compares deployment strategies for MTA and Non-MTA applications.
+
+| deployType      | MTA Applications | Non MTA Applications |
+|---------------|-----------------|----------------------|
+| **standard**   | deployTool = mtaDeployPlugin  <br> Uses MTA plugin, <br> Command run `cf deploy` | deployTool = cf_native  <br> cf CLI used <br> Command `cf push` <br> Requires Manifest file and app name <br> appname can be provided via config or manifest file. |
+| **blue-green** | deployTool = mtaDeployPlugin, <br> Uses MTA plugin <br> Command run `cf deploy bgdeploy` | Deprecated. <br> **Alternative:** Rolling deployment strategy by setting <br> `cfNativeDeployParameters = '--strategy rolling'` |
+|               | **deployDockerImage not supported** | **deployDockerImage supported**<br>Docker credentials can only be provided as Jenkins environment variable. |
 
 !!! note
     Due to [an incompatible change](https://github.com/cloudfoundry/cli/issues/1445) in the Cloud Foundry CLI, multiple buildpacks are not supported by this step.

resources/metadata/cloudFoundryDeploy.yaml

@@ -3,6 +3,14 @@ metadata:
   description: "Deploys an application to Cloud Foundry"
   longDescription: |
     Deploys an application to a test or production space within Cloud Foundry.
+    This step supports two deployment types:
+
+    * in a standard way
+    * in a zero-downtime manner using a [blue-green deployment approach](https://martinfowler.com/bliki/BlueGreenDeployment.html)
+
+    The step achieves this via following deploy tools
+    * [cf CLI](https://docs.cloudfoundry.org/cf-cli/) - used as default for Non MTA apps
+    * [MTA CF CLI Plugin](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin) - used as default for MTA apps
 spec:
   inputs:
     secrets:
@@ -98,11 +106,11 @@ spec:
       - name: deployDockerImage
         type: string
         description: "Docker image deployments are supported
-          (via manifest file in general)[https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#docker].
+          [via manifest file in general](https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#docker).
           If no manifest is used, this parameter defines the image to be deployed.
           The specified name of the image is passed to the `--docker-image` parameter of the cf CLI and must
           adhere it's naming pattern (e.g. REPO/IMAGE:TAG).
-          See (cf CLI documentation)[https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html]
+          See [cf CLI documentation](https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html)x`x`
           for details.
           Note: The used Docker registry must be visible for the targeted Cloud Foundry instance."
         scope:
@@ -113,7 +121,7 @@ spec:
         mandatory: false
       - name: deployTool
         type: string
-        description: "Defines the tool which should be used for deployment."
+        description: "Defines the tool which should be used for deployment. Mandatory if `buildTool` is not found in pipeline environment"
         scope:
           - PARAMETERS
           - STAGES
@@ -136,10 +144,9 @@ spec:
       - name: deployType
         type: string
         description:
-          "Defines the type of deployment, for example, `standard` deployment which results in a system
-          downtime, `blue-green` deployment which results in zero downtime for mta deploy tool.
-           - For mta build tool, possible values are `standard`, `blue-green` or `bg-deploy`.
-           - For cf native build tools, possible value is `standard`. To eliminate system downtime, an alternative is to pass '--strategy rolling' to the parameter `cfNativeDeployParameters`."
+          "Defines the type of deployment -`standard` or `blue-green` deployment.
+          For mta build tool, possible values are `standard`, `blue-green` or `bg-deploy`.
+          For cf native build tools, possible value is `standard`. To eliminate system downtime, an alternative is to pass '--strategy rolling' to the parameter `cfNativeDeployParameters`."
         scope:
           - PARAMETERS
           - STAGES
@@ -199,7 +206,7 @@ spec:
         mandatory: false
       - name: manifest
         type: string
-        description: "Defines the manifest to be used for deployment to Cloud Foundry."
+        description: "Defines the manifest file name to be used for deployment to Cloud Foundry. Defaults to `manifest.yml`"
         scope:
           - PARAMETERS
           - STAGES