Chapter 4. Migrate from ClusterTask to the cluster resolver

Procedure

1. Find ClusterTask references in Pipeline resources across all namespaces by running the following command:

   $ oc get pipelines -A -o yaml | grep -B5 "kind: ClusterTask"

   Example output:

   namespace: my-project
     taskRef:
       name: buildah
       kind: ClusterTask

2. Find ClusterTask references in PipelineRun resources by running the following command:

   $ oc get pipelineruns -A -o yaml | grep -B5 "kind: ClusterTask"

3. Find ClusterTask references in TaskRun resources by running the following command:

   $ oc get taskruns -A -o yaml | grep -B5 "kind: ClusterTask"

4. For each ClusterTask reference, note the following information:

   • The task name
   • The namespace where the pipeline or run exists
   • Whether the task is a Red Hat-provided task or a custom task
   • The pipeline or run name that references the task

Verification

1. Review your list of ClusterTask references to ensure completeness.

2. Verify the format of a typical ClusterTask reference that needs migration:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: example-pipeline
   spec:
     tasks:
     - name: build-image
       taskRef:
         name: buildah
         kind: ClusterTask

   ClusterTask specifies that the reference format is no longer supported and must be migrated to use the cluster resolver.

Procedure

1. List the available Red Hat provided tasks in the OpenShift Pipelines installation namespace by running the following command:

   $ oc get tasks -n openshift-pipelines

   Example output:

   NAME                 AGE
   buildah              10d
   git-cli              10d
   git-clone            10d
   maven                10d
   openshift-client     10d
   s2i-java             10d
   skopeo-copy          10d
   tkn                  10d

2. Verify that the task you want to use is available by running the following command:

   $ oc get task buildah -n openshift-pipelines

3. Update the taskRef definition in your pipeline to use the cluster resolver.

   Before migration:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: build-and-deploy
   spec:
     tasks:
     - name: build-image
       taskRef:
         name: buildah
         kind: ClusterTask
       params:
       - name: IMAGE
         value: $(params.IMAGE_NAME)
       workspaces:
       - name: source
         workspace: shared-workspace

   After migration:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: build-and-deploy
   spec:
     tasks:
     - name: build-image
       taskRef:
         resolver: cluster
         params:
         - name: kind
           value: task
         - name: name
           value: buildah
         - name: namespace
           value: openshift-pipelines
       params:
       - name: IMAGE
         value: $(params.IMAGE_NAME)
       workspaces:
       - name: source
         workspace: shared-workspace

   where:

   resolver

   Specifies the cluster resolver to access tasks from the same cluster.

   value

   Specifies the default namespace where the task is located.

4. Apply the updated pipeline definition by running the following command:

   $ oc apply -f my-pipeline.yaml

   Tip

   When migrating to the cluster resolver, you only need to change the taskRef section. Task parameters, workspaces, and results remain unchanged.

Verification

1. Create a pipeline run to verify the migration by running the following command:

   $ tkn pipeline start build-and-deploy --showlog

2. Verify that the pipeline run completes successfully by running the following command:

   $ tkn pipelinerun logs <pipelinerun-name> -f

Procedure

1. Export the existing ClusterTask resource to a YAML file by running the following command:

   $ oc get clustertask my-custom-task -o yaml > my-custom-task.yaml

2. Edit the YAML file to convert it to a namespace-scoped Task:

   1. Change kind: ClusterTask to kind: Task.
   2. Update apiVersion from tekton.dev/v1beta1 to tekton.dev/v1 if necessary.
   3. Add a namespace field under metadata.
   4. Remove generated fields such as creationTimestamp, generation, resourceVersion, selfLink, and uid.
   5. Remove the status section if present.

   Example of a converted task:

   apiVersion: tekton.dev/v1
   kind: Task
   metadata:
     name: my-custom-task
     namespace: my-shared-tasks
   spec:
     params:
     - name: MESSAGE
       type: string
       default: "Hello from custom task"
     steps:
     - name: echo-message
       image: registry.access.redhat.com/ubi9/ubi-minimal:latest
       script: |
         #!/bin/sh
         echo "$(params.MESSAGE)"

   metadata.namespace

   Specifies the namespace where the task is created.

3. Create the namespace if it does not exist by running the following command:

   $ oc create namespace my-shared-tasks

4. Apply the converted task to the cluster by running the following command:

   $ oc apply -f my-custom-task.yaml

5. Update all pipeline references to use the cluster resolver by running the following command:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: example-pipeline
   spec:
     tasks:
     - name: run-custom-task
       taskRef:
         resolver: cluster
         params:
         - name: kind
           value: task
         - name: name
           value: my-custom-task
         - name: namespace
           value: my-shared-tasks

   spec.taskRef.params.value

   Specifies the namespace where you have created the converted task.

