Develop and deploy an application on IBM Cloud VPC using deployment strategies
Use this tutorial to understand how to create an open toolchain that uses different deployment strategies like Rolling, Blue-Green, and Canary to develop and deploy a simple Spring Java web app to IBM Cloud VPC. The tutorial takes you through the steps required to create a toolchain with the IBM Cloud Continuous Delivery service. This toolchain implements standard DevOps practices like setting up an application git repository, a PR (Pull Request) pipeline, CI (Continuous Integration) pipeline, and CD (Continuous Delivery) pipeline. In addition, this toolchain incorporates shift-left capabilities such as code-risk analysis, CIS scans, vulnerability scans that are integrated as part of the PR and CI pipelines.
The tutorial also guides you to provision a secure and scalable VPC infrastructure using IBM Cloud Schematics and terraform Infrastructure-As-Code (IAC) template required to adopt advanced deployment strategies like Rolling, Blue-Green, and Canary.
Once the VPC infrastructure is provisioned and the toolchain is created this tutorial takes you through the steps to change the application code, push that change to the application repository and test using PR pipelines. Once tested, we guide you through how to use the CI pipeline to build the application binary and use the CD pipeline to deploy the binary to the virtual server instances provisioned for the deployment strategy of your choice.
Please refer to Understanding the deployment strategies to know more about the deployment strategies currently implemented with IBM Cloud.
To set up the prerequisites for your toolchains, follow these steps:
-
Set up an IBM Cloud account. The template requires you to have a Standard plan. For more information, see Setting up your IBM Cloud account and Upgrading your account.
-
Provision the IBM Cloud VPC Infrastructure. Depending on the type of deployment strategy you plan to use, use the links to create the IBM Cloud Schematics workspace. The workspace generates and applies the terraform plan to create the VPC, Virtual server instances, and Load Balancer required to run and access the application.
-
Create an instance of the Continuous Delivery service.
-
Optional. Store your secrets in a secrets management vault and manage them centrally from a single location. Managing IBM Cloud secrets can help you to choose from various secrets management and data protection offerings. If you don't already have an instance of the secrets management vault provider of your choice, create one.
Any of the methods in this tutorial takes you to the guided setup experience. You are guided through the toolchain setup process in a logical order, and you are presented with the recommended configuration options that are needed to create your toolchain.
A progress indicator shows the steps to complete the configuration. You can use the progress indicator to navigate to a previous step with a mouse click. The configuration options for the current step are displayed in the main area of the page.
To advance to the next step, click Continue. You can advance to the next step only when the configuration for the current step is complete and valid. You can navigate to the previous step by clicking Back.
Some steps include an Advanced Options toggle. These steps by default present you with the minimum recommended configuration needed. However, advanced users that require finer-grained control can click the Advanced Options toggle to reveal all options for the underlying tool integration.
After all the steps are successfully completed, you create the toolchain by clicking Create on the Summary step.
TIP: You can always go back to the previous or explore the next steps in the guided installer. The toolchain installer retains all the configuration settings from the successive steps.
Start the toolchain configuration by selecting the Develop and Deploy application to VPC using deployment strategies template from the Toolchains catalog.
Alternately, use the Create toolchain button below to create the toolchain.
Review the default information for the toolchain settings. The toolchain's name identifies it in IBM Cloud. Make sure that the toolchain's name is unique within your toolchains for the same region and resource group in IBM Cloud.
Note: The present tutorial creates the toolchain in the us-south region. Please select the appropriate region for your toolchain.
The toolchain creates a Continuous Deployment Pipeline to deploy the application (executable java jar for the sample) on virtual machine instances within VPC. Select from one of the deployment strategies Rolling, Blue-Green, or Canary. Each deployment strategy requires a different configuration of VPC Infrastructure. Therefore, it's required to first create the appropriate configuration and then return to this step to proceed further with the toolchain setup.
Clicking on the link provided in the tile takes you to the IBM Cloud Schematics page. For more help on using IBM Cloud Schematics refer to the documentation.
The Application step that refers to the application source code repository is shown in the following image. The toolchain template provides a sample Java Spring App using a maven build.
The PR (Pull Request) and CI (Continous Integration) pipeline build the application source code from the application source code repository.
The Inventory step that refers to the inventory repository is shown in the following image. The inventory repository records details of artifacts that are built by the CI toolchains.
The CI (Continuous Integration) pipeline uploads the built artifact (e.g jar) to the COS (Cloud Object Store) and corresponding metadata in JSON format to the inventory repository configured in this step. Later, when the CD (Continuous Deployment) pipeline is triggered, the build metadata is read from the inventory repository and the same artifact is pulled from the artifact store (Cloud Object Store)
Several tools in this toolchain require secrets to access privileged resources. An IBM Cloud API key is an example of such a secret. All secrets should be stored securely in a secrets vault and then referenced as required by the toolchain.
With IBM Cloud, you can choose from various secrets management and data protection offerings that help you to protect your sensitive data and centralize your secret. The secrets step allows you to specify which secret vault integrations are added to your toolchain. Use the provided toggles to add or remove the vault integrations that you require as explained in Managing IBM Cloud secrets.
This tutorial uses IBM Secrets Manager as the vault for secrets.
Use IBM Secrets Manager to securely store and apply secrets like API keys, Image Signature, or HashiCorp credentials that are part of your toolchain.
Refer to the details for IBM Key Protect or HashiCorp vault for managing your secrets in case you plan to use either of them instead of Secrets Manager
Based on the selection of deployment strategy earlier, this step lets you configure the deployment target for the toolchain.
- Setup deployment target for Rolling
- Setup deployment target for Blue-Green
- Setup deployment target for Canary
- Setup deployment target for Basic
Any change to the source triggers the continuous integration pipeline. When a continuous integration run succeeds, a build or binary artifact is created and saved in transient storage, and then deployed to the target Virtual Server Instances.
The toolchain provides the option to use IBM Cloud Cloud Object Store (COS) to store transient build artifacts. In the case of the sample Spring Java App, the executable jar file is built by the Continuous Integration (CI) pipeline.
Alternatively, you may choose to use Artifactory if you have an Artifactory instance of your own.
DevOps Insights
IBM Cloud DevOps Insights is included in the created toolchain. You do not need to provide any configuration steps for DevOps Insights, the CI pipeline will automatically use the insights instance included in the toolchain. DevOps Insights aggregates code, test, build, and deployment data to provide visibility into the velocity and quality of all your teams and releases.
On the Summary page, click Create, and wait for the toolchain to be created.
TIP: The individual toolchain integrations can be configured also after the pipeline is created.
Once created, the toolchain looks like below
The toolchain contains three pipelines:
-
Pull Request (PR) Pipeline: This pipeline is triggered when a merge or pull request is created in the Application source code repository. Typically, this request is manually created by the application source code developer to merge changes from their development branch to the master branch or any other branch. The PR Pipeline runs the Unit Tests and Static Scans on the Application source code.
-
Continuous Integration (CI) Pipeline: This pipeline is triggered when a change is merged to the master branch of the Application source code repository. The CI Pipeline runs the Unit Tests, Code Coverage, Static Scans, performs CIS checks, and generates a BOM (Bill Of Materials for the Application source code. The CI Pipeline generates the binary build artifact and uploads it to the Cloud Object Storage or Artifactory as configured in the toolchain. The CI Pipeline also generates the metadata of the build artifacts and stores it in the Inventory repository.
-
Continuous Deployment (CD) Pipeline: The CD Pipeline is responsible for the deployment of the build artifacts to the deployment environment. The pipeline verifies the successful deployment of the application by running a health check. This pipeline must be manually triggered after the successful completion of the CI Pipeline. Depending on the deployment strategy selected, additional triggers are configured for the CD Pipeline.
To start the PR pipeline, create a merge request in your application repository. To achieve this, do the following:
- On the toolchain page, click the application repository tile. By default, it gets created with a name compliance-app-
- Create a branch from master
- Update some code in the application or readme file and Save changes.
- Submit merge request.
- Back on the toolchain page, click the
pr-pipelinetile. Observe: the PR pipeline has been initiated.
The corresponding Merge Request in your application repository will be in the "Pending" state until all the stages of the PR Pipeline finish successfully.
After the PR Pipeline run is successful, click to explore the steps executed by the pipeline.
To start the CI Pipeline, navigate back to the merge request created earlier in your application repository.
- Click the
Mergebutton, to merge changes from the branch created in the earlier step to the master. - Back on the toolchain page observe that the CI pipeline is triggered automatically.
- Click the
ci-pipelinetile. - Observe the running CI pipeline and wait for the pipeline run to finish.
After the CI Pipeline run is successful, click to explore the steps executed by the pipeline.
The PR and CI pipelines discussed earlier are common across all the deployment strategies. The CD Pipeline design and implementation changes are based on the deployment strategy selected earlier.
To know more about the CD pipeline run for the deployment strategy,
This sub-step configures the toolchain with information about the Virtual Private Cloud (VPC) and the Virtual Server Instances (VSI) that you have provisioned using IBM Cloud Schematics and Terraform in the Select the Deployment Strategy step.
- Virtual Private Cloud Region: Select the region in which you have provisioned the Virtual Private Cloud.
- Virtual Private Cloud Name: Select from a list of all the VPC's present in the region of your selection. Select the VPC that you provisioned using the terraform template.
- Username for VPC Instances: All the Virtual Server Instances in your VPC requires a username and ssh key to log in and perform the deployment operation. Provide the Username for VPC Instances that you configured while provisioning.
- Base64 Encoded SSH Key for VPC Instances: Provide the private SSH key in base64 encoded form for the public SSH key that you configured while provisioning instances.
The Terraform template also creates an additional VSI to be used as a bastion host. Bastion host provides a secure way to connect to the VSI's within your VPC to carry out deployment and maintenance tasks. The bastion host connects to the VSI's over SSH by using the credentials (username and ssh key) that you configure in the sub-step above.
The toolchain requires login to the VSI's within the VPC to deploy the application binary, start/stop the application, download the third-party dependency to run the application. All these tasks are achieved by using SSH-Tunneling with the bastion host. Please note that the toolchain uses the same credentials to log in to the bastion host as is used by the bastion host to connect to the VSI's.
- Bastion Host: Select from the list of VSI's, the one which is provisioned as a bastion host by the terraform template.
The sample application deployed on the VSI's in your VPC exposes a simple web page on port 8080. To make the application available over the internet using a DNS name and also to load balance the traffic between multiple VSI's running the application, the terraform template provisions an Application Load Balancer. All the VSI's running the application form the backend pool of servers for the load balancer.
The toolchain uses the details for the load balancer and backend pool to configure and redirect the live application traffic during the rolling deployment process so that no traffic is routed to the VSI on which deployment is being performed.
- Load Balancer name: Select the application load balancer provisioned by the terraform template.
- Backend pool name: Select the backend pool for the load balancer selected in the previous step.
This sub-step configures the toolchain with information about the Virtual Private Cloud (VPC) and the Virtual Server Instances (VSI) that you have provisioned using IBM Cloud Schematics and Terraform in the Select the Deployment Strategy step.
- Virtual Private Cloud Region: Select the region in which you have provisioned the Virtual Private Cloud.
- Virtual Private Cloud Name: Select from a list of all the VPC's present in the region of your selection. Select the VPC that you provisioned using the terraform template.
- Username for VPC Instances: All the Virtual Server Instances in your VPC requires a username and ssh key to log in and perform the deployment operation. Provide the Username for VPC Instances that you configured while provisioning.
- Base64 Encoded SSH Key for VPC Instances: Provide the private SSH key in base64 encoded form for the public SSH key that you configured while provisioning instances.
The Terraform template also creates an additional VSI to be used as a bastion host. Bastion host provides a secure way to connect to the VSI's within your VPC to carry out deployment and maintenance tasks. The bastion host connects to the VSI's over SSH by using the credentials (username and ssh key) that you configure in the sub-step above.
The toolchain requires login to the VSI's within the VPC to deploy the application binary, start/stop the application, download the third-party dependency to run the application. All these tasks are achieved by using SSH-Tunneling with the bastion host. Please note that the toolchain uses the same credentials to log in to the bastion host as is used by the bastion host to connect to the VSI's.
- Bastion Host: Select from the list of VSI's, the one which is provisioned as a bastion host by the terraform template.
The sample application deployed on the VSI's in your VPC exposes a simple web page on port 8080. To make the application available over the internet using a DNS name and also to load balance the traffic between multiple VSI's running the application, the terraform template provisions an Application Load Balancer. All the VSI's running the application form the backend pool of servers for the load balancer.
The toolchain uses the details for the load balancer and 2 backend pools to configure and redirect the live application traffic during the blue-green deployment process. The blue backend pool and green backend pool contain exactly the same number of VSI's. At any given time only one of the pools actively serves the live traffic while the other remains idle running an older version of the application. The load balancer swaps or toggles the backend pool serving live traffic with each deployment. So while the blue backend pool is active currently, the next deployment will deploy the application on VSI's in the green backend pool and make it active while the blue backend pool goes passive.
- Load Balancer name: Select the application load balancer provisioned by the terraform template.
- Blue Backend pool name: Select the blue backend pool for the load balancer as provisioned by the terraform template.
- Green Backend pool name: Select the green backend pool for the load balancer as provisioned by the terraform template.
This sub-step configures the toolchain with information about the Virtual Private Cloud (VPC) and the Virtual Server Instances (VSI) that you have provisioned using IBM Cloud Schematics and Terraform in the Select the Deployment Strategy step.
- Virtual Private Cloud Region: Select the region in which you have provisioned the Virtual Private Cloud.
- Virtual Private Cloud Name: Select from a list of all the VPC's present in the region of your selection. Select the VPC that you provisioned using the terraform template.
- Username for VPC Instances: All the Virtual Server Instances in your VPC requires a username and ssh key to log in and perform the deployment operation. Provide the Username for VPC Instances that you configured while provisioning.
- Base64 Encoded SSH Key for VPC Instances: Provide the private SSH key in base64 encoded form for the public SSH key that you configured while provisioning instances.
The Terraform template also creates an additional VSI to be used as a bastion host. Bastion host provides a secure way to connect to the VSI's within your VPC to carry out deployment and maintenance tasks. The bastion host connects to the VSI's over SSH by using the credentials (username and ssh key) that you configure in the sub-step above.
The toolchain requires login to the VSI's within the VPC to deploy the application binary, start/stop the application, download the third-party dependency to run the application. All these tasks are achieved by using SSH-Tunneling with the bastion host. Please note that the toolchain uses the same credentials to log in to the bastion host as is used by the bastion host to connect to the VSI's.
- Bastion Host: Select from the list of VSI's, the one which is provisioned as a bastion host by the terraform template.
The sample application deployed on the VSI's in your VPC exposes a simple web page on port 8080. To make the application available over the internet using a DNS name and also to load balance the traffic between multiple VSI's running the application, the terraform template provisions an Application Load Balancer. All the VSI's running the application form the backend pool of servers for the load balancer.
The toolchain uses the details for the load balancer and 1 backend pool to configure and redirect the live application traffic during the canary deployment process. The toolchain leverages the weighted round-robin strategy to gradually increase the traffic to the instances with the new version of the application deployed while decreasing the traffic to the instances with the older ones.
- Load Balancer name: Select the application load balancer provisioned by the terraform template.
- Backend pool name: Select the backend pool for the load balancer selected in the previous step.
The instance group provides a logical grouping of VSI's running the same version of the application. The terraform template creates two instance groups with exactly the same number and identical configurations for the VSI's. These instance groups are internally identified as canary and prod. At any given time only VSI's that belong to one of the two instance groups actively serves the live traffic while the other remains idle running an older version of the application.
During a canary deployment, the toolchain deploys the application to the VSI's of the canary instance group while the VSI's in the prod keeps serving the live traffic.
- Instance group 1: Select the instance group provisioned by the terraform template.
- Instance group 2: Select the other instance group provisioned by the terraform template.
Once deployment succeeds, the toolchain configures the backend pool to gradually increase traffic to the instances in the canary instance group while simultaneously decreasing the traffic to instances in the prod instance group.
- Canary step size: Defines how much amount of traffic needs to be redirected to a new release of Canary deployment.
- Canary step interval: Defines interval time between each Canary test to move to the new release of Canary deployment.
The CD pipeline offers two triggers for the rolling deployment. You can start a CD pipeline in either of the following ways:
- Trigger the CD pipeline manually.
- Automatically after every
Mergeaction in Inventory Repository. After the merge, you must manually trigger the run of CD Pipeline. A GRIT trigger is set up to trigger an automatic CD Pipeline, but is disabled by default and can be enabled after the first promotion.
In this strategy, the deployment happens without any downtime by incrementally updating all production instances with the new version of the software.
Rollback requires redeploying the previous release, which may not be immediate.
Once the CD pipeline run is successful, the app URL can be found under the deploy step of the CD pipeline.
In this deployment strategy, you can leverage two permanent production environments (blue and green) with only one receiving traffic at any time. Deploy the new release to the idle environment, then switch all traffic to it with no downtime. For rapid rollback, simply switch all traffic back to the other environment that remained unchanged.
The CD pipeline offers three triggers for the blue-green deployment.
- You can start a CD pipeline in either of the following ways:
- Trigger the CD pipeline manually.
- Automatically after every
Mergeaction in Inventory Repository.
- The third trigger is provided for a switch between blue and green deployment for an automated and faster rollback.
This tutorial shows how the blue-green deployment strategy works using the sample app.
a. Run the manual trigger from the CD pipeline to deploy the first version of the app.
b. Wait till the CD Pipeline run is completed and successful.
c. Once, the CD Pipeline run is successful, the app URL can be found under the release step of the CD pipeline
d. Check the app is running.
e. Now, update the app code and commit your changes. For the sample app, we will update the welcome message displayed on the app. This can be done by navigating to the sample app repo tile on the toolchain page and updating the welcome message in utils.js
f. Observe that it will initiate the CI pipeline. Wait till the CI pipeline is successfully completed.
g. Once the CI pipeline is completed, run the manual trigger from the CD pipeline as explained earlier and wait till the CD Pipeline run is completed and successful.
h. Check the app URL again to notice the updated app has been deployed.
i. Both the app versions are now running simultaneously. All the network traffic is currently flowing to the updated app. To test the rollback, run the switch-blue-green trigger from the CD pipeline and wait for it to get completed and successful.
j. Check the same app URL again to find that you can see the old version of the app again.
g. You can run the switch trigger multiple times to keep alternating between the old and new versions of the app.
The Canary deployment strategy deploys a new release in parallel with the original production environment (similar to Blue-Green), with no downtime. In this case, the amount of traffic that is sent to both the updated and original instances is managed, so that the new version can be experienced by a controlled subset of the users while deployment is proceeding. Over time, the traffic being sent to the new version is increased until all traffic is being sent there, at which point the old production environment can be stopped. For rapid rollback, while deployment is in progress, all traffic can be routed back to the original production environment.
The CD pipeline offers three triggers for the blue-green deployment.
- You can start a CD pipeline in either of the following ways:
- Trigger the CD pipeline manually.
- Automatically after every Merge action in Inventory Repository.
- The third trigger,
abort-deployment, helps abort an ongoing canary deployment and revert all the traffic to the original production environment.
This tutorial shows how the blue-green deployment strategy works using the sample app.
a. Run the manual trigger from the CD pipeline to deploy the first version of the app.
b. Wait till the CD Pipeline run is completed and successful.
c. Once, the CD Pipeline run is successful, the app URL can be found under the prod-deployment step of the CD pipeline.
d. Check the app is runnig.
e. e. Now, update the app code and commit your changes. For the sample app, we will update the welcome message displayed on the app. This can be done by navigating to the sample app repo tile on the toolchain page and updating the welcome message in utils.js
f. Observe that it will initiate the CI pipeline. Wait till the CI pipeline is successfully completed.
g. Once the CI pipeline is completed, run the manual trigger from the CD pipeline as explained earlier. The step canary deployment will deploy the new release immediately. Post that the step canary-test will run for the time decided by Canary step size and Canary step interval mentioned in the setup step. In this step, the traffic will be incrementally diverted to the new release.
h. Once the canary-test step is complete, the new release will be accessible on the app URL
i. When the canary-test step is running, you can abort the process of diverting network traffic to a new release by running the abort-deployment trigger and send all the traffic to the original production environment.
j. Wait for the abort deployment trigger to complete and check the app URL points back to the original production environment.
i. After the abort-deployment CD pipeline run is complete, the parallel running CD pipeline run for the new production environment is aborted and marked as failed.
j. Please note the abort-deployment trigger works only when the canary-test step is running. Once that step is successful, you cannot revert to the original traffic using this trigger. The old app will have to be redeployed using the manual trigger as explained earlier.