Getting Started

Prerequisites, Installation, and Basic Usage

Note

See also the Getting started with Tekton interactive tutorial.

Interactive Tutorial

Prerequisites

  • A Kubernetes cluster version 1.15 or higher for Tekton Pipelines v0.11.0 or higher, or a Kubernetescluster version 1.11 or higher for Tekton releases before v0.11.0.
  • Enable Role-Based Access Control (RBAC)in the cluster.
  • Grant current user cluster-admin privileges.

If you are using Google Kubernetes Engine (GKE),see Kubernetes Engine Quickstartfor instructions on setting up a Kubernetes cluster. GKE clusters have RBACenabled and persistent volumes available by default; to grant current userthe required privilege, run the following command:

  1. kubectl create clusterrolebinding cluster-admin-binding \
  2.                                   --clusterrole=cluster-admin \
  3.                                   --user=$(gcloud config get-value core/account)

For other cloud providers or Minikube installations, refer to theirdocumentation for more information.

  1. # Example #1: sign in using the default `system:admin` user with an OpenShift cluster
  2. oc login -u system:admin
  3. # Example #2: sign in using the default `admin:admin` user with a MiniShift cluster
  4. oc login -u admin:admin

Installation

To install the core component of Tekton, Tekton Pipelines, run the command below:

  1. kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml

If your container runtime does not support image-reference:tag@digest (for example, like cri-o used in OpenShift 4.x), use release.notags.yaml instead:

  1. kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml

Note

This command automatically installs the latest official release of theTekton core component, Tekton Pipelines. Ifyou would like to install a previous version, use

  1. kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/YOUR-VERSION/release.yaml

Replace YOUR-VERSION with the release you prefer. You can find the full listof official Tekton releases on GitHub.

Additionally, Tekton Pipelines pushes nightly releases every night togcr.io/tekton-nightly. If you are feeling adventurous and would like toexperiment with the most recent, unreleased code, see Tekton Development Guide.

It may take a few moments before the installation completes. You can checkthe progress with the following command:

  1. kubectl get pods --namespace tekton-pipelines

Confirm that every component listed has the status Running.

Persistent volumes

To run a CI/CD workflow, you need to provide Tekton a Persistent Volumefor storage purposes. Tekton requests a volume of 5Gi withthe default storage class by default. Your Kubernetescluster, such as one from Google Kubernetes Engine, may have persistent volumesset up at the time of creation, thus no extra step is required; if not, youmay have to create them manually. Alternatively, you may ask Tektonto use a Google Cloud Storage bucketor an AWS Simple Storage Service (Amazon S3)bucket instead. Note that the performance of Tekton may vary depending onthe storage option you choose.

Note

You can check available persistent volumes and storage classes with thecommands below:

  1. kubectl get pv
  2. kubectl get storageclasses

These storage options can be configured using ConfigMaps:

If you would like to configure the size and storage class of the PersistentVolume Tekton requests, update the default config-artifact-pvc configMap.This configMap includes two attributes:

  • size: the size of the volume
  • storageClassName: the name of the storage class of the volume

The following example asks Tekton to request a Persistent Volume of 10Gi withthe manual storage class when running a workflow:

  1. kubectl create configmap config-artifact-pvc \
  2.                          --from-literal=size=10Gi \
  3.                          --from-literal=storageClassName=manual \
  4.                          -o yaml -n tekton-pipelines | kubectl replace -f -

If you would like to use Google Cloud Storage or AWS S3 buckets instead,remove the default config-artifact-pvc configMap and create anotherone of the name config-artifact-bucket. This configMap includes thefollowing attributes:

  • location: the address of the bucket, such as gs://my-gcs-bucket/
  • bucket.service.account.secret.name: the name of theKubernetes secretwhere the service account credentials for accessing the bucket reside.
  • bucket.service.account.secret.key: the name of the key in the secret whichTekton should use
  • bucket.service.account.field.name: the name of the environment variableto use when setting up the credentials. Defaults to GOOGLE_APPLICATION_CREDENTIALS;use BOTO_CONFIG if you plan to use an AWS S3 bucket.

The following example asks Tekton to use a Google Cloud Storage bucket forstorage when running a workflow:

  1. kubectl create configmap config-artifact-pvc \
  2.                          --from-literal=location=gs://MY-GCS-BUCKET \
  3.                          --from-literal=bucket.service.account.secret.name=my-secret \
  4.                          --from-literal=bucket.service.account.secret.key=my-key \
  5.                          -o yaml -n tekton-pipelines | kubectl replace -f -

And the my-secret Kubernetes secret is configured as follows:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: my-secret
  5. type: kubernetes.io/opaque
  6. stringData:
  7.   my-key: MY-SERVICE-ACCOUNT-JSON-KEY

