#Enabling the Built-in Tekton Hub

#Overview

Starting from v4.10.2, a fresh installation no longer deploys the built-in Tekton Hub by default. Tekton catalog artifacts are delivered by the platform's standalone ArtifactHub component instead. ArtifactHub has its own lifecycle, so catalog updates — new tools, Task fixes, version upgrades — can be delivered quickly, independently of the operator release cadence.

The operator still fully supports deploying the built-in Tekton Hub as a transitional option. This guide describes how to enable it, how the new default keeps an existing Tekton Hub working across an operator upgrade, and how to disable it.

If you deploy the standalone ArtifactHub component instead, see Configuring Tekton to Use ArtifactHub Shim to connect the Tekton Hub resolver and DevOps Hub endpoint to it.

The other guides in this section (such as Tekton Hub Configuration and Custom Catalogs) assume the built-in Tekton Hub has been enabled by following this guide.

#How the Switch Works

Whether the operator deploys the built-in Tekton Hub is controlled by an operator-level switch: the AUTOINSTALL_TEKTONHUB key in the tekton-config-defaults ConfigMap in the tekton-operator namespace. Its default value is "preserve".

The switch is three-state:

An unset, empty, or unrecognized value maps to "preserve", so a typo can never fall through to the destructive "false" behavior.

#Enabling the Built-in Tekton Hub

Set the switch to "true". The value is injected into the operator's environment, which is not hot-reloaded — the operator pod must be restarted after changing the ConfigMap.

# 1) Turn the switch on
$ kubectl -n tekton-operator patch configmap tekton-config-defaults \
    --type merge -p '{"data":{"AUTOINSTALL_TEKTONHUB":"true"}}'

# 2) Restart the operator so it re-reads the environment
$ kubectl -n tekton-operator delete pod -l name=tekton-operator

# 3) The operator creates the TektonHub CR for a profile=all TektonConfig shortly
#    after the restart. If the command below reports NotFound, the CR has not been
#    created yet — wait a moment and re-run it.
$ kubectl wait --for=condition=Ready tektonhub/hub --timeout=600s

#The Default on Upgrade

With the default "preserve", upgrading an environment that already runs the built-in Tekton Hub (for example v4.10.1 → v4.10.2) requires no action: the existing Tekton Hub is kept and continues to serve its catalog, so Task and Pipeline references keep resolving. Both the keep and the catalog reuse happen automatically:

• The TektonHub CR and all built-in Tekton Hub workloads are kept, and the operator waits for the hub to become Ready.
• The catalog ConfigMaps imported into the kube-public namespace (the *-latest tool-image ConfigMaps, the overview-template ConfigMaps, the tool-image ConfigMaps, and the mail-template ConfigMaps) are preserved across the operator's internal upgrade, so the catalog served before the upgrade is the catalog served after it.
• The catalog image that this environment already runs is captured and pinned automatically, so the upgrade does not switch the catalog to a tool-image set that may not exist in your registry (particularly relevant for air-gapped installations).

You only need the steps in Pinning the Catalog below when you explicitly enable the built-in Tekton Hub with "true" and want to control which catalog image it uses.

#Pinning the Catalog to the Pre-Upgrade Image

The operator bundle no longer ships the tool images referenced by the catalog (buildah, golang, maven, and so on). The tool image versions referenced by the new catalog may therefore not exist in your environment. This is especially true for air-gapped installations, where the image synchronization list of the new version no longer contains these tool images. The tool images referenced by your pre-upgrade catalog, on the other hand, are guaranteed to exist, because they were synchronized together with the previous version.

For this reason, when you re-enable the built-in Tekton Hub after an upgrade, it is recommended to pin the catalog to the pre-upgrade catalog image, so that the upgrade has no impact on your existing pipelines.

Step 1 — before the upgrade, record the current catalog image:

$ kubectl -n tekton-pipelines get deployment tekton-hub-api \
    -o jsonpath='{.spec.template.spec.initContainers[?(@.name=="catalog-sidecar")].image}'

Step 2 — after the upgrade, enable the switch as described above, then pin the recorded image through the TektonConfig CR:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  hub:
    options:
      deployments:
        tekton-hub-api:                   # deployment name, must match exactly
          spec:
            template:
              spec:
                initContainers:
                  - name: catalog-sidecar # init container name, must match exactly
                    image: <catalog-image-recorded-before-the-upgrade>

#Disabling the Built-in Tekton Hub

If this Hub has custom catalogs and you are switching to artifacthub-shim, first migrate the custom catalog sources and credentials and verify them through the Hub resolver. release-4.10 does not migrate this configuration automatically.

To remove a deployed built-in Tekton Hub, set the switch to "false" and restart the operator in the same way:

$ kubectl -n tekton-operator patch configmap tekton-config-defaults \
    --type merge -p '{"data":{"AUTOINSTALL_TEKTONHUB":"false"}}'

$ kubectl -n tekton-operator delete pod -l name=tekton-operator

The operator then removes the deployed built-in Tekton Hub. When the switch is "false":

• The TektonHub CR and all built-in Tekton Hub workloads are removed. The TektonConfig CR stays Ready.
• The overview-template ConfigMaps imported with the catalog into the kube-public namespace are removed together with the Tekton Hub.
• The tool-image ConfigMaps (catalog-tool-image-*) and mail-template ConfigMaps in the kube-public namespace are kept. They continue to point at the pre-upgrade tool image addresses, which exist in your registry.