Working with Tekton pipelines

Creating a Delivery Pipeline for Tekton by using the console

When you configure a Delivery Pipeline tool integration, you can select the type of pipeline that you want to create.

1. If you don't have a toolchain, select a template to create a toolchain. Depending on the template that you use, different fields might be available. Review the default field values and if needed, change those settings.

2. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the Continuous delivery card, click View toolchain. Then, click Overview.

3. Add the Delivery Pipeline integration to your toolchain:

   a. Click Add tool.

   b. In the Tool Integrations section, click Delivery Pipeline.

4. Specify a name for your new pipeline.

5. Select Tekton to create a Tekton Delivery Pipeline. You can view the output of Tekton pipeline runs on a defined Kubernetes cluster, with support for configuring the pipeline definitions repos, the pipeline triggers, where the pipeline runs, and simple secrets.

6. If you plan to use your pipeline to deploy a user interface, select the Show apps in the View app menu checkbox. All of the apps that your pipeline creates are shown in the View App list on the toolchain's Overview page.

7. Click Create Integration to add the Delivery Pipeline to your toolchain.

   header['x-github-event'] == 'pull_request' && 
      (body.action == 'opened' || body.action == 'synchronize') && 
      body.pull_request.base.ref == 'main'

   header['x-github-event'] == 'push' && body.ref == 'refs/heads/main'

   header['x-github-event'] == 'push' && 
      body.ref == 'refs/heads/main' && 
      !body.head_commit.message.contains("skip run")

   header['x-github-event'] == 'issue_comment' && 
      body.action == 'created' && has(body.issue.pull_request) &&
      body.comment.body.contains('/lgtm')

   header['x-github-event'] == 'issues' && 
      body.action == 'opened' && 
      body.issue.labels.exists(label, label.name == 'urgent')

   header['x-gitlab-event'] == 'Merge Request Hook' && 
      (body.object_attributes.action == 'open' || body.object_attributes.action == 'update') && 
      body.object_attributes.target_branch == 'main'

   header['x-gitlab-event'] == 'Push Hook' && body.ref == 'refs/heads/main'

   header['x-gitlab-event'] == 'Push Hook' && 
      body.ref == 'refs/heads/main' &&
      !body.object_attributes.last_commit.message("skip run")

   header['x-gitlab-event'] == 'Note Hook' && 
      body.object_attributes.noteable_type == 'MergeRequest' && 
      body.object_attributes.action == 'create' &&
      body.object_attributes.note.contains('/lgtm')

   header['x-gitlab-event'] == 'Issue Hook' && 
      (body.object_attributes.action == 'open') && 
      body.object_attributes.labels.exists(label, label.name == 'urgent')

   (header['x-event-key'] == 'pullrequest:created' || header['x-event-key'] == 'pullrequest:updated') && 
       body.pullrequest.destination.branch.name == 'main'

   header['x-event-key'] == 'repo:push' && body.push.changes[0].new.name == 'main'

   header['x-event-key'] == 'repo:push' && 
      body.push.changes[0].new.name == 'main' &&
      !body.push.changes[0].commits[0].message("skip run")

   header['x-event-key'] == 'pullrequest:comment_created' && 
      body.comment.content.raw.contains('/lgtm')

   header['x-event-key'] == 'issue:created' && 
      body.issue.kind == 'bug'

Creating a Delivery Pipeline for Tekton with the API

1. Obtain an IAM bearer token. Alternatively, if you are using an SDK, obtain an IAM API key and set the client options by using environment variables.

   export CD_TEKTON_PIPELINE_APIKEY={api_key}
   

2. Determine the region and ID of the toolchain to which you want to add the Delivery Pipeline tool integration.

3. Add the Delivery Pipeline tool integration to the toolchain.

   curl -X POST \
     https://api.{region}.devops.cloud.ibm.com/toolchain/v2/toolchains/{toolchain_id}/tools \
     -H 'Authorization: Bearer {iam_token}' \
     -H 'Accept: application/json` \
     -H 'Content-Type: application/json' \
     -d '{
       "tool_type_id": "pipeline",
       "parameters": {
         "name": "{tool_integration_name}",
         "type" : "tekton"
       }
     }'
   

   const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
   ...
   (async () => { 
      const toolchainService = CdToolchainV2.newInstance();
      const pipelinePrototypeModel = {
         toolchainId: {toolchain_id},
         toolTypeId: 'pipeline',
         name: {tool_integration_name},
         type: "tekton"
      };
      const pipelineTool = await toolchainService.createTool(pipelinePrototypeModel);
   })();
   

   import (
       "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
   )
   ...
   toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
   toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
   createPipelineToolOptions := toolchainClient.NewCreateToolOptions({toolchain_id}, "pipeline")
   createPipelineToolOptions.SetName({tool_integration_name})
   createPipelineToolOptions.SetType("tekton")
   pipelineTool, response, err := toolchainClient.CreateTool(createPipelineToolOptions)
   

   from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
   ...
   toolchain_service = CdToolchainV2.new_instance()
   pipeline_tool = toolchain_service.create_tool(
      name = {tool_integration_name},
      toolchain_id = {toolchain_id},
      tool_type_id = "pipeline",
      type = "tekton"
   )
   

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   CreateToolOptions createPipelineToolOptions = new CreateToolOptions.Builder()
      .name({tool_integration_name})
      .toolchainId({toolchain_id})
      .toolTypeId("pipeline")
      .type("tekton")
      .build();
   Response<ToolchainToolPost> response = toolchainService.createTool(createPipelineToolOptions).execute();
   ToolchainToolPost pipelineTool = response.getResult();
   

   The following table lists and describes each of the variables that are used in the previous step.

   Variables for adding the Delivery Pipeline tool integration with the API

   Variable	Description
   {region}	The region in which the toolchain resides, for example, us-south.
   {tool_integration_name}	A name for your tool integration, for example, ci-pipeline.
   {toolchain_id}	The ID of the toolchain to which to add the tool integration.
   {iam_token}	A valid IAM bearer token.

