This article demonstrates a step-by-step guide about creating your own pipeline in IBM Cloud to implement continuous integration and continuous delivery in a GitOps way.
The IBM Cloud Toolchains service provides default templates to adopt a DevOps approach to implement continuous integration (CI) and continuous delivery (CD) pipelines. On some occasions, the template may not meet your requirements, which requires you create a customized pipeline.
This article provides a sample tutorial for how to implement your own toolchain to deploy a simple “Hello Tekton” Kubernetes application. It’s implemented in the GitOps way. Two separate Git repositories are created for application source code and Kubernetes deployment files. The tutorial implements the following workflow using the Tekton pipeline and Argo CD:
- A change is pushed to the application Git repository.
- The CI pipeline is triggered. It builds a new Docker image, tags the image and pushes the image into IBM Container Registry.
- The CI pipeline then checks out the config Git repository, updates the Kubernetes deployment yaml file with the new image tag and commits the change back to the config repository.
- An Argo CD project is created to monitor the config repository. When the deployment file is committed with change, Argo CD will synchronize the change and deploy it to Kubernetes.
- Create a Kubernetes cluster if you don’t have one. Log in to the IBM Cloud console and select Kubernetes Service in the Catalog to create a cluster. For testing purposes, you can use the Free plan. You also need to install the Kubenetes CLI (kubectl) following the instructions here.
- Create a namespace in the container registry. You can use command line: Alternatively, you can create a namespace on the Container Registry UI.
- Create an IBM Cloud API key. Go to IBM Cloud API keys and click Create an IBM Cloud API key. Save the API key value by either copying or downloading it. You need it when configuring your toolchain.
Create a custom toolchain
- In the IBM Cloud Catalog, open the Toolchain service and select the Build your own toolchain card to create a custom toolchain.
- Input a unique toolchain name and then select the region and resource group where you want to create the toolchain:
- Click Create to create a blank toolchain.
Prepare Git repositories
- First you need to create a Git repository for your application source. In the repository, a “.tekton” directory is used to save the Tekton pipeline, task and listener definitions. In this tutorial, I used the hello-tekton Github repository.
- To simplify the work, my pipeline will call the tasks provided by the Open Toolchain Tekton catalog. The Tekton catalog is a Github repository that contains a set of tasks that can be reused in pipelines. Each task is in a subdirectory corresponding to its usage. You can create a fork of the tekton-catalog repository in Github.
- Next, create a config Github repository. In the repository, I created a directory “hello-tekton” and an initial version of the Kubernetes delopyment file
Configure the toolchain
- Return to the toolchain's Overview page you just created.
- Click the Add+ button and select Github.
- For the Repository type, select Existing.
- In the Source repository URL field, input the URL of your application repository.
- Make sure the Enable GitHub Issues checkbox and Track deployment of code changes checkbox are selected.
- Click Create Integration:
- Repeat Step 2 to add Github integration for the config repository and Tekton catalog repository.
- After completing the steps, you can see three repositories from the toolchain’s Overview page:
- From the Overview page, click Add+ again and select Delivery Pipeline.
- On the Configure Delivery Pipeline page, give the pipeline a name and select Tekton as the type. Click Create Integration:
- Click the newly created pipeline to open the pipeline Configuration page.
- On the left, select Definitions and complete these tasks:
- Click Add to add your repository.
- Specify the Git repository that contains the Tekton pipeline definition. In this tutorial, the pipeline definition is in application repository.
- Select the branch you want to use.
- Specify the path (
.tekton) to your pipeline definition in repository.
- Save your changes:
- To use the tasks provided by the Tekton catalog, you also need to add the Tekton catalog integration to the Definitions tab with the Path set. In this tutorial, the following repositories with paths are added:
- On the left, select Worker, choose IBM Managed workers in the Work field and click Save:
- On the left, select Triggers and click Add > Manual. Manual triggers run when you run the pipeline manually from the UI:
- From the Triggers page, click Add > Git Repository and fill in the following:
- Input a Trigger name.
- Specify the EventListener. This is defined by the listener.yaml file in the
.tektonfolder of the Git repository.
- From the Repository list, select the application repository hello-tekton.
- For Branch, input “master”.
- Select the When a commit is pushed checkbox.
- Click Add: With this trigger, the CI pipeline is run when a change is pushed to the master branch of application repository.
- On the left, select Environment Properties and define the environment properties for this tutorial. To add each property, click Add > Text value (except for apikey and toolchain-apikey, which are secured properties). Add properties below:
- apikey: The API key that you created earlier in Prerequisites step.
- app-name: The name of the Kubernetes application. I used “hello-tekton” in this tutorial.
- image-name: The name of Docker image created.
- inventoryRepo: The Github config repository URL.
- registry-namespace: The Container Registry namespace created in the Prerequisites step.
- registry-region: The region where your Container Registry is located.
- repository: The Github application repository URL.
- toolchain-apikey: The same value as apikey above:
The CI pipeline has now been configured. Next, you need to configure the automatic deployment for CD.
Create and configure Argo CD
Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. In this tutorial, Argo CD is used to monitor the Kubernetes deployment files in the Git config repository. When the change is committed by the CI pipeline, Argo CD will update Kubernetes automatically.
- Install Argo CD in your cluster and the Argo CD command line by following the Getting Started documentation.
- Access the Argo CD API server using Kubectl port-forwarding:
- Log in to Argo CD using the CLI.
- Retrieve the initial password for the Access Argo CD API server using Kubectl port-forwarding:
- Find the account using kubectl:
- Log in with the password retrieved from above:
- Create an application from your Git config repository via the CLI: You can also create the project from Argo CD web console by accessing https://localhost:8080/.
- Synchronize and check the application:
- Enable automated synchronization:
Test the CI/CD pipeline
- To manually run the pipeline, open the ci-pipeline from the Toolchain Overview page.
- Select PipelineRuns on the left and click Run pipeline. The toolchain is now running:
- Click the running pipeline name and you can see the pipeline with tasks detail:
- After the pipeline succeeds, open the deployment file from the Git config repository; the image tag is updated:
- Using the CLI to check the Argo CD project status and the Kubernetes resource, you can see the deployment is updated:
- From the Argo CD web console (https://localhost:8080/), you can also see the “hello-tekton” app is synced using new configuration:
- To test the automation process, open the app.js file in the application Git repository, make some changes in the text message and commit the change.
- Go back to the ci-pipeline page and select PipelineRuns on the left. You can see a new pipeline is running automatically:
- Like the manual run, you can check the results by opening the pipeline details. After the CI pipeline completes, you can monitor Argo CD until the application is shown as Synced. The updated yaml file will be deployed to Kubernetes.
In this sample tutorial, you implemented a toolchain with a Tekton CI pipeline and Argo CD that deploys a "Hello Tekton" app to a Kubernetes cluster. You can apply the pipeline in your dev, staging and production environments. You can also try to create your own PR pipeline for a pull request.