Migrate from ClusterTasks to Tekton Resolvers in OpenShift Pipelines

What are ClusterTasks?

ClusterTasks are CRDs that OpenShift Pipeline provides that are the cluster-scoped equivalent of a Task. They share all of the same fields as a Task but can be referenced regardless of the namespace that a TaskRun is executing in. In contrast, a Task can only be referred to by a TaskRun in the same namespace. 

OpenShift Pipelines ships with various default cluster tasks, like git clone, buildah, etc. Additionally, users can create their own ClusterTask by creating a Task object with the kind field set to ClusterTask. 

See the example below of a ClusterTask and how it is used in pipelines. We will use this same task to show how you can migrate from ClusterTask using various resolvers:

apiVersion: tekton.dev/v1beta1
kind: ClusterTask
metadata:
  name: generate-random-number
spec:
  description: Generates a random number.
  inputs:
    parameters:
    - name: min
      type: string
    - name: max
      type: string
  steps:
  - name: generate-random-number
    image: busybox
    command: ["/bin/echo", "$((RANDOM % $(params.max - params.min) + params.min))"]
  outputs:
    result:
      type: string

Install the ClusterTask in your OpenShift cluster:

oc create -f path/to/my/generate-random-number.yaml

Once you have installed a cluster task, you can use it in a pipeline in any namespace by specifying the taskRef field in the tasks section of the pipeline definition:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: generate-random-number-pipeline
spec:
  tasks:
  - name: generate-random-number
    taskRef:
      name: generate-random-number
      kind: ClusterTask
  results:
  - name: random-number
    value: $(tasks.generate-random-number.outputs.result)

Why is ClusterTask being deprecated? 

There are a few reasons why cluster tasks are not widely used. 

• First, cluster tasks can be difficult to manage. They are not namespaced, so other cluster tasks can overwrite them. Additionally, there is no built-in versioning. If someone updates a ClusterTask in a non-backward compatible way, it will break any usage that didn't consider this change.
• Second, they are not necessary for most use cases. Tekton Pipelines are run in a single namespace, so there is no need for a cluster-scoped Task. 
• Third, cluster tasks are not as secure as namespaced tasks. They can be accessed by any user in the cluster, even if they do not have access to the namespace where the TaskRun is running.

Ways to migrate from ClusterTask

The resolver feature in Tekton is an alternative to ClusterTask in the context of OpenShift Pipelines. It has been introduced as a Generally Available (GA) feature starting from OpenShift Pipelines 1.11. The Tekton Resolver is designed as a robust and extensible tool that enables users to resolve resources from remote locations, encompassing Git repositories, cloud buckets, and other storage systems. Implementation-wise, the Resolver is realized as a Kubernetes Custom Resource Definition (CRD), which provides its compatibility and deployability across diverse Kubernetes clusters.

The Tekton Resolver offers a range of built-in resolvers: Git Resolver, Bundle Resolver, Cluster Resolver, and Hub Resolver. Each resolver comes with its own distinct capabilities and limitations. In the subsequent section, we will delve into the details of these resolvers and explore how they can effectively replace ClusterTasks. To illustrate these concepts, we will continue utilizing the previous example.

Cluster Resolver

A cluster resolver is a Tekton Pipelines feature that allows you to reference tasks and pipelines from other namespaces. This can replace ClusterTasks. You can add the tasks you want to be available across the cluster in one or multiple namespaces. These namespaces will allow an admin to create and maintain tasks you previously used as ClusterTasks. Thus, organizations can use enhanced security measures by consolidating the desired tasks in designated namespaces, which assumes an administrative role. Specifically, only the administrator of this namespace possesses the necessary privileges to modify or delete the tasks that are made available throughout the cluster. Additionally, you can block some namespaces to resolve tasks/pipelines from. 

