Develop and deploy an application on Kubernetes using deployment strategies
Use this tutorial to understand how to create an open toolchain that supports different deployment strategies, how they are implemented in IBM Cloud Continuous Delivery service, and how to develop and deploy a simple, Kubernetes-based web app using them. The toolchain implements standard DevOps practices like code scanning, acceptance tests, git repo, CI, and CD capabilities. After you create the cluster and toolchain, changing your app's code and pushing the change to the Git Repos and Issue Tracking repository (repo), causes the Tekton-based delivery pipeline to automatically build and deploy the code.
Tekton is an open-source, vendor-neutral, Kubernetes-native framework that you can use to build, test, and deploy apps. Tekton provides a set of shared components for building continuous integration and continuous delivery (CICD) systems. As an open-source project, Tekton is managed by the Continuous Delivery Foundation (CDF), which has the goal of modernizing continuous delivery by providing industry specifications for pipelines, workflows, and other building blocks. With Tekton, you can build, test, and deploy across cloud providers or on-premise systems by abstracting the underlying implementation details.
Read more about the IBM Cloud Kubernetes Service.
The template used by this tutorial works with both standard or lite plans for Kubernetes. The standard plan gives you the ability to access your app via DNS name, whereas in the lite plan, the app is only available via nodeport.
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. Depending on your IBM Cloud account type, access to certain resources might be limited. Depending on your account plan limits, certain capabilities that are required by some of the deployment strategies might not be available. For more information, see Setting up your IBM Cloud account and Upgrading your account.
- You need a Kubernetes cluster and an API key. You can create them by using either the UI or the CLI. The cluster might take some time to provision. As the cluster is created, it progresses through these stages: Deploying, Pending, and Ready. Learn more. Rolling and Blue/green deployments can be tried on a lite plan but for Canary, you must create a Kubernetes cluster with a standard plan.
- You will need 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.
- Optional. Create a namespace by using the container registry command line. In a command-line window, enter the command: ibmcloud cr namespace-add Alternatively, you can create a namespace on the Container Registry page. For more information, see IBM Cloud Container Registry service.
The target cluster is configured during toolchain setup (by using an IBM Cloud API key and cluster name). You can later change these settings by altering the Delivery Pipeline configuration. Any code merged to the target Git repository branch is automatically built, validated, and deployed into the Kubernetes cluster.
Any of the methods in this tutorial take 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 need finer-grained control can click the Advanced Options toggle to reveal all options for the underlying 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.
You'll create a "Develop a Kubernetes app" toolchain. For this task, you need your API key and Kubernetes cluster name.
Start the toolchain configuration by clicking the Create toolchain button.
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 toolchain region can differ from the cluster and registry region.
The toolchain creates a Continuous Deployment Pipeline to deploy the application docker image on IBM Kubernetes Services. Select from one of the deployment strategies "Rolling", "Blue-Green" or "Canary". Based on your selection you will have to provide additional details to the deployment target step.
The following example shows the Rolling deployment strategy as an example.
Multiple repositories must be configured during the guided setup, as described in the following sections.
The Application step configures the application source code repository, as shown in the following image. The recommended options are displayed by default, but you can click the Advanced Options toggle to see all of the configuration options available for the underlying Git integration. The default behavior of the toolchain is to Use default sample, which creates an IBM hosted GRIT Repository that contains a simple, sample application. You can change the name of the application repository.
The region of the repository remains the same as the region of the toolchain.
The toolchain template provides a sample NodeJS app. If you want to link an existing Application Repository for the toolchain, select the Bring your own app option, and provide it as input to the Repository URL field. As noted earlier, the toolchain currently supports linking only to existing GRIT repositories.
By default, the application repository template will be cloned to your Git Repo and Issue Tracking organization. To change the organization, enable Advanced options, and edit the Repository owner field.
The inventory repository records details of artifacts that are built by the CI pipeline. You can choose to either create a new inventory repository, which will be a clone of the inventory repository template or use an existing inventory repository that you are sharing between toolchains.
By default, the inventory repository template will be cloned to your Git Repo and Issue Tracking organization. To change the organization, enable Advanced options, and edit the Repository owner field.
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 documentation gives you information on prerequisites and how to use a list of prescribed secret names that are otherwise known as hints. By using hints in a template, a toolchain can be automatically populated with preconfigured secrets without any need to manually select them from various vault integrations that are attached to the toolchain.
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
Configure the target Kubernetes cluster where the application will be deployed. Once the application passes the build, test, and scan phase the pipeline deploys the built application image to target the Kubernetes cluster. This deployment is then ready for acceptance test or integration test.
Using the API key that is either created, retrieved from a vault, or manually entered the following fields load automatically if the API key has sufficient access. If the API key is valid, the Container registry region and namespace Cluster region, name, namespace, and Resource group will be automatically populated. You may change any of these fields to match your configuration if needed.
-
App name: The name of the application.
- Default: hello-containers
-
IBM Cloud API Key: The API key is used to interact with the ibmcloud CLI tool in several tasks.
- Preferred: An existing key can be imported from an existing secret vault of your choice by clicking the key icon.
- An existing key can be copy and pasted.
- A new key can be created from here by clicking the New +.
- Generate a new api-key if you don’t have one or copy an existing key to the field.
TIP: The newly generated API key can be immediately saved to an existing secret vault of your choice.
The deployment is carried out as per the deployment strategy you have selected earlier in the Select Deployment Strategy step of the guided setup. The snapshot below shows the details if you would have selected Rolling or Blue-Green
In case you chose Canary in the Select Deployment Strategy step of the guided setup, there are additional details needed in the Deployment Target step of the guided setup.
-
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.
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.
The created toolchain will look like this:
It 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 Test 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 Test, Code Coverage, Static Scans on the Application Source Code, CIS check, and Bill Of Materials (BOM) check. The CI Pipeline also generates the binary build artifact and uploads them to the IBM Container Registry as configured in the toolchain. And the CI Pipeline 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 the health check. This pipeline must be manually triggered after the successful completion of the CI Pipeline. Depending on the deployment strategy selected, more triggers are added to the CD Pipeline.
To start the PR pipeline, you should 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 sample node app 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, you can click it to explore numerous steps completed.
- Navigate back to the merge request.
- Merge the request so that your changes are copied to the master branch of your application repository: the CI pipeline is automatically triggered.
- On the CI toolchain page, click the
ci-pipelinetile. - Observe: a pipeline run is running. Wait for the pipeline run to complete.
After the CI Pipeline run is successful, you can click it to explore the completed steps.
In the secure app development world, shift left is a practice referred to as preventing and finding issues like defects, security vulnerabilities and performing compliance checks early in the software delivery process.
- Checks that can be run on the code/repository itself and do not need the built image, should be run as early as possible to prevent non-compliant code from being merged to the master branch of the repository. Evidence is not collected from the PR pipeline, its goal is to shift compliance checks, as far left as possible.
- All checks are done every pipeline run, even if a previous check fails, the pipeline progresses to the next one. To evaluate if you have any failures in your run, you need to check the final step of your pipeline, which has a pipeline evaluator.
Results from unit tests run, vulnerability scans are published to the DevOps Insights instance inside the toolchain. You can navigate to it by clicking the DevOps Insights tool card in the toolchain. You can review the collected evidence on the Quality Dashboard page.
Note: To evaluate if you have any failures in your pipeline run, you need to check the final step of your pipeline, which has a pipeline evaluator.
The PR and CI Pipeline are common across all the deployment strategies. The CD Pipeline design and implementation changes are based on the deployment strategy selected earlier.
Please click on the explore the link below for the deployment strategy you have selected in the setup step and would like to know more on how it works:
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 perform deployment 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.
k. 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 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 parallely 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 redeployed using the manual trigger as explained earlier.
In case you want to remove the sample app running you need to clean Kubernetes cluster at following places.
- Go to Kubernetes Cluster homepage.
- Select the cluster where the sample app is running.
- Click on
Kubernetes dashboard
- Choose the
namespacefrom the drop-down where the sample app is running
- Delete the related deployments, services and ingresses
- Getting started with clusters
- Getting started with toolchains
- Getting started with Continuous Delivery
Get help fast directly from the IBM Cloud Continuous Delivery development teams by joining us on Slack.
For more support options, see Getting help and support for Continuous Delivery.