From 0db9a699038d35ce3bb97a59d2347c37c1904715 Mon Sep 17 00:00:00 2001 From: Ashly Mathew Date: Mon, 17 Feb 2025 15:14:02 +0100 Subject: [PATCH] Improve CF documentation --- cmd/cloudFoundryDeploy_generated.go | 18 +++++++++---- .../docs/steps/cloudFoundryDeploy.md | 25 ++++++++++++------- resources/metadata/cloudFoundryDeploy.yaml | 23 +++++++++++------ 3 files changed, 44 insertions(+), 22 deletions(-) diff --git a/cmd/cloudFoundryDeploy_generated.go b/cmd/cloudFoundryDeploy_generated.go index 6d4643ecba6..c64b213c6dd 100644 --- a/cmd/cloudFoundryDeploy_generated.go +++ b/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 with some possible system downtime during app deployment +* 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.DeployTool, "deployTool", os.Getenv("PIPER_deployTool"), "Defines the tool which should be used for deployment.") + 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. 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") diff --git a/documentation/docs/steps/cloudFoundryDeploy.md b/documentation/docs/steps/cloudFoundryDeploy.md index 3a141f2b437..f97b89a2bde 100644 --- a/documentation/docs/steps/cloudFoundryDeploy.md +++ b/documentation/docs/steps/cloudFoundryDeploy.md @@ -4,23 +4,30 @@ ### 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` +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 +* With CF CLI + * Blue green deployments are deprecated, but [rolling deployment strategy](https://docs.cloudfoundry.org/devguide/deploy-apps/rolling-deploy.html) is supported. + * 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 - * 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) - -!!! note "Blue-Green Deployment with MTA CF CLI Plugin" The Multiapps Plugin offers 2 different strategies: * [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` +| deployType | MTA Applications | Non MTA Applications | +|-------------|-----------------|----------------------| +| **standard** | deployTool = mtaDeployPlugin
Uses MTA plugin,
Piper calls command `cf deploy` | deployTool = cf_native
cf CLI used
Piper calls command `cf push`
Requires Manifest file and app name
appname can be provided as step parameter or via manifest file. | +| **blue-green** | deployTool = mtaDeployPlugin,
Uses MTA plugin
Piper calls command `cf deploy bgdeploy` | Deprecated.
**Alternative:** Rolling deployment strategy by setting parameter
`cfNativeDeployParameters = '--strategy rolling'` | +| **deployDockerImage** | Not supported | Supported, 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. If your `application` contains a list of `buildpacks` instead of a single `buildpack`, this will be automatically re-written by the step when blue-green deployment is used. diff --git a/resources/metadata/cloudFoundryDeploy.yaml b/resources/metadata/cloudFoundryDeploy.yaml index 921000fdd55..cd97238b75a 100644 --- a/resources/metadata/cloudFoundryDeploy.yaml +++ b/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 with some possible system downtime during app deployment + * 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