You've already forked sap-jenkins-library
mirror of
https://github.com/SAP/jenkins-library.git
synced 2025-09-16 09:26:22 +02:00
Improve CF documentation (#5274)
* Improve CF documentation * Lint fix --------- Co-authored-by: maxcask <bondarcask@gmail.com>
This commit is contained in:
Ashly Mathew
GitHub
@@ -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.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")
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user