Before you begin

Your Kubernetes cluster is starting and may take a few minutes to be available. You will see 'Kubernetes started' in the terminal when it is ready.

Run kubectl cluster-info in the terminal to check its status. You should see the following outputs:

Kubernetes master is running at ...
KubeDNS is running at ...

...

Installing Tekton

To add Tekton to this experimental Kubernetes cluster, execute the command below:

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

It may take a few moments for the installation to complete. To monitor the progress, run the following command:

kubectl get pods --namespace tekton-pipelines

Every component listed in the output should have the status running.

Getting the code

We’ve put everything you need for this scenario in a GitHub repository. To clone this repository, run the following command:

git clone https://github.com/tektoncd/website

Open the directory website/tutorials/katacoda/getting-started/src. The directory consists of three subdirectories and one file:

• app/: a simple Python Flask web application.
• tekton-katacoda/: Tekton resource specifications you will use in this scenario.
• Dockerfile: a Dockerfile for building app/ into a runnable container image.

Almost done

Tekton is now running in your Katacoda experimental cluster. To help the installation run smoothly in this special environment, a few extra steps are required:

mkdir /mnt/data && kubectl apply -f https://k8s.io/examples/pods/storage/pv-volume.yaml && \
kubectl apply -f ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/init.yaml && \
kubectl delete configmap/config-artifact-pvc -n tekton-pipelines && \
kubectl create configmap config-artifact-pvc --from-literal=storageClassName=manual -n tekton-pipelines

As introduced earlier, a Tekton CI/CD workflow is a Tekton pipeline with a number of Tekton tasks, each of which performs an operation, such as retrieving source code or running the unit tests, in the workflow.

Tekton uses Kubernetes Custom Resource Definitions to specify Tekton resources (tasks, pipelines, etc.). To specify a task, for example, you need to create a YAML file as follows:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: YOUR-TASK-NAME
spec:
  resources:
    inputs:
      # The input resource(s) of the task, such as a GitHub repository
    outputs:
      # The output resource(s) of the task, such as an image built from the source
  steps:
    ...
    # Each step of the task

Your first Tekton task

First, you will create a simple Tekton task with one step: running all the tests in app/. Naturally, the task requires that Tekton clones the source code from GitHub, which you can specify in the field spec.resources.inputs:

1. Open website/tutorials/katacoda/getting-started/src/tekton-katacoda/tasks/buildTemplate.yaml.

2. Edit the file; add a new resource to spec.resources.inputs:

    spec:
      resources:
        inputs:
        - name: git
          type: git
   

   git is one of the built-in resource types Tekton provides. It specifies that the task must take a GitHub repository as input. Here you give it the name git, which tells Tekton to clone the repository to /workspace/git.

With the input resource ready, you may now specify the step. Each step in Tekton uses a tool image to run some commands; as an example, if you are a Go developer, you can use the Go tool image to build a Go program, or run tests in a Go project.

Note: Tekton offers a number of pre-configured tasks you can use. You can also find many available images on container registries such as DockerHub, and Google Cloud Platform tool images (builder images) GitHub repository. Of course, if you prefer, it is possible to use an image of your own instead as well.

In this lab, since app/ includes a Python web application, you will use the Python tool image. In the same file, add a step to spec.steps:

steps:
# The name of the step
- name: pytest
  image: python
  command:
  - /bin/bash
  - -c
  args:
  # Changes to the app/ directory, installs required dependencies, and
  # run all the tests with pytest
  - cd /workspace/git/getting-started/src/app && pip3 install -r requirements.txt && pip3 install -r dev_requirements.txt && pytest .

Add more steps

The code is ready for containerization after all the tests pass. For simplicity reasons, in this scenario, you will build the container image with Docker and save it locally (as opposed to pushing it to a remote repository).

Add the following step to the task:

steps:
- name: pytest
  ...
- name: docker
  image: docker
  command:
  - docker
  args:
  - build
  - -f
  - /workspace/git/getting-started/src/Dockerfile
  - -t
  - app
  - /workspace/git/getting-started/src

This step invokes Docker to build the image and gives it the name app.

Important: For security reasons, in production systems you should not use Docker for image building. Alternatives include Kaniko, BuildKit, img, and many more.

Your first Tekton task is now ready. If you have not followed every step above, a complete task specification is available at website/tutorials/katacoda/getting-started/tekton/tasks/build.yaml. To apply this task, run the command below:

cd ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/ && kubectl apply -f tasks/build.yaml

Your second Tekton task (also the last)

The image is now ready for deployment. In this scenario, you will create a second task for this purpose, which uses the kubectl tool image to spin up the container you just built in the cluster.

1. Open website/tutorials/katacoda/getting-started/src/tekton-katacoda/tasks/deployTemplate.yaml.

