Deploy an app on Kubernetes
In this tutorial, you learn how to create an open toolchain by using different deployment strategies. You also learn how toolchains are implemented in the IBM Cloud® Continuous Delivery service and how to develop and deploy a simple web application (app) by using toolchains.
This tutorial is browser-based. You can also create a similar open toolchain in Terraform as shown in the IBM Cloud Terraform Provider example ibm-cd-toolchain-simple-helm.
This tutorial uses deployment strategies that have Kubernetes as the deployment target. The toolchain that is used in this tutorial implements standard DevOps practices such as code scanning, acceptance tests, Git repos, and continuous integration and continuous delivery capabilities. After you create a Kubernetes cluster and a toolchain, you change your app's code and push the change to the Git Repos and Issue Tracking repo. When you push changes to your repo, the Tekton-based delivery pipeline automatically builds and deploys 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 systems. As an open source project, Tekton is managed by the Continuous Delivery Foundation. The goal is to modernize 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-premises systems by abstracting the underlying implementation details. Tekton pipelines are built into Continuous Delivery.
The template that is used in this tutorial works with either the Standard or Lite plan for Kubernetes. With the Standard plan, you can access your app by way of the DNS name. In the Lite plan, you can access your app by using nodeport.
You can use a deployment strategy to update an application in a production environment, in a controlled manner. Using a deployment strategy can provide the following benefits:
- Avoid application downtime.
- Enable production testing of new functions without impacting customers.
- Limit the impact of production issues to a subset of users.
- Enable rapid rollback to the previous version if issues are found.
Many possible deployment strategies are available. In general, they depend on running multiple instances of the application and managing how the various instances are updated. You can pre-configure the following common deployment strategies in Continuous Delivery:
- Basic
- Deploys the new release by stopping and updating all of the running instances simultaneously, causing downtime. For rollback, you must deploy the previous version again, which causes extra downtime. Although this strategy is simple, fast, and has low runtime resource requirements, it is the riskiest and causes downtime. The Basic deployment strategy is not recommended for critical apps that must be highly available.
- Rolling update
- Similar to the Basic strategy, this deployment strategy is simple, fast, and has low runtime resource requirements. However, because each running instance is taken down and updated individually, avoiding downtime, rollback requires you to deploy the previous release again. This time consuming approach might cause issues if the current version of the app in production is broken.
- Blue-Green deployment
- Creates two separate, permanent production environments (blue and green), and only one of those environments receives traffic at a time. The current release is always deployed to the idle environment and traffic is switched to it after deployment completes, with no downtime. Because you need to switch only the traffic to the unchanged environment, rollback does not cause downtime. Because this strategy requires two full production environments, the resource requirements are higher. However, this strategy enables powerful Developer flows, such as the ability to test new app versions in the production environment before it allows customer traffic. Blue-Green deployment also supports fast rollback.
- Canary release
- Deploys a new release in parallel with the original production environment (similar to Blue-Green), with no downtime. The amount of traffic that is sent to both the updated and original instances is managed so that the new version is available to a controlled subset of users while the deployment proceeds. Over time, the traffic that is sent to the new version is increased until all of the traffic is sent there, at which point you can stop the old production environment. For rapid rollback while deployment is in progress, you can route all of the traffic to the original production environment. Since this strategy requires two full production environments only during deployment, the overall resource usage is lower than for the Blue-Green deployment. The Canary release deployment strategy is the slowest to move from a previous release to a current release of the software that is being deployed. Canary deployments allow organizations to test two different software versions side by side in production.
Before you begin
Before you start this tutorial, make sure that you have the following resources in place:
-
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 about IBM Cloud accounts, see Setting up your IBM Cloud account and Upgrading your account.
-
A Kubernetes cluster and an API key. You can create these resources by using either the UI or the CLI. The cluster might take some time to provision. As the cluster is created, it progresses through the Deploying, Pending, and Ready stages. For more information about Kubernetes clusters, see Kubernetes clusters. Although you can use Rolling and Blue-Green deployments for Lite plans, you must create a Kubernetes cluster for Standard plans.
-
An instance of the Continuous Delivery service.
-
Optional. Secrets that are stored in a secrets management vault and managed centrally from a single location. For more information about choosing from the various secrets management and data protection offerings, see Managing IBM Cloud secrets. If you don't already have an instance of the secrets management vault provider of your choice, create one.
-
Optional. A namespace that is created by using the container registry command line. To create a namespace, type the following command from the command line:
ibmcloud cr namespace-add <my namespace>Alternatively, you can create a namespace on the Container Registry page. For more information about creating a namespace in this location, see IBM Cloud Container Registry service.
Create the toolchain
In this step, you create a Develop a Kubernetes app toolchain. The target Kubernetes cluster is configured during the toolchain setup by using your IBM Cloud API key and your Kubernetes cluster name. You can change these settings later by updating the Delivery Pipeline configuration. Any code that is merged into the target Git repo branch is automatically built, validated, and deployed into the Kubernetes cluster.
To create a Develop a Kubernetes app toolchain, click
Alternatively, from the IBM Cloud console, click the menu icon 
, and select DevOps. On the Toolchains page, click Create a Toolchain.
On the Create a Toolchain page, click Develop a Kubernetes app.
Configure the toolchain name and region
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.
The toolchain region can differ from the cluster and registry region.
Select the deployment strategy
The toolchain creates a Continuous Deployment Pipeline to deploy the application Docker image on the IBM Cloud® Kubernetes Service. Select the deployment strategy that you want to use. Based on which deployment strategy you choose (Rolling, Blue-Green, or Canary), you must provide more details.
-
Click the deployment strategy that you want to use for your toolchain.
Figure 2. Deployment strategies -
Click Continue.
Configure the application source code repo
In the Application step, that recommended options for the application source code repo are displayed by default. To view all of the available options for the underlying Git integration, click Advanced Options. By default, the toolchain uses the default sample that clones the sample app as an IBM-hosted Git Repos and Issue Tracking repo.
You can change the name of the app repo. The region of the repo 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 repo for the toolchain, select Bring your own app and specify the URL for the repo. The toolchain supports linking only to existing Git Repos and Issue Tracking repos.
By default, the application repo template is cloned to your Git Repos and Issue Tracking org. To change the org, enable Advanced options and specify the repo owner.
Configure the inventory repo
The inventory repo records the details of the artifacts that are built by the continuous integration toolchains. You can either create a new inventory repo that is a clone of the inventory repo template or use an existing inventory repo that you share between toolchains.
By default, the inventory repo template is cloned to your Git Repos and Issue Tracking org. To change the org, select Advanced options and specify the repo owner.
Securely store secrets
Several tools within this toolchain require secrets, such as an IBM Cloud API key. You must securely store all secrets in a secrets vault and reference them as required by the toolchain.
Using 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. In the Secrets step, you can specify which secret vault integrations to add or remove from your toolchain. For more information about adding and removing vault integrations, including prerequisites and by using hints, see Managing IBM Cloud secrets.
By using hints within a template, a toolchain is automatically populated with preconfigured secrets; you don't need to manually select secrets from vault integrations that are attached to the toolchain.
This tutorial uses the IBM Secrets Manager as the secrets vault.
IBM Secrets Manager securely stores and applies secrets such as API keys, Image Signature, or HashiCorp credentials that are part of your toolchain.
For more information about managing your secrets in IBM Key Protect or HashiCorp, see IBM Key Protect or HashiCorp.
Configure the deployment target
Configure the target Kubernetes cluster to deploy the app to. After the app passes the build, test, and scan phase, the pipeline deploys the built app image to the target Kubernetes cluster. This deployment is now ready for acceptance testing or integration testing.
If the API key has the required access, the following fields automatically load by using the API key that is either created, retrieved from a vault, or manually specified. If the API key is valid, values for the Container registry region and namespace Cluster region, name, namespace, and Resource group are automatically populated. You can update any of these fields to match your configuration.
-
App name: The name of the app. The default app name is
hello-containers. -
IBM Cloud API Key: The API key that is used to interact with the
ibmcloudCLI tool in several tasks. Use one of the following methods to specify the API key that you want to use:- Click the key icon to import an existing API key from a secret vault of your choice.
- Copy and paste an existing API key.
- Click New to create an API key.
- Generate a new
api-keyif you don’t have an existing API key.
You can immediately save the generated API key to an existing secrets vault of your choice.
The app is deployed by using the deployment strategy that you specified. The following example shows the details for a Rolling or Blue-Green deployment.
If you selected the Canary deployment strategy, you must specify extra deployment target details.
-
Canary step size: Defines the amount of traffic to redirect to the new release of the Canary deployment.
-
Canary step interval: Defines the time interval between each Canary test to move to the new release of the Canary deployment.
Add optional tool integrations
You can add the IBM Cloud® DevOps Insights tool integration to your toolchain without any additional configuration.
DevOps Insights is included in the created toolchain. You do not need to provide any configuration steps for DevOps Insights. The continuous integration pipeline automatically uses the DevOps Insights instance that is included in the toolchain. DevOps Insights aggregates code, test, build, and deployment data to provide visibility into the velocity and quality of all of your teams and releases.
Click Continue.
Complete the toolchain setup
On the Summary page, click Create. Several steps run automatically to set up your toolchain.
You can configure the individual toolchain integrations after the pipeline is created.
Explore your new toolchain
After you create your toolchain, it shows each of the tool integrations that are part of the toolchain in a diagram.
Explore the pipelines
You can explore the pipelines to understand the toolchain flow and the different operations that run within each pipeline. The toolchain that you just created contains three pipelines:
- Pull request pipeline: Runs when a developer merges changes from their development branch to the master branch, or to any other branch in the repo. The pull request pipeline runs the Unit Test and Static Scans on the Application Source Code.
- Continuous integration pipeline: Runs when you merge a change into the master branch of the Application Source Code repo. The continuous integration pipeline runs the Unit Test, Code Coverage, and Static Scans on the Application Source Code, CIS check, and Bill Of Materials (BOM) check. The continuous delivery pipeline also generates the binary build artifacts and uploads them to the IBM Cloud® Kubernetes Service, as configured in the toolchain. And the continuous integration pipeline generates the metadata of the build artifacts and stores it in the Inventory repo.
- Continuous deployment pipeline: Deploys build artifacts to the deployment environment. The pipeline verifies the successful deployment of the app by running the health check. You must manually trigger this pipeline after the continuous integration pipeline successfully completes. Depending on the deployment strategy that you selected, more triggers are added to the continuous delivery pipeline.
Run the pull request and continuous integration pipelines
To start the pull request pipeline, create a merge request in your app repo:
- On the Toolchain's Overview page, on the Repositories card, click the
compliance-app-<timestamp>app repo. - From the master repo, create a branch.
- Update some code in the sample node app or readme file and save these changes.
- Submit the merge request.
- On the Toolchain's Overview page, on the Repositories card, click the
pr-pipelinerepo to start the pull request pipeline. The corresponding merge request in your app repo remains in the pending state until all of the stages of the pull request pipeline successfully complete. - After the pull request pipeline run succeeds, you can select it to explore the completed steps.
To start the continuous integration pipeline, merge the continuous integration merge request in your app repo:
- Go to the merge request.
- Merge the request so that your changes are copied to the master branch of your app repo. The continuous integration pipeline is automatically triggered.
- On the continuous integration Toolchain Overview page, on the Repositories card, click the
ci-pipelinerepo to start the continuous integration pipeline. - After the continuous integration pipeline run succeeds, you can click the pipeline run to explore the completed steps.
Shift left practice
In the secure app development world, shift left is a practice that prevents and finds issues such as defects and security vulnerabilities and runs compliance checks early in the software delivery process. Shift left includes the following practices:
- Run checks that can be run on the code or the repo itself and do not need the built image, as early as possible. These checks prevent noncompliant code from being merged into the master branch of the repo. Because evidence is not collected from the pull request pipeline, its goal is to shift compliance checks as far left as possible.
- All checks are run in every pipeline run. If a previous check fails, the pipeline progresses to the next check. To evaluate if you have any failures in your run, check the final step of your pipeline that has a pipeline evaluator.
Results from unit tests and vulnerability scans are published to the DevOps Insights instance within the toolchain. To review these results, click the DevOps Insights tile within the toolchain and go to the Quality Dashboard page.
To evaluate if you have any failures in your pipeline run, check the final step of your pipeline, which has a pipeline evaluator.
Explore the continuous delivery pipeline
The pull request and continuous integration pipelines are common across all of the deployment strategies. The continuous delivery pipeline design and implementation changes are based on the deployment strategy that you previously selected in this tutorial.
This tutorial demonstrates how the rolling deployment strategy works by using the sample app.
Explore the Rolling deployment
The rolling deployment strategy that is used in this tutorial demonstrates how you can use a deployment strategy with the Continuous Delivery Service to run your production workload on Kubernetes. The continuous delivery pipeline provides two triggers for the rolling deployment. You can start a continuous delivery pipeline in either of the following ways:
- Trigger the continuous delivery pipeline manually.
- Automatically trigger the continuous delivery pipeline after each
Mergeaction in the Inventory repo. After the merge, you must manually trigger the continuous deliver pipeline run.
A Git Repos and Issue Tracking trigger is set up to trigger an automatic continuous delivery pipeline, but it is disabled by default. You can enable this trigger after the first time that you promote a change.
Because the rolling deployment strategy incrementally updates all of the production instances with the new software version, it doesn't incur any downtime. However, the rollback deployment strategy requires that you redeploy the previous release, which might take some time to complete.
After the continuous delivery pipeline run succeeds, you can locate the app URL within the perform deployment step of the continuous delivery pipeline.
Next steps
If you want to remove the sample app that is running on Kubernetes, you must clean the Kubernetes cluster:
-
Go to the Kubernetes Cluster home page.
-
Select the cluster where the sample app is running.
-
Click Kubernetes dashboard.
-
From the location where the sample app is running, select namespace.
Figure 15. Kubernetes namespace -
Delete the related deployments, services, and ingresses that are listed within the selected namespace.
Looking for help?
Get help 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.