Following the previous example mentioned in the ClusterTasks section, you can create the task as a regular task object in an example namespace:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: generate-random-number
spec:
  description: Generates a random number.
  inputs:
    parameters:
    - name: min
      type: string
    - name: max
      type: string
  steps:
  - name: generate-random-number
    image: busybox
    command: ["/bin/echo", "$((RANDOM % $(params.max - params.min) + params.min))"]
  outputs:
    result:
      type: string

You install the task manifest in OpenShift cluster in the example namespace:

oc create -f path/to/my/generate-random-number.yaml -n example 

Then you can refer to this task in a pipeline in any namespace: 

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: generate-random-number-pipeline
spec:
  tasks:
  - name: generate-random-number
    taskRef:
      resolver: cluster
      params:
        - name: kind
          value: task
        - name: name
          value: generate-random-number
        - name: namespace
          value: example 
  results:
  - name: random-number
    value: $(tasks.generate-random-number.outputs.result)

Additionally, you can also use the cluster resolver to reference pipelines. To do this, you need to set the kind parameter to pipeline. 

Thus, the cluster resolver is a powerful feature that allows you to share tasks and pipelines across namespaces. This can make it easier to manage your pipelines and tasks and help you improve the security and performance of your workloads. However, the shortcoming of this approach currently is that a user might not have the right to list the task and pipeline in the namespace that the resolvers look into, making "discoverability" hard.

Git resolver

Git Resolver is a Tekton Pipelines feature that allows you to reference tasks and pipelines from Git repositories. This can be useful for storing your tasks and pipelines in a central location, such as GitHub, and then referencing them from your pipelines. The Git Resolver has two modes: Cloning a repository anonymously (public repositories only) or fetching individual files via an SCM provider’s API using an API token. The private repositories and API token can be set inside git-resolver-config from the OpenShift pipelines operator. 

This can again replace ClusterTasks, where the tasks can be maintained inside a central repository and reference the tasks by specifying the Git repository URL, revision, path, org, etc. This gives you the benefit of proper task versioning and maintenance. 

Continuing with the previous example, let us consider a scenario where the task YAML file is hosted within a designated location, such as the URL https://github.com/tektoncd/catalog, specifically under the path task/generate-random-number/. Moreover, the task is maintained with different versions, for instance, the version 0.6/generate-random-number.yaml. Consequently, it becomes possible to reference a specific version of the task within the pipeline, thus offering precise task execution based on the desired version.

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: generate-random-number-pipeline
spec:
  tasks:
  - name: generate-random-number
    taskRef:
      resolver: git
      params:
        - name: url
          value: https://github.com/tektoncd/catalog.git
        - name: revision
          value: main
        - name: pathInRepo
          value: task/generate-random-number/0.6/generate-random-number.yaml
  results:
  - name: random-number
    value: $(tasks.generate-random-number.outputs.result)

In addition, the Git resolver can be utilized to reference pipelines, further expanding its functionality. By employing the Git resolver, users gain the flexibility to organize their desired tasks and pipelines to provide availability throughout the cluster while minimizing replication efforts. Additionally, leveraging the security features offered by Git, such as Role-Based Access Control (RBAC), enhances the overall security posture of the pipelines.

At present, the Git resolver is compatible with the following platforms:

• github.com and GitHub Enterprise
• gitlab.com and self-hosted GitLab instances
• Gitea
• BitBucket Server
• BitBucket Cloud

Bundles resolver

A bundles resolver is a feature in Tekton Pipelines that allows you to reference Tekton resources from a Tekton bundle image. A Tekton bundle is a collection of Tekton resources that are packaged together and can be deployed as a single unit. Bundles can be used to share Tekton resources with others or to make it easier to deploy Tekton resources consistently.

Moreover, Tekton bundles are built on top of the OCI image format. This means bundles can be stored and distributed in any OCI registry, such as Docker Hub or Quay.io.

