Improve CF documentation (#5274)

* Improve CF documentation

* Lint fix

---------

Co-authored-by: maxcask <bondarcask@gmail.com>

cmd/cloudFoundryDeploy_generated.go

@@ -113,7 +113,15 @@ func CloudFoundryDeployCommand() *cobra.Command {
 	var createCloudFoundryDeployCmd = &cobra.Command{
 		Use:   STEP_NAME,
 		Short: "Deploys an application to Cloud Foundry",
-		Long:  `Deploys an application to a test or production space within Cloud Foundry.`,
+		Long: `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`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			startTime = time.Now()
 			log.SetStepName(STEP_NAME)
@@ -231,15 +239,15 @@ func addCloudFoundryDeployFlags(cmd *cobra.Command, stepConfig *cloudFoundryDepl
 	cmd.Flags().StringVar(&stepConfig.CfHome, "cfHome", os.Getenv("PIPER_cfHome"), "The cf home folder used by the cf cli. If not provided the default assumed by the cf cli is used.")
 	cmd.Flags().StringVar(&stepConfig.CfNativeDeployParameters, "cfNativeDeployParameters", os.Getenv("PIPER_cfNativeDeployParameters"), "Additional parameters passed to cf native deployment command")
 	cmd.Flags().StringVar(&stepConfig.CfPluginHome, "cfPluginHome", os.Getenv("PIPER_cfPluginHome"), "The cf plugin home folder used by the cf cli. If not provided the default assumed by the cf cli is used.")
-	cmd.Flags().StringVar(&stepConfig.DeployDockerImage, "deployDockerImage", os.Getenv("PIPER_deployDockerImage"), "Docker image deployments are supported (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] for details. Note: The used Docker registry must be visible for the targeted Cloud Foundry instance.")
+	cmd.Flags().StringVar(&stepConfig.DeployDockerImage, "deployDockerImage", os.Getenv("PIPER_deployDockerImage"), "Docker image deployments are supported [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)x`x` for details. Note: The used Docker registry must be visible for the targeted Cloud Foundry instance.")
-	cmd.Flags().StringVar(&stepConfig.DeployTool, "deployTool", os.Getenv("PIPER_deployTool"), "Defines the tool which should be used for deployment.")
+	cmd.Flags().StringVar(&stepConfig.DeployTool, "deployTool", os.Getenv("PIPER_deployTool"), "Defines the tool which should be used for deployment. Mandatory if `buildTool` is not found in pipeline environment")
 	cmd.Flags().StringVar(&stepConfig.BuildTool, "buildTool", os.Getenv("PIPER_buildTool"), "Defines the tool which is used for building the artifact. If provided, `deployTool` is automatically derived from it. For MTA projects, `deployTool` defaults to `mtaDeployPlugin`. For other projects `cf_native` will be used.")
-	cmd.Flags().StringVar(&stepConfig.DeployType, "deployType", `standard`, "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`.")
+	cmd.Flags().StringVar(&stepConfig.DeployType, "deployType", `standard`, "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`.")
 	cmd.Flags().StringVar(&stepConfig.DockerPassword, "dockerPassword", os.Getenv("PIPER_dockerPassword"), "If the specified image in `deployDockerImage` is contained in a Docker registry, which requires authorization, this defines the password to be used.")
 	cmd.Flags().StringVar(&stepConfig.DockerUsername, "dockerUsername", os.Getenv("PIPER_dockerUsername"), "If the specified image in `deployDockerImage` is contained in a Docker registry, which requires authorization, this defines the username to be used.")
 	cmd.Flags().BoolVar(&stepConfig.KeepOldInstance, "keepOldInstance", false, "If this option is set to true the old instance will remain stopped in the Cloud Foundry space.\"")
 	cmd.Flags().StringVar(&stepConfig.LoginParameters, "loginParameters", os.Getenv("PIPER_loginParameters"), "Addition command line options for cf login command. No escaping/quoting is performed. Not recommended for productive environments.")
-	cmd.Flags().StringVar(&stepConfig.Manifest, "manifest", os.Getenv("PIPER_manifest"), "Defines the manifest to be used for deployment to Cloud Foundry.")
+	cmd.Flags().StringVar(&stepConfig.Manifest, "manifest", os.Getenv("PIPER_manifest"), "Defines the manifest file name to be used for deployment to Cloud Foundry. Defaults to `manifest.yml`")
 	cmd.Flags().StringSliceVar(&stepConfig.ManifestVariables, "manifestVariables", []string{}, "Defines a list of variables in the form `key=value` which are used for variable substitution within the file given by manifest.")
 	cmd.Flags().StringSliceVar(&stepConfig.ManifestVariablesFiles, "manifestVariablesFiles", []string{`manifest-variables.yml`}, "path(s) of the Yaml file(s) containing the variable values to use as a replacement in the manifest file. The order of the files is relevant in case there are conflicting variable names and values within variable files. In such a case, the values of the last file win.")
 	cmd.Flags().StringVar(&stepConfig.MtaDeployParameters, "mtaDeployParameters", `-f`, "Additional parameters passed to mta deployment command")

documentation/docs/steps/cloudFoundryDeploy.md

@@ -4,22 +4,37 @@
 
 ### Additional Hints
 
-Deployment can be done
+#### Standard CF deployments
 
-* in a standard way
+`deployType` parameter defaults to value `standard`.<br>
-* in a zero-downtime manner (using a [blue-green deployment approach](https://martinfowler.com/bliki/BlueGreenDeployment.html))
+This means that CF CLI is called by piper and command `cf push` is run by piper
 
-!!! note "Deployment supports multiple deployment tools"
+#### Blue green deployments
-    Currently the following are supported:
 
-    * Standard `cf push` and [Bluemix blue-green plugin](https://github.com/bluemixgaragelondon/cf-blue-green-deploy#how-to-use)
+**With CF CLI**
-    * [MTA CF CLI Plugin](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin)
 
-!!! note "Blue-Green Deployment with MTA CF CLI Plugin"
+* Blue green deployments are deprecated, but [rolling deployment strategy](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html) is supported.<br>
-    The Multiapps Plugin offers 2 different strategies:
+* For rolling deployment strategy , set parameter `cfNativeDeployParameters:'--strategy rolling'`
   
-    * [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`.
+**With [MTA CF CLI Plugin](https://github.com/cloudfoundry-incubator/multiapps-cli-plugin) for MTA applications**
-    * [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
+          "Defines the type of deployment -`standard` or `blue-green` deployment.
-          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 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`."
-           - 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