6. If you want to share tasks across multiple projects, consider creating a dedicated namespace for shared tasks by running the following command:

   $ oc create namespace shared-pipeline-tasks

   Then, grant access to the namespace by creating a RoleBinding for each project that needs to use the tasks:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: pipeline-tasks-viewer
     namespace: shared-pipeline-tasks
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - kind: ServiceAccount
     name: pipeline
     namespace: my-project

   subjects.namespace

   Specifies the namespace where your pipelines run.

Verification

1. Verify that the task was created successfully by running the following command:

   $ oc get task my-custom-task -n my-shared-tasks

2. Create a TaskRun to test the converted task:

   apiVersion: tekton.dev/v1
   kind: TaskRun
   metadata:
     name: test-custom-task
   spec:
     taskRef:
       resolver: cluster
       params:
       - name: kind
         value: task
       - name: name
         value: my-custom-task
       - name: namespace
         value: my-shared-tasks

3. View the task run logs to confirm it works correctly by running the following command:

   $ tkn taskrun logs test-custom-task -f

Procedure

1. Identify community tasks that are no longer available:

   Examples of removed community tasks include:

   • helm-upgrade-from-repo
   • jib-maven
   • pull-request
   • pytest

2. Obtain the task definition from the Tekton Catalog or another source:

   $ curl -LO https://raw.githubusercontent.com/tektoncd/catalog/main/task/helm-upgrade-from-repo/0.3/helm-upgrade-from-repo.yaml

3. Review the task definition to ensure it meets your requirements:

   $ cat helm-upgrade-from-repo.yaml

4. Choose a namespace for the task installation:

   • Same namespace as the pipeline: Install the task in the same namespace as your pipeline if it is only used by that pipeline.
   • Shared namespace: Install the task in a shared namespace if multiple pipelines in different projects use it.

5. Apply the task to the cluster by running the following command:

   $ oc apply -f helm-upgrade-from-repo.yaml -n my-namespace

6. Update pipeline references based on where you installed the task.

   If the task is in the same namespace as the pipeline:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: helm-deploy-pipeline
     namespace: my-namespace
   spec:
     tasks:
     - name: upgrade-helm-chart
       taskRef:
         name: helm-upgrade-from-repo

   For tasks in the same namespace, you can reference them by name without using the cluster resolver.

   If the task is in a different namespace:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: helm-deploy-pipeline
     namespace: my-project
   spec:
     tasks:
     - name: upgrade-helm-chart
       taskRef:
         resolver: cluster
         params:
         - name: kind
           value: task
         - name: name
           value: helm-upgrade-from-repo
         - name: namespace
           value: shared-tasks

   For tasks in a different namespace, use the cluster resolver.

   Note

   You can also use the cluster resolver for tasks in the same namespace for consistency across all task references.

Verification

1. Verify that the task is available by running the following command:

   $ oc get task helm-upgrade-from-repo -n my-namespace

2. Test the task with a pipeline run or task run to ensure it works as expected.

Procedure

1. Edit the cluster resolver configuration by running the following command:

   $ oc edit configmap cluster-resolver-config -n openshift-pipelines

2. Configure default values for the cluster resolver:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: cluster-resolver-config
     namespace: openshift-pipelines
   data:
     default-kind: "task"
     default-namespace: "openshift-pipelines"

   data.default-kind

   Sets the default resource kind to task. This means you do not need to specify kind in every cluster resolver reference if you are referencing tasks.

   data.default-namespace

   Sets the default namespace to openshift-pipelines. This means you do not need to specify the namespace parameter if your tasks are in this namespace.

3. Save the changes to the ConfigMap.

4. After configuring defaults, you can simplify task references in your pipelines:

   Without defaults:

   taskRef:
     resolver: cluster
     params:
     - name: kind
       value: task
     - name: name
       value: buildah
     - name: namespace
       value: openshift-pipelines

   With defaults configured:

   taskRef:
     resolver: cluster
     params:
     - name: name
       value: buildah

5. If you need to override the defaults for a specific task reference, you can still provide explicit values:

   taskRef:
     resolver: cluster
     params:
     - name: name
       value: my-custom-task
     - name: namespace
       value: my-shared-tasks

   taskRef.value

   Specifies a different namespace, overriding the default.

   Important

   Setting defaults affects all pipelines that use the cluster resolver in the cluster. Ensure that the default namespace contains the tasks that most of your pipelines use.

Verification

1. Create a test pipeline that uses the simplified syntax:

   apiVersion: tekton.dev/v1
   kind: Pipeline
   metadata:
     name: test-defaults
   spec:
     tasks:
     - name: test-task
       taskRef:
         resolver: cluster
         params:
         - name: name
           value: buildah

2. Run the following command to verify that the cluster resolver correctly to apply the defaults:

   $ tkn pipeline start test-defaults --showlog

3. Check the pipeline run details to confirm the task was resolved correctly by running the following command:

   $ tkn pipelinerun describe <pipelinerun_name>

   <pipelinerun_name>

   Specifies the name of the pipeline run.

Procedure

1. Verify that no ClusterTask references remain in your cluster by running the following command:

   $ oc get pipelines -A -o yaml | grep -c "kind: ClusterTask"

   Example output:

   0

   A count of 0 indicates that no ClusterTask references remain.

