Backstage Pipelines with Tekton Plugin

Install the frontend plugin

1. Add the plugin to the app workspace

   Copy

   yarn workspace app add @backstage-community/plugin-tekton

2. Show PipelineRuns in the entity CI CD tab

   Edit the Entity page in your app

   Copy

   // packages/app/src/components/catalog/EntityPage.tsx
   import React from 'react';
   import { EntitySwitch } from '@backstage/core-components';
   import {
     isTektonCIAvailable,
     TektonCI,
   } from '@backstage-community/plugin-tekton';
   
   const cicdContent = (
     <EntitySwitch>
       {/* other cases */}
       <EntitySwitch.Case if={isTektonCIAvailable}>
         <TektonCI />
       </EntitySwitch.Case>
     </EntitySwitch>
   );
   
   // make sure cicdContent is rendered under the entity CI CD tab in your page layout

Install and configure the Kubernetes backend

The Tekton UI reads data through the Kubernetes backend plugin. Install it and set up access to your clusters.

New backend system

1. Add the backend plugin

   Copy

   yarn workspace backend add @backstage/plugin-kubernetes-backend

2. Register the backend plugin

   Copy

   // packages/backend/src/index.ts
   import { createBackend } from '@backstage/backend-defaults';
   
   const backend = createBackend();
   
   // other backend plugins
   backend.add(import('@backstage/plugin-kubernetes-backend'));
   
   backend.start();

Legacy backend system

1. Add the backend plugin

   Copy

   yarn workspace backend add @backstage/plugin-kubernetes-backend

2. Create the router module

   Copy

   // packages/backend/src/plugins/kubernetes.ts
   import { Router } from 'express';
   import { createRouter } from '@backstage/plugin-kubernetes-backend';
   import type { PluginEnvironment } from '../types';
   
   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     return await createRouter({
       logger: env.logger,
       config: env.config,
       discovery: env.discovery,
       tokenManager: env.tokenManager,
       catalogApi: env.catalogClient,
       permissions: env.permissions,
     });
   }

3. Mount the router

   Copy

   // packages/backend/src/index.ts
   import { Router } from 'express';
   import kubernetes from './plugins/kubernetes';
   
   // create env the same way as in your app
   const apiRouter = Router();
   
   // other routers
   apiRouter.use('/kubernetes', await kubernetes(env));
   
   // expose under /api
   app.use('/api', apiRouter);

Configure app config for Tekton resources

Add Tekton custom resources so the Kubernetes plugin can query them.

# app-config.yaml
kubernetes:
  # your cluster configuration goes here
  customResources:
    - group: 'tekton.dev'
      apiVersion: 'v1'
      plural: 'pipelineruns'
    - group: 'tekton.dev'
      apiVersion: 'v1'
      plural: 'taskruns'

Grant cluster access

Backstage needs read access to Tekton resources and pod logs. Bind these rules to the service account used by your Backstage backend.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-read-only
rules:
  - apiGroups:
      - ""
    resources:
      - pods/log
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - tekton.dev
    resources:
      - pipelineruns
      - taskruns
    verbs:
      - get
      - list

Bind this role to the service account that the backend uses.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: backstage-read-only-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: backstage-read-only
subjects:
  - kind: ServiceAccount
    name: <service-account-name>
    namespace: <service-account-namespace>

Annotate entities in the catalog

Add annotations to each entity that should show Tekton data.

Enable Tekton features on the entity

# catalog-info.yaml for the entity
metadata:
  name: <BACKSTAGE_ENTITY_NAME>
  annotations:
    tekton.dev/cicd: "true"

Link the entity to Kubernetes resources by id

metadata:
  annotations:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

Optionally fix the namespace

metadata:
  annotations:
    backstage.io/kubernetes-namespace: <RESOURCE_NS>

Optionally use a label selector on the cluster side

metadata:
  annotations:
    backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'

Label your Kubernetes resources with the same id

metadata:
  labels:
    backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

When you use a label selector the labels must exist on the resources.

Set permissions when using the permissions framework

Grant these permission names to the user or group that will view Tekton data

kubernetes.clusters.read
kubernetes.resources.read

What you should see in the UI

• Open a component in the catalog, then go to the CI CD tab
• You will see a list of PipelineRuns with name, status, task status, started, and duration
• Expand a row to see the graph for that PipelineRun

Optional UI actions and results

Enable the Vulnerabilities column. Your pipelines must write a result in the PipelineRun that ends with SCAN_OUTPUT. The value is JSON with counts.

# part of a PipelineRun status
status:
  results:
    - name: 'MY_SCAN_OUTPUT'
      value: >
        {"vulnerabilities":{"critical":0,"high":9,"medium":2,"low":13,"unknown":0},
         "unpatched_vulnerabilities":{"critical":0,"high":1,"medium":0,"low":1}}

Enable the SBOM action. Add these annotations on the SBOM task and write a LINK_TO_SBOM result.

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: export-sbom-task
  annotations:
    task.output.location: results
    task.results.format: application/text
    task.results.type: external-link
    task.results.key: LINK_TO_SBOM

Write the result in the task

echo 'https://sbom-viewer.example.test/item/123' | tee $(results.LINK_TO_SBOM.path)

Enable the Output action for reports written to pod logs. Add annotations on tasks that emit JSON reports.

Enterprise contract example

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: enterprise-contract-task
  annotations:
    task.results.format: application/json
    task.results.type: ec
    task.output.location: logs
    task.results.container: step-report-json

ACS image scan example

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: acs-image-scan
  annotations:
    task.results.format: application/json
    task.results.type: roxctl-image-scan
    task.results.key: SCAN_OUTPUT
    task.output.location: logs
    task.results.container: step-report

ACS image check example

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: acs-image-check
  annotations:
    task.results.format: application/json
    task.results.type: roxctl-image-check
    task.results.key: SCAN_OUTPUT
    task.output.location: logs
    task.results.container: step-report

ACS deployment check example

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: acs-deployment-check
  annotations:
    task.results.format: application/json
    task.results.type: roxctl-deployment-check
    task.results.key: SCAN_OUTPUT
    task.output.location: logs
    task.results.container: step-report

PipelineRun level results appear in the Others section of the Output modal.