This can again replace ClusterTasks, where you first create and push a Tekton bundle containing the task in a registry and then refer to the task in your pipeline using bundles resolver by passing image and other parameters in taskref. As Tekton bundles are built on top of the OCI registry, you get the security benefits of OCI, like image signing and content trust to make sure that the images are authentic and have not been tampered with. You also reap the scalability and reliability benefits of OCI registries with Tekton bundles. 

Let's continue with the example. First, create and push the bundle to a registry, such as Docker, with proper tagging to help maintain the task:

tkn bundle push docker.io/myorg/mybundle:1.0 -f path/to/my/generate-random-number.yaml

Next, use this image in a pipeline with bundles resolver:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: generate-random-number-pipeline
spec:
  tasks:
  - name: generate-random-number
    taskRef:
      resolver: bundles 
      params:
        - name: bundle
          value: docker.io/myorg/mybundle:1.0
        - name: name
          value: generate-random-number
        - name: kind
          value: task
  results:
  - name: random-number
    value: $(tasks.generate-random-number.outputs.result)

Currently, there is a limitation that no more than ten individual layers (pipelines and/or tasks) can be placed in a single image. However, we recommend using a single image per task/pipeline to reap the benefits of versioning, tagging, and security. 

Hub resolver 

A hub resolver in Tekton is a component used to resolve Tekton resources from the Tekton Hub or Artifact Hub. The Tekton Hub/Artifact Hub is a collection of Tekton resources, such as tasks and pipelines. The hub resolver can pull resources from the Tekton Hub and use them in your Tekton pipelines.

By default, the hub resolver supports the public endpoint of Tekton Hub/Artifact Hub. However, you can configure the resolver to use your hub instance by specifying the ARTIFACT_HUB_API or TEKTON_HUB_API environment variables.

You can use the hub resolver to replace ClusterTasks. To do this, you must host your tasks in your Tekton Hub/Artifact Hub instance and then refer to those objects using the hub resolver. Hosting your tasks in a hub instance will make it easier for you to maintain and search for them using the hub UI, making them easier for other teams to consume.

Following the previous example: 

• Create a Git repository and add your tasks to it.
• Deploy your own hub instance using the instructions here.
• Set the ARTIFACT_HUB_API or TEKTON_HUB_API environment variable to the URL of your hub instance.
• Use the hub resolver to refer to your tasks in your Tekton pipelines.

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: generate-random-number-pipeline
spec:
  tasks:
  - name: generate-random-number
    taskRef:
     resolver: hub
     params:
      - name: kind
        value: task
      - name: name
        value: generate-random-number
  results:
  - name: random-number
    value: $(tasks.generate-random-number.outputs.result)

Custom resolvers

If none of the built-in resolvers fit your needs, you can create your own in any language. Tekton provides an easy way to create one in the form of a Go framework/library.

The approach is similar to how the Tekton controller is written but more simple. In a gist, a resolver watches the ResolutionRequest object and picks up the one that belongs to itself (through the name of the resolver, like "hub" or "git"). From there, it will get a set of parameters, and the contract is that it should return either a valid Task or Pipeline in a relatively short time. This can generate a dynamic Task or Pipeline based on some template and parameters.

This is documented in more detail in upstream document How to write a Resolver.

Conclusion

All resolvers offer viable alternatives to ClusterTasks, with unique capabilities and limitations.

• Cluster resolver follows a K8s native approach that provides additional benefits compared to ClusterTasks, such as K8s RBAC and storage. However, it does not address task maintenance, version management, or task trust.
• Git resolver is valuable for task organization, versioning, and trust management. It reduces replication efforts and enhances security through Git's own RBAC.
• Bundle resolver offers the best security benefits through OCI, such as image signing and content trust. It provides scalability and reliability advantages offered by OCI registries. 
• Hub resolver additionally reaps the benefits of easy searching and filtering tasks using the hub UI.
• Custom resolvers give you the option to create your own solution to fit your needs.

The choice of resolver depends on the specific use case and deployment model of cluster tasks. Factors such as task organization, version management, trust, collaboration, and maintenance will help determine the most suitable resolver for your needs.