Alauda DevOps Pipelines Docs

Tekton Hub Configuration

TOC

Overview

This guide covers the basic configuration of Tekton Hub instances, including installation and core system settings. Learn how to configure the fundamental aspects of your Tekton Hub deployment.

Important: If you deployed Tekton Hub through TektonConfig, modify the catalog configuration in the TektonConfig resource instead of directly editing the ConfigMap. Direct ConfigMap modifications will be overridden by the Tekton Operator controller.

Namespace Note: Throughout this guide, <tekton-pipelines> is used as a placeholder for your Tekton Hub namespace. Replace it with your actual namespace name. The default installation uses tekton-pipelines namespace.

Core Configuration Areas

This guide covers essential Tekton Hub configuration topics:

  • Catalog Refresh: Automated resource synchronization
  • Categories: Resource classification and organization
  • Hub Resolver: Integration with Tekton Pipelines

Catalog Refresh Configuration

Default Refresh Interval

By default, Tekton Hub refreshes catalogs every 30 minutes to fetch the latest resources from configured repositories.

Modifying Refresh Interval

The refresh interval can be configured by modifying the CATALOG_REFRESH_INTERVAL setting in the tekton-hub-api ConfigMap.

Supported Time Units:

  • s (seconds): 30s, 60s
  • m (minutes): 15m, 30m, 45m
  • h (hours): 1h, 2h, 12h
  • d (days): 1d, 2d
  • w (weeks): 1w, 2w

Example Configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-hub-api
  namespace: <tekton-pipelines>
data:
  CATALOG_REFRESH_INTERVAL: 30m

Disabling Automated Refresh

To skip automated refresh entirely, set the interval to empty or "0":

data:
  CATALOG_REFRESH_INTERVAL: "0"

Categories Configuration

Default Categories

Tekton Hub provides the following standard categories for resource organization:

  • Automation
  • Build Tools
  • CLI
  • Cloud
  • Code Quality
  • Continuous Integration
  • Deployment
  • Developer Tools
  • Image Build
  • Integration & Delivery
  • Git
  • Kubernetes
  • Messaging
  • Monitoring
  • Networking
  • Openshift
  • Publishing
  • Security
  • Storage
  • Testing
  • Script

Adding Custom Categories

You can add custom categories by modifying the CATEGORIES section in the tekton-hub-api ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-hub-api
  namespace: <tekton-pipelines>
data:
  CATEGORIES: |
    - Automation
    - Build Tools
    - CLI
    - Cloud
    - Code Quality
    - Continuous Integration
    - Deployment
    - Developer Tools
    - Image Build
    - Integration & Delivery
    - Git
    - Kubernetes
    - Messaging
    - Monitoring
    - Networking
    - Publishing
    - Security
    - Storage
    - Testing
    - My Custom Category
    - Data Processing
    - Machine Learning

Category Guidelines:

  • Use clear, descriptive names
  • Follow title case formatting
  • Avoid duplicating existing categories
  • Keep names concise but meaningful

Applying Category Changes

After updating the categories:

  1. Apply the updated ConfigMap:

    $ kubectl apply -f tekton-hub-api-configmap.yaml

  2. Refresh the Hub configuration:

    # Restart the API pod
$ kubectl delete pod app=tekton-hub-api -n <tekton-pipelines>

Using Categories in Resources

Resources in your catalog can reference these categories through annotations:

metadata:
  annotations:
    tekton.dev/categories: "Build Tools,Continuous Integration"

Hub Resolver Configuration

The Hub resolver enables users to reference Hub resources in TaskRuns and PipelineRuns. Proper configuration is essential for catalog resource resolution.

Prerequisites

  • Tekton Pipelines v0.41.0 or later
  • Built-in remote resolvers installed
  • Beta features enabled (if using beta resolver features)

Enabling Hub Resolver

Enable the Hub resolver by setting the feature flag in the feature-flags ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: <tekton-pipelines>
data:
  enable-hub-resolver: "true"

Hub Resolver Configuration

Configure Hub resolver defaults via the hubresolver-config ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: hubresolver-config
  namespace: <tekton-pipelines>
data:
  # Default catalog for tasks
  default-tekton-hub-catalog: "tekton-catalog-tasks"

  # Default catalog for pipelines
  default-tekton-hub-pipeline-catalog: "tekton-catalog-pipelines"

  # Default artifact hub catalogs
  default-artifact-hub-task-catalog: "tekton-catalog-tasks"
  default-artifact-hub-pipeline-catalog: "tekton-catalog-pipelines"

  # Default resource kind (task or pipeline)
  default-kind: "task"

  # Default hub type (artifact or tekton)
  default-type: "artifact"

Custom Hub Endpoints

In most cases, you should keep the default TEKTON_HUB_API endpoint (http://tekton-hub-api.tekton-pipelines:8000/) unchanged. Only modify this endpoint when you specifically need to integrate with an external hub API.

For custom Tekton Hub instances, configure API endpoints via environment variables in the resolver deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tekton-pipelines-remote-resolvers
  namespace: <tekton-pipelines>
spec:
  template:
    spec:
      containers:
      - name: controller
        env:
        # Custom Tekton Hub API endpoint
        - name: TEKTON_HUB_API
          value: "https://your-tekton-hub-api.example.com"

        # Custom Artifact Hub API endpoint (if using artifact type)
        - name: ARTIFACT_HUB_API
          value: "https://your-artifact-hub-api.example.com"

Applying Configuration

After updating resolver configuration:

  1. Apply the ConfigMap changes:

    $ kubectl apply -f hubresolver-config.yaml

  2. Restart the resolver deployment:

    $ kubectl delete pod app=tekton-pipelines-resolvers -n <tekton-pipelines>

Testing Hub Resolver

Test resolver configuration with a simple TaskRun:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: test-hub-resolver
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog
      value: "your-custom-catalog"  # Must match catalog name in Hub
    - name: type
      value: tekton
    - name: kind
      value: task
    - name: name
      value: echo-hello
    - name: version
      value: "0.1"

Common Configuration Issues

Hub Resolver Problems

Issue: Resources cannot be resolved via Hub resolver

Solutions:

  1. Verify Hub resolver is enabled: kubectl get cm feature-flags -n <tekton-pipelines> -o yaml
  2. Check resolver configuration: kubectl get cm hubresolver-config -n <tekton-pipelines>
  3. Ensure catalog names match between Hub configuration and resolver parameters

Catalog Refresh Issues

Issue: Catalogs not updating automatically

Solutions:

  1. Check refresh interval setting: CATALOG_REFRESH_INTERVAL
  2. Verify catalog repository accessibility
  3. Review API pod logs for sync errors
  4. Manually restart API pod: kubectl delete pod app=tekton-hub-api -n <tekton-pipelines>

Category Configuration Problems

Issue: Resources not appearing in expected categories

Solutions:

  1. Verify category exists in Hub configuration
  2. Check resource annotations match configured categories
  3. Restart API pod after category changes