2. Add the steps:

    steps:
    # Deploy the image
    - name: deploy
      image: lachlanevenson/k8s-kubectl
      args:
        - run
        - myapp
        - --image=app
    # Expose the image for external acceess
    - name: expose
      image: lachlanevenson/k8s-kubectl
      args:
      - expose
      - pod
      - myapp
      - --port=80
      - --target-port=8080
      - --name=mysvc
      - --type="NodePort"
   

   This step uses the lachlanevenson/k8s-kubectl tool image.

See website/tutorials/katacoda/getting-started/src/tekton-katacoda/tasks/deploy.yaml for a complete specification of this task. To apply this task, run the command below:

cd ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/ && kubectl apply -f tasks/deploy.yaml

A side note

So far you have been using hard-coded values in your tasks. Tekton also supports variables in its specification, which allows developers to switch configurations easily at runtime. You can specify them in spec.params and use them in the steps with the $(params.YOUR-VAR-NAME) syntax. For examples, see build.yaml and deploy.yaml.

You can now build the two tasks into a Tekton pipeline. Open and edit website/tutorials/katacoda/getting-started/src/tekton-katacoda/pipelines/pipelineTemplate.yaml.

The pipeline must include all the resources the tasks within use. Add them in the spec.resources field:

spec:
  resources:
  - name: git
    type: git

In other words, to trigger this pipeline, one must provide a resource of the git type, which Tekton will pass to tasks requesting them.

Then you can add tasks to the spec.tasks field using their names:

  tasks:
  # The name of the task in this pipeline
  - name: build-test-app
    taskRef:
      # The name of the task
      name: build-test-app
    resources:
      # The input and output resources this specific task uses
  # The name of the task in this pipeline
  - name: deploy-app
    taskRef:
      # The name of the task
      name: deploy-app

The name of a task is available in the metadata.name field of its specification.

Additionally, you must specify the input and output resources each specific task requires so that the Tekton pipeline can allocate them correctly:

tasks:
  - name: build-test-app
    taskRef:
      name: build-test-app
    resources:
      inputs:
      - name: git
        resource: git
  ...

The pipeline is now ready. If you have not followed every step above, a complete pipeline specification is available at website/tutorials/katacoda/getting-started/src/tekton-katacoda/pipelines/pipeline.yaml. To apply this pipeline, run the command below:

cd ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/ && kubectl apply -f pipelines/pipeline.yaml

So far you have been specifying resources using only their types (git) but not their values (the URL of the GitHub repository). Tekton uses pipeline resources to store these values; to create the git pipeline resource used for this scenario, for example, you can create a YAML file as follows:

apiVersion: tekton.dev/v1alpha1
kind: PipelineResource
metadata:
  # The name of the pipeline resource
  name: example-git
spec:
  type: git
  params:
  # The revision/branch of the repository
  - name: revision
    value: master
  # The URL of the repository
  - name: url
    value: https://github.com/tektoncd/website

The example above is also available at website/tutorials/katacoda/getting-started/src/tekton-katacoda/resources/git.yaml. To apply it, run the command below:

cd ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/ && kubectl apply -f resources/git.yaml

With all the tasks, pipeline resources, and the pipeline itself applied, you can set your CI/CD system in motion. To trigger a pipeline manually, create (once again) a YAML file of the pipelineRun kind. The specification should include the name of the pipeline, and the pipeline resources it uses:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
name: build-test-deploy-app-run
spec:
  pipelineRef:
  name: build-test-deploy-app
  resources:
  - name: git
    resourceRef:
      name: example-git

To apply the pipelineRun specification, run the command below:

cd ~/website/tutorials/katacoda/getting-started/src/tekton-katacoda/ && kubectl apply -f pipelines/run.yaml

Almost done

You can check the status of your pipeline with the following command:

kubectl get pipelineruns/build-test-deploy-app-run -o yaml

The output should look as follows:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  ...  
spec:
  ...
status:
  completionTime: ...
  conditions:
  - lastTransitionTime: ...
    message: ...
    reason: ...
    status: ...
    type: ...
  startTime: ...
  taskRuns:
    ...

It may take a few moments before Tekton finishes executing your pipeline. Check the message, reason, and status Tekton reports. Should an error occur when running the pipeline, the cause will be reported in these fields with instructions for troubleshooting. If everything runs smoothly, you should see an All Steps have completed executing message with a Succeeded reason listed.

Check out the deployment in the cluster

1. Find the IP of your deployed service:

   kubectl get svc

   Write down the CLUSTER-IP of mysvc.

2. Run the following command to access the service:

   curl http://YOUR-CLUSTER-IP/hello

   Replace YOUR-CLUSTER-IP with the value of your own. It may take a few moments before your app gets ready. You should see Hello World! returned as the output.