2. Check pipeline runs for any remaining ClusterTask references by running the following command:

   $ oc get pipelineruns -A -o yaml | grep -c "kind: ClusterTask"

3. Apply one of your updated pipelines to the cluster by running the following command:

   $ oc apply -f my-updated-pipeline.yaml

4. Start a pipeline run to test the migrated pipeline by running the following command:

   $ tkn pipeline start my-updated-pipeline --showlog

5. Monitor the pipeline run to ensure all tasks resolve correctly by running the following command:

   $ tkn pipelinerun logs <pipelinerun_name> -f

   <pipelinerun_name>

   Specifies the name of the pipeline run to monitor.

6. Verify that the task was resolved from the correct namespace by running the following command:

   $ tkn pipelinerun describe <pipelinerun_name>

   <pipelinerun_name>

   Specifies the name of the pipeline run.

   Example output

   Name:           my-pipeline-run-xxxxx
   Namespace:      my-project
   Pipeline Ref:   my-updated-pipeline
   TASKRUNS
   NAME                             TASK NAME      STARTED         DURATION   STATUS
   my-pipeline-run-xxxxx-build      buildah        2 minutes ago   1 minute   Succeeded

   my-pipelines-run-xxxxx-build

   Indicates the task ran successfully using the cluster resolver

7. Review the resolved task reference in the pipeline run status:

   $ oc get pipelinerun <pipelinerun_name> -o jsonpath='{.status.childReferences[*].pipelineTaskName}'

   <pipelinerun_name>

   Specifies the name of the pipeline run to be inspected.

Verification

1. Confirm that all your critical pipelines have been migrated and tested.
2. Document any custom tasks or community tasks that you installed for future reference.

3. Create a test plan to verify all common pipeline scenarios:

   • Pipelines with multiple tasks
   • Pipelines using tasks from different namespaces
   • Pipelines with conditional tasks
   • Pipelines using when expressions

Procedure

1. Verify that the task exists in the namespace by running the following command:

   $ oc get task <task_name> -n <namespace>

   <task_name>

   Specifies the name of the task you are trying to reference.

   <namespace>

   Specifies the namespace where the task should be located.

2. If the task does not exist, check if it is available in the OpenShift Pipelines installation namespace by running the following command:

   $ oc get tasks -n openshift-pipelines

3. Verify the spelling of the task name and namespace in your pipeline definition.

Procedure

1. Inspect the cluster resolver configuration by running the following command:

   $ oc get configmap cluster-resolver-config -n openshift-pipelines -o yaml

2. Check if the namespace is in the blocked-namespaces list:

   data:
     blocked-namespaces: "kube-system,kube-public"

   kube-system,kube-public

   Lists namespaces that cannot be accessed by the cluster resolver.

3. If necessary, update the configuration to allow access to the namespace by running the following command:

   $ oc edit configmap cluster-resolver-config -n openshift-pipelines

4. Ensure that the service account running the pipeline has permissions to view tasks in the target namespace:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: pipeline-viewer
     namespace: shared-tasks
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: view
   subjects:
   - kind: ServiceAccount
     name: pipeline
     namespace: my-project

Procedure

1. Check if the cluster resolver is enabled in the feature flags configuration by running the following command:

   $ oc get configmap resolvers-feature-flags -n openshift-pipelines -o yaml

2. Verify that enable-cluster-resolver is set to "true":

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: resolvers-feature-flags
     namespace: openshift-pipelines
   data:
     enable-cluster-resolver: "true"

   data.enable-cluster-resolver

   Must be set to "true" to enable the cluster resolver.

3. If the setting is "false", update it to "true" by running the following command:

   $ oc patch configmap resolvers-feature-flags -n openshift-pipelines \
     --type merge -p '{"data":{"enable-cluster-resolver":"true"}}'

4. Restart the resolver pods to apply the changes by running the following command:

   $ oc delete pods -n openshift-pipelines -l app=tekton-pipelines-resolvers

Procedure

1. Review the task definition to see current parameters by running the following command:

   $ oc get task buildah -n openshift-pipelines -o yaml

2. Check the task reference documentation for the correct parameter names and types. For more information, see the Additional Resources section.
3. Update your pipeline to use the correct parameter names.

Procedure

1. View the pipeline run events for detailed error messages by running the following command:

   $ oc get events --sort-by='.lastTimestamp' | grep <pipelinerun_name>

   <pipelinerun_name>

   The name of the pipeline run to search for in the events.

2. Check the resolver logs for resolution errors by running the following command:

   $ oc logs -n openshift-pipelines -l app=tekton-pipelines-resolvers --tail=100

3. Verify the service account has the necessary permissions by running the following command:

   $ oc auth can-i get tasks --as=system:serviceaccount:my-project:pipeline -n openshift-pipelines

4. Ensure that the Red Hat OpenShift Pipelines Operator is running the correct version by running the following command:

   $ oc get csv -n openshift-pipelines