4. Configure the Delivery Pipeline to use public managed workers within the specified regions.

   curl -X POST \
      https://api.{region}.devops.cloud.ibm.com/pipeline/v2/tekton_pipelines \
      -H 'Authorization: Bearer {iam_token}' \
      -H 'Accept: application/json` \
      -H 'Content-Type: application/json' \
      -d '{
         "id": "{pipeline_id}",
         "worker": { "id": "public" }
      }'
   

   const CdTektonPipelineV2 = require('@ibm-cloud/continuous-delivery/cd-tekton-pipeline/v2');
   ...
   (async () => { 
      const tektonService = CdTektonPipelineV2.newInstance();
      const workerIdentityModel = {
         id: 'public',
      };
      const params = {
         id: {pipeline_id},
         worker: workerIdentityModel,
      };
      const res = await tektonService.createTektonPipeline(params);
   })();
   

   import {
      "github.com/IBM/continuous-delivery-go-sdk/cdtektonpipelinev2"
   }
   ...
   cdTektonPipelineOptions := &cdtektonpipelinev2.CdTektonPipelineV2Options{}
   pipelineSvc, err = cdtektonpipelinev2.NewCdTektonPipelineV2UsingExternalConfig(cdTektonPipelineOptions)
   createTektonPipelineOptions := pipelineSvc.NewCreateTektonPipelineOptions(
      {pipeline_id}
   )
   workerIdentityModel := &cdtektonpipelinev2.WorkerIdentity{
      ID: core.StringPtr("public"),
   }
   createTektonPipelineOptions.SetWorker(workerIdentityModel)
   tektonPipeline, response, err := pipelineSvc.CreateTektonPipeline(createTektonPipelineOptions)
   

   from ibm_continuous_delivery.cd_tekton_pipeline_v2 import CdTektonPipelineV2
   ...
   pipeline_service = CdTektonPipelineV2.new_instance()
   worker_identity_model = {
      'id': 'public',
   }
   response = pipeline_service.create_tekton_pipeline(
      id = {pipeline_id},
      worker = worker_identity_model
   )
   tekton_pipeline = response.get_result()
   

   import com.ibm.cloud.continuous_delivery.cd_tekton_pipeline.v2.CdTektonPipeline;
   import com.ibm.cloud.continuous_delivery.cd_tekton_pipeline.v2.model.*;
   ...
   CdTektonPipeline pipelineSvc = CdTektonPipeline.newInstance();
   WorkerIdentity workerIdentityModel = new WorkerIdentity.Builder()
      .id("public")
      .build();
   CreateTektonPipelineOptions createTektonPipelineOptions = new CreateTektonPipelineOptions.Builder()
      .id({pipeline_id})
      .worker(workerIdentityModel)
      .build();
   Response<TektonPipeline> response = pipelineSvc.createTektonPipeline(createTektonPipelineOptions).execute();
   TektonPipeline tektonPipeline = response.getResult();
   

   The following table lists and describes each of the variables that are used in the previous step.

   Variables for configuring the Delivery Pipeline with the API

   Variable	Description
   {region}	The region in which the toolchain resides, for example, us-south.
   {pipeline_id}	The ID of the pipeline that is returned from the previous step where the pipeline tool integration was created.
   {iam_token}	A valid IAM bearer token.

For more information about the Delivery Pipeline API, see the API Docs.

Creating a Delivery Pipeline for Tekton with Terraform

1. To install the Terraform CLI and configure the IBM Cloud provider plug-in for Terraform, follow the tutorial for Getting started with Terraform on IBM Cloud®.

2. Create a Terraform configuration file that is named main.tf. In this file, add the configuration to create a pipeline by using the HashiCorp Configuration Language. For more information about using this configuration language, see the Terraform documentation.

   A pipeline must belong to a toolchain. You can also create toolchains by using Terraform.

   The following example creates a toolchain and a pipeline by using the specified Terraform resources.

   data "ibm_resource_group" "group" {
     name = "default"
   }
   
   resource "ibm_cd_toolchain" "my_toolchain" {
     name              = "terraform_toolchain"
     resource_group_id = data.ibm_resource_group.group.id
   }
   
   resource "ibm_cd_toolchain_tool_pipeline" "my_pipeline_tool" {
     parameters {
        name = "terraform-pipeline-integration"
     }
     toolchain_id = ibm_cd_toolchain.my_toolchain.id
   }
   
   resource "ibm_cd_tekton_pipeline" "my_tekton_pipeline" {
    worker {
        id = "public"
    }
    pipeline_id = ibm_cd_toolchain_tool_pipeline.my_pipeline_tool.tool_id
   }
   

   For more information about the ibm_cd_toolchain_tool_pipeline and ibm_cd_tekton_pipeline resources, see the argument reference details in the Terraform Registry Documentation.

3. Initialize the Terraform CLI, if required.

   terraform init
   

4. Create a Terraform execution plan. This plan summarizes all of the actions that must run to create a toolchain.

   terraform plan
   

5. Apply the Terraform execution plan. Terraform takes all of the required actions to create the toolchain.

   terraform apply
   

Deleting a Delivery Pipeline with the API

1. Obtain an IAM bearer token. Alternatively, if you are using an SDK, obtain an IAM API key and set the client options by using environment variables.

   export CD_TEKTON_PIPELINE_APIKEY={api_key}
   

2. Determine the region and ID of the toolchain that you want to add the DevOps Insights tool integration to.

3. Delete the pipeline.

   curl -X DELETE \
     https://api.{region}.devops.cloud.ibm.com/toolchain/v2/toolchains/{toolchain_id}/tools/{pipeline_id} \
     -H 'Authorization: Bearer {iam_token}'
   

   const CdTektonPipelineV2 = require('@ibm-cloud/continuous-delivery/cd-tekton-pipeline/v2');
   ...
   (async () => { 
      const pipelineSvc = CdTektonPipelineV2.newInstance();
      const params = {
         id: {pipeline_id},
      };
      const res = await pipelineSvc.deleteTektonPipeline(params);
   })();
   

   import {
      "github.com/IBM/continuous-delivery-go-sdk/cdtektonpipelinev2"
   }
   ...
   cdTektonPipelineOptions := &cdtektonpipelinev2.CdTektonPipelineV2Options{}
   pipelineSvc, err = cdtektonpipelinev2.NewCdTektonPipelineV2UsingExternalConfig(cdTektonPipelineOptions)
   deleteTektonPipelineOptions := pipelineSvc.NewDeleteTektonPipelineOptions(
      {pipeline_id}
   )
   response, err := pipelineSvc.DeleteTektonPipeline(deleteTektonPipelineOptions)
   

   from ibm_continuous_delivery.cd_tekton_pipeline_v2 import CdTektonPipelineV2
   ...
   pipeline_service = CdTektonPipelineV2.new_instance()
   response = pipeline_service.delete_tekton_pipeline(
      id={pipeline_id}
   )
   

   import com.ibm.cloud.continuous_delivery.cd_tekton_pipeline.v2.CdTektonPipeline;
   import com.ibm.cloud.continuous_delivery.cd_tekton_pipeline.v2.model.*;
   ...
   CdTektonPipeline pipelineSvc = CdTektonPipeline.newInstance();
   DeleteTektonPipelineOptions deleteTektonPipelineOptions = new DeleteTektonPipelineOptions.Builder()
      .id({pipeline_id})
      .build();
   Response<Void> response = pipelineSvc.deleteTektonPipeline(deleteTektonPipelineOptions).execute();
   

The following table lists and describes each of the variables that are used in the previous step.

Deleting a Delivery Pipeline with Terraform

1. Locate the Terraform file (for example, main.tf) that contains the resource block for the existing pipeline.

   The resource in the following example describes an existing pipeline.

   data "ibm_resource_group" "group" {
     name = "default"
   }
   
   resource "ibm_cd_toolchain" "my_toolchain" {
     name              = "terraform_toolchain"
     resource_group_id = data.ibm_resource_group.group.id
   }
   
   resource "ibm_cd_toolchain_tool_pipeline" "my_pipeline_tool" {
     parameters {
        name = "terraform-pipeline-integration"
     }
     toolchain_id = ibm_cd_toolchain.my_toolchain.id
   }
   
   resource "ibm_cd_tekton_pipeline" "my_tekton_pipeline" {
    worker {
        id = "public"
    }
    pipeline_id = ibm_cd_toolchain_tool_pipeline.my_pipeline_tool.tool_id
   }
   

2. Remove the ibm_cd_toolchain_tool_pipeline and ibm_cd_tekton_pipeline resource blocks from your Terraform file.

3. Initialize the Terraform CLI, if required.

   terraform init
   

4. Create a Terraform execution plan. This plan summarizes all of the actions that must run to delete the pipeline.

   terraform plan
   

5. Apply the Terraform execution plan. Terraform takes all of the required actions to delete the pipeline.

   terraform apply
   

Viewing details for a TaskRun pod

To view information about the underlying Kubernetes pod for a specific TaskRun, click the Task name and then click Pod.

You can view the details for the pod and any related events that are reported by the worker. This information can help you to debug specific failures or to determine where time is spent during a run.