Hello World Tutorial
Welcome to the Tekton Pipeline tutorial!
This tutorial will walk you through creating and running some simpleTasks & Pipelinesand running them by creatingTaskRuns and PipelineRuns.
Before starting this tutorial, please install the Tekton CLI.
Note: This tutorial can be run on a local workstation
Task
The main objective of Tekton Pipelines is to run your Task individually or as a
part of a Pipeline. Every Task runs as a Pod on your Kubernetes cluster with
each step as its own container.
A Task defines the work that needs to be executed, for example the
following is a simple Task that will echo hello world:
1 | apiVersion: tekton.dev/v1alpha1 |
The steps are a series of commands to be sequentially executed by the Task.
A TaskRun runs the Task you defined. Here is a simple example
of a TaskRun you can use to execute your Task:
1 | apiVersion: tekton.dev/v1alpha1 |
To apply the yaml files, use the following command:
1 | kubectl apply -f <name-of-file.yaml> |
To see the output of the TaskRun, use the following command:
1 | tkn taskrun describe echo-hello-world-task-run |
You will get an output similar to the following:
1 | Name: echo-hello-world-task-run |
The status of type Succeeded shows that the Task ran successfully.
To see the actual outcome, use the following command:
1 | tkn taskrun logs echo-hello-world-task-run |
You will get an output similar to this:
1 | [echo] hello world |
Task Inputs and Outputs
In more common scenarios, a Task needs multiple steps with input and output
resources to process. For example a Task could fetch source code from a GitHub
repository and build a Docker image from it.
PipelineResources are used to define the artifacts that can be
passed in and out of a Task. There are a few system defined resource types ready
to use, and the following are two examples of the resources commonly needed.
The git resource represents a git repository with
a specific revision:
1 | apiVersion: tekton.dev/v1alpha1 |
The image resource represents the image to be
built by the Task:
1 | apiVersion: tekton.dev/v1alpha1 |
The following is a Task with inputs and outputs. The input resource is a
GitHub repository and the output is the image produced from that source. The
args of the Task command support variable substitution so that the definition of Task is
constant and the value of parameters can change in runtime.
1 | apiVersion: tekton.dev/v1alpha1 |
Before you continue with the TaskRun you will have to
create a secret to push your image to your desired registry.
To do so, use the following command:
1 | kubectl create secret docker-registry regcred \ |
To be able to use this secret the TaskRun needs to use a ServiceAccount.
The ServiceAccount should look similar to this:
1 | apiVersion: v1 |
You need to put your new ServiceAccount into action, to do so, use the following command:
1 | kubectl apply -f <name-of-file.yaml> |
Now you are ready for your first TaskRun.
A TaskRun binds the inputs and outputs to already defined PipelineResources,
sets values to the parameters used for variable substitution in addition to executing theTask steps.
1 | apiVersion: tekton.dev/v1alpha1 |
To apply the yaml files use the following command, you need to apply the twoPipelineResources, the Task and TaskRun.
1 | kubectl apply -f <name-of-file.yaml> |
To see all the resource created so far as part of Tekton Pipelines, run the
command:
1 | kubectl get tekton-pipelines |
You will get an output similar to the following:
1 | NAME AGE |
To see the output of the TaskRun, use the following command:
1 | tkn taskrun describe build-docker-image-from-git-source-task-run |
You will get an output similar to the following:
1 | Name: build-docker-image-from-git-source-task-run |
The status of type Succeeded shows the Task ran successfully and you
can also validate the Docker image is created in the location specified in the
resource definition.
If you run into issues, use the following command to receive the logs:
1 | tkn taskrun logs build-docker-image-from-git-source-task-run |
Pipeline
A Pipeline defines a list of Tasks to execute in order, while
also indicating if any outputs should be used as inputs of a following Task by
using the from field and also indicating
the order of executing (using the runAfter and from fields).
The same variable substitution you used in Tasks is also available in a Pipeline.
For example:
1 | apiVersion: tekton.dev/v1alpha1 |
The above Pipeline is referencing a Task called deploy-using-kubectl which
can be found here:
1 | apiVersion: tekton.dev/v1alpha1 |
With the new Task inside of your Pipeline,
you need to give your ServiceAccount additional permissions to be able to execute the run-kubectl step.
First you have to create a new role, which you have to assign to your ServiceAccount,
to do so, use the following command:
1 | kubectl create clusterrole tutorial-role \ |
Now you need to assign this new role tutorial-role to your ServiceAccount,
to do so, use the following command:
1 | kubectl create clusterrolebinding tutorial-binding \ |
To run the Pipeline, create a PipelineRunas follows:
1 | apiVersion: tekton.dev/v1alpha1 |
The PipelineRun will create the TaskRuns corresponding to each Task and
collect the results.
To apply the yaml files use the following command, you will need to apply thedeploy-task if you want to run the Pipeline.
1 | kubectl apply -f <name-of-file.yaml> |
While the Pipeline is running, you can see what exactly is happening, just use the following command:
1 | tkn pipelinerun logs tutorial-pipeline-run-1 -f |
To see the output of the PipelineRun, use the following command:
1 | tkn pipelinerun describe tutorial-pipeline-run-1 |
You will get an output similar to the following:
1 | Name: tutorial-pipeline-run-1 |
The status of type Succeeded shows the Pipeline ran successfully, also
the status of individual Task runs are shown.
Local development
Known good configuration
Tekton Pipelines is known to work with:
- Docker for Desktop. A known good
configuration specifies six CPUs, 10 GB of memory and 2 GB of swap space. - These prerequisites.
- Setting
host.docker.local:5000as an insecure registry with Docker for
Desktop (set via preferences or configuration, see the
Docker insecure registry documentation.
for details) - Passing
--insecureas an argument to Kaniko tasks lets us push to an
insecure registry. - Running a local (insecure) Docker registry: this can be run with
docker run -d -p 5000:5000 --name registry-srv -e REGISTRY_STORAGE_DELETE_ENABLED=true registry:2
- Optionally, a Docker registry viewer so we can check our pushed images are
present:
docker run -it -p 8080:8080 --name registry-web --link registry-srv -e REGISTRY_URL=http://registry-srv:5000/v2 -e REGISTRY_NAME=localhost:5000 hyper/docker-registry-web
Images
- Any PipelineResource definitions of image type should be updated to use the
local registry by setting the url tohost.docker.internal:5000/myregistry/<image name>equivalents - The
KO_DOCKER_REPOvariable should be set tolocalhost:5000/myregistry
before usingko - You are able to push to
host.docker.internal:5000/myregistry/<image name>
but your applications (e.g any deployment definitions) should referencelocalhost:5000/myregistry/<image name>
Logging
- Logs can remain in-memory only as opposed to sent to a service such as
Stackdriver. - See docs on getting logs from Runs
Elasticsearch, Beats and Kibana can be deployed locally as a means to view logs:
an example is provided at
https://github.com/mgreau/tekton-pipelines-elastic-tutorials.
Experimentation
Lines of code you may want to configure have the #configure annotation. This
annotation applies to subjects such as Docker registries, log output locations
and other nuances that may be specific to particular cloud providers or
services.
The TaskRuns have been created in the following
order:
tutorial-pipeline-run-1-build-skaffold-web- This runs the
Pipeline Taskbuild-skaffold-webfirst,
because it has nofromorrunAfterclausestutorial-pipeline-run-1-deploy-web- This runsdeploy-websecond, because
its inputweb-imagecomesfrombuild-skaffold-web(thereforebuild-skaffold-webmust run beforedeploy-web).