Also, Tekton uses the default service account in your Kubernetes clusterunless otherwise configured; if you would like to override this option,update the default-service-account attribute of the ConfigMapconfig-defaults:

  1. kubectl create configmap config-defaults \
  2.                          --from-literal=default-service-account=YOUR-SERVICE-ACCOUNT \
  3.                          -o yaml -n tekton-pipelines | kubectl replace -f -

Set up the CLI

For your convenience, it is recommended that you install the Tekton CLI, tkn,together with the core component of Tekton, Tekton Pipelines.

tkn is available on macOS via brew:

  1. brew tap tektoncd/tools
  2. brew install tektoncd/tools/tektoncd-cli

You can also download it as a tarball from the tkn Releases page.After downloading the file, extract it to your PATH:

  1. # Replace YOUR-DOWNLOADED-FILE with the file path of your own.
  2. sudo tar xvzf YOUR-DOWNLOADED-FILE -C /usr/local/bin/ tkn

tkn is available on Windows via Chocolatey:

  1. choco install tektoncd-cli --confirm

You can also download it as a .zip file from the tkn Releases page.After downloading the file, add it to your Path:

  • Uncompress the .zip file.
  • Open Control Panel > System and Security > System > Advanced System Settings.
  • Click Environment Variables, select the Path variable and click Edit.
  • Click New and add the path to your uncompressed file.
  • Click OK.

tkn is available on Linux as a .deb package (for Debian, Ubuntu andother deb-based distros) and .rpm package (for Fedora, CentOS, and otherrpm-based distros).

  • Debian, Ubuntu, and other deb-based distros

Find the .deb package of the tkn release you would like to install onthe tkn Releases page andinstall it with

  1. # Replace LINK-TO-THE-PACKAGE with the package URL you would like to use.
  2. rpm -Uvh LINK-TO-THE-PACKAGE

If you are using the latest releases of Ubuntu or Debian, you may use theTektonCD CLI PPA instead:

  1. sudo apt update;sudo apt install -y gnupg
  2. sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3EFE0E0A2F2F60AA
  3. echo "deb http://ppa.launchpad.net/tektoncd/cli/ubuntu eoan main"|sudo tee /etc/apt/sources.list.d/tektoncd-ubuntu-cli.list
  4. sudo apt update && sudo apt install -y tektoncd-cli
  • Fedora, CentOS, and other rpm-based distros

Find the .rpm package of the tkn release you would like to install onthe tkn Releases page andinstall it with

  1. # Replace LINK-TO-THE-PACKAGE with the package URL you would like to use.
  2. rpm -Uvh LINK-TO-THE-PACKAGE

If you are using Fedora 30⁄31, CentOS 7⁄8, EPEL, or RHEL 8, @chmouselprovides an unofficial copr package repository for installing thepackage:

  1. dnf copr enable chmouel/tektoncd-cli
  2. dnf install tektoncd-cli

Alternatively, you may download tkn as a tarball:

Find the tarball of the tkn release for your platform (ARM or X86-64)you would like to install on the tkn Releases pageand install it with

  1. # Replace LINK-TO-TARBALL with the package URL you would like to use.
  2. curl -LO LINK-TO-TARBALL
  3. # Replace YOUR-DOWNLOADED-FILE with the file path of your own.
  4. sudo tar xvzf YOUR-DOWNLOADED-FILE -C /usr/local/bin/ tkn

Your first CI/CD workflow with Tekton

With Tekton, each operation in your CI/CD workflow becomes a step,which is executed with a container image you specify. Steps are thenorganized in tasks, which run as a Kubernetes podin your cluster. If you would like to, you can further organize tasksinto pipelines.

To create a task, create a Kubernetes object using the Tekton API withthe kind Task. The following YAML file specifies a task with one simplestep, printing a Hello World! message usingthe official Ubuntu image:

  1. apiVersion: tekton.dev/v1alpha1
  2. kind: Task
  3. metadata:
  4.   name: echo
  5. spec:
  6.   steps:
  7.     - name: echo
  8.       image: ubuntu
  9.       command:
  10.         - echo
  11.       args:
  12.         - "Hello World!"

Write this file to task.yaml, and apply it to your Kubernetes cluster:

  1. kubectl apply -f task.yaml

To run this task with Tekton, you need to create a taskRun, which isanother Kubernetes object using the Tekton API:

  1. apiVersion: tekton.dev/v1alpha1
  2. kind: TaskRun
  3. metadata:
  4.   name: getting-started
  5. spec:
  6.   taskRef:
  7.     name: echo

Write this file to taskRun.yaml, and apply it to your Kubernetes cluster:

  1. kubectl apply -f taskRun.yaml

Tekton will now start running your task. To check out the output, run thecommand below:

  1. tkn taskrun logs getting-started

It may take a few moments before your task completes. You should see an outputas follows:

  1. [echo] Hello World!

What’s next

Now you have the core component of Tekton, Tekton Pipelines, installed onyour Kubernetes/OpenShift cluster with the Tekton CLI installed on your localmachine. If you would like to install more components, see the list below:

Learn more about Tekton in Concepts.