Tekton
Prerequisites
Make sure your environment is properly setup.
Follow the instructions here
SetUp
Tekton CLI Installation
-
Tekton CLI is command line utility used to interact with the Tekton resources.
-
Follow the instructions on the tekton CLI github repository https://github.com/tektoncd/cli#installing-tkn
-
For MacOS for example you can use brew
- Verify the Tekton cli
- The command should show a result like:
- If you already have the
tkn
install you can upgrade running
Tekton Pipelines Installation
- To deploy the Tekton pipelines:
oc apply --filename https://raw.githubusercontent.com/ibm-cloud-architecture/learning-cloudnative-101/master/static/yamls/tekton-lab/tekton-operator.yaml
- Note: It will take few mins for the Tekton pipeline components to be installed, you an watch the status using the command:
You can use
Ctrl+c
to terminate the watch - A successful deployment of Tekton pipelines will show the following pods:
Create Target Namespace
- Set the environment variable
NAMESPACE
totekton-demo
, if you open a new terminal remember to set this environment again - Create a the namespace using the variable
NAMESPACE
Tasks
Task Creation
- Create the below yaml files.
- The following snippet shows what a Tekton Task YAML looks like:
-
Create the file task-test.yaml
apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: java-test spec: params: - name: url default: https://github.com/ibm-cloud-architecture/cloudnative_sample_app - name: revision default: master steps: - name: git-clone image: alpine/git script: | git clone -b $(params.revision) --depth 1 $(params.url) /source volumeMounts: - name: source mountPath: /source - name: test image: maven:3.3-jdk-8 workingdir: /source script: | mvn test echo "tests passed with rc=$?" volumeMounts: - name: m2-repository mountPath: /root/.m2 - name: source mountPath: /source volumes: - name: m2-repository emptyDir: {} - name: source emptyDir: {}
-
Each Task has the following:
- name - the unique name using which the task can be referred
- name - the name of the parameter
- description - the description of the parameter
- default - the default value of parameter
-
Note: The
TaskRun
orPipelineRun
could override the parameter values, if no parameter value is passed then the default value will be used. -
steps - One or more sub-tasks that will be executed in the defined order. The step has all the attributes like a Pod spec
- volumes - the task can also mount external volumes using the volumes attribute.
- The parameters that were part of the spec inputs params can be used in the steps using the notation
$(<variable-name>)
.
Task Deploy
-
The application test task could be created using the command:
-
We will use the Tekton cli to inspect the created resources
-
The above command should list one Task as shown below:
TaskRun
- The TaskRun is used to run a specific task independently. In the following section we will run the build-app task created in the previous step
TaskRun Creation
- The following snippet shows what a Tekton TaskRun YAML looks like:
- Create the file taskrun-test.yaml
- generateName - since the TaskRun can be run many times, in order to have unqiue name across the TaskRun ( helpful when checking the TaskRun history) we use this generateName instead of name. When Kubernetes sees generateName it will generate unquie set of characters and suffix the same to build-app-, similar to how pod names are generated
- taskRef - this is used to refer to the Task by its name that will be run as part of this TaskRun. In this example we use build-app Task.
- As described in the earlier section that the Task inputs and outputs could be overridden via TaskRun.
- params - this are the parameter values that are passed to the task
- The application test task(java-maven-test) could be run using the command:
- Note - As tasks will use generated name, never use
oc apply -f taskrun-test.yaml
-
We will use the Tekton cli to inspect the created resources:
The above command should list one TaskRun as shown below: Note - It will take few seconds for the TaskRun to show status as Running as it needs to download the container images. -
To check the logs of the Task Run using the
Note - Each task step will be run within a container of its own. The -f or -a allows to tail the logs from all the containers of the task. For more options runtkn
:tkn tr logs --help
- If you see the TaskRun status as Failed or Error use the following command to check the reason for error:
- If it is successful, you will see something like below. The above command should list one TaskRun as shown below:
Creating additional tasks and deploying them
- Create a Task to build a container image and push to the registry
- This task will be later used by the pipeline.
- Download the task file task-buildah.yaml to build the image, push the image to the registy:
- Create the
buildah
Task using the file and the command: - Use the Tekton cli to inspect the created resources
-
The above command should list one Task as shown below:
-
Create an environment variable for location to push the image to be build. Replace
NAMESPACE
for the dockerhub username, or IBM CR Namespace -
Lets create a Task Run for
The task will start and logs will start printing automaticallybuildah
Task using thetkn
CLI passing the inputs, outputs and service account. -
Verify the status of the Task Run
Output should look like this - To clean up all Pods associated with all Task Runs, delete all the task runs resources
- (Optional) Instead of starting the Task via
tkn task start
you could also use yaml TaskRun, create a file taskrun.yamlThen create the TaskRun with Follow the logs with:apiVersion: tekton.dev/v1beta1 kind: TaskRun metadata: generateName: buildah-task-run- spec: serviceAccountName: pipeline taskRef: name: buildah params: - name: url value: https://github.com/ibm-cloud-architecture/cloudnative_sample_app - name: image value: image-registry.openshift-image-registry.svc:5000/tekton-demo/cloudnative_sample_app
Pipelines
Pipeline Creation
-
Pipelines allows to start multiple Tasks, in parallel or in a certain order
-
Create the file pipeline.yaml, the Pipeline contains two Tasks
apiVersion: tekton.dev/v1beta1 kind: Pipeline metadata: name: test-build spec: params: - name: repo-url default: https://github.com/ibm-cloud-architecture/cloudnative_sample_app - name: revision default: master - name: image-server default: image-registry.openshift-image-registry.svc:5000 - name: image-namespace default: tekton-demo - name: image-repository default: cloudnative_sample_app tasks: - name: test taskRef: name: java-test params: - name: url value: $(params.repo-url) - name: revision value: $(params.revision) - name: build runAfter: [test] taskRef: name: buildah params: - name: image value: $(params.image-server)/$(params.image-namespace)/$(params.image-repository) - name: url value: $(params.repo-url) - name: revision value: $(params.revision)
-
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.
- Create the Pipeline using the command:
- Use the Tekton cli to inspect the created resources The above command should list one Pipeline as shown below:
PipelineRun
PipelineRun Creation
- To execute the Tasks in the Pipeline, you must create a PipelineRun. Creation of a PipelineRun will trigger the creation of TaskRuns for each Task in your pipeline.
- Create the file pipelinerun.yaml serviceAccount - it is always recommended to have a service account associated with PipelineRun, which can then be used to define fine grained roles.
- Create the PipelineRun using the command:
-
We will use the Tekton cli to inspect the created resources
-
The above command should list one PipelineRun as shown below:
-
Wait for few minutes for your pipeline to complete all the tasks. If it is successful, you will see something like below.
-
Run again the pipeline ls command
If it is successful, go to your container registry account and verify if you have thecloudnative_sample_app
image pushed. -
(Optional) Run the pipeline again using the
tkn
CLI - (Optional) Re-run the pipeline using last pipelinerun values
Deploy Application
- Create a deployment
- Verify if the pods are running:
- Expose the deployment as a service
- Expose the service as a route
- Now access the compose the URL of the App using IP and NodePort
- Now access the app from terminal or browser Output should be
Prerequisites
Make sure your environment is properly setup.
Follow the instructions here
SetUp
Tekton CLI Installation
-
Tekton CLI is command line utility used to interact with the Tekton resources.
-
Follow the instructions on the tekton CLI github repository https://github.com/tektoncd/cli#installing-tkn
-
For MacOS for example you can use brew
- Verify the Tekton cli
- The command should show a result like:
- If you already have the
tkn
install you can upgrade running
Tekton Pipelines Installation
- To deploy the Tekton pipelines:
- Note: It will take few mins for the Tekton pipeline components to be installed, you an watch the status using the command:
You can use
Ctrl+c
to terminate the watch - A successful deployment of Tekton pipelines will show the following pods:
Tekton Dashboard Installation (Optional)
- To deploy the Tekton dashboard:
- Note: It will take few mins for the Tekton dashboard components to be installed, you an watch the status using the command:
You can use
Ctrl+c
to terminate the watch - A successful deployment of Tekton pipelines will show the following pods:
- Access the dashboard as follows: You can access the web UI at http://localhost:9097 .
Create Target Namespace
- Set the environment variable
NAMESPACE
totekton-demo
, if you open a new terminal remember to set this environment again - Create a the namespace using the variable
NAMESPACE
Tasks
Task Creation
- Create the below yaml files.
- The following snippet shows what a Tekton Task YAML looks like:
-
Create the file task-test.yaml
apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: java-test spec: params: - name: url - name: revision default: master steps: - name: git-clone image: alpine/git script: | git clone -b $(params.revision) --depth 1 $(params.url) /source volumeMounts: - name: source mountPath: /source - name: test image: maven:3.3-jdk-8 workingdir: /source script: | mvn test echo "tests passed with rc=$?" volumeMounts: - name: m2-repository mountPath: /root/.m2 - name: source mountPath: /source volumes: - name: m2-repository emptyDir: {} - name: source emptyDir: {}
-
Each Task has the following:
- name - the unique name using which the task can be referred
- name - the name of the parameter
- description - the description of the parameter
- default - the default value of parameter
-
Note: The
TaskRun
orPipelineRun
could override the parameter values, if no parameter value is passed then the default value will be used. -
steps - One or more sub-tasks that will be executed in the defined order. The step has all the attributes like a Pod spec
- volumes - the task can also mount external volumes using the volumes attribute.
- The parameters that were part of the spec inputs params can be used in the steps using the notation
$(<variable-name>)
.
Task Deploy
-
The application test task could be created using the command:
-
We will use the Tekton cli to inspect the created resources
-
The above command should list one Task as shown below:
TaskRun
- The TaskRun is used to run a specific task independently. In the following section we will run the build-app task created in the previous step
TaskRun Creation
- The following snippet shows what a Tekton TaskRun YAML looks like:
- Create the file taskrun-test.yaml
- generateName - since the TaskRun can be run many times, in order to have unqiue name across the TaskRun ( helpful when checking the TaskRun history) we use this generateName instead of name. When Kubernetes sees generateName it will generate unquie set of characters and suffix the same to build-app-, similar to how pod names are generated
- taskRef - this is used to refer to the Task by its name that will be run as part of this TaskRun. In this example we use build-app Task.
- As described in the earlier section that the Task inputs and outputs could be overridden via TaskRun.
- params - this are the parameter values that are passed to the task
- The application test task(java-maven-test) could be run using the command:
- Note - As tasks will use generated name, never use
kubectl apply -f taskrun-test.yaml
-
We will use the Tekton cli to inspect the created resources:
The above command should list one TaskRun as shown below: Note - It will take few seconds for the TaskRun to show status as Running as it needs to download the container images. -
To check the logs of the Task Run using the
Note - Each task step will be run within a container of its own. The -f or -a allows to tail the logs from all the containers of the task. For more options runtkn
:tkn tr logs --help
- If you see the TaskRun status as Failed or Error use the following command to check the reason for error:
- If it is successful, you will see something like below. The above command should list one TaskRun as shown below:
Creating additional tasks and deploying them
- Create a Task to build a container image and push to the registry
- This task will be later used by the pipeline.
- Download the task file task-buildah.yaml to build the image, push the image to the registy:
- Create task buildah
- Create the
buildah
Task using the file and the command: - Use the Tekton cli to inspect the created resources
-
The above command should list one Task as shown below:
-
To access the container registry, create the required secret as follows.
- If using IBM Container registry use
iamapikey
forREGISTRY_USERNAME
and get a API Key forREGISTRY_PASSWORD
, use the domain name for the region IBM CR service likeus.icr.io
-
Create the environment variables to be use, replace with real values and include the single quotes:
-
Run the following command to create a secret
regcred
in the namespaceNAMESPACE
kubectl create secret docker-registry regcred \ --docker-server=${REGISTRY_SERVER} \ --docker-username=${REGISTRY_USERNAME} \ --docker-password=${REGISTRY_PASSWORD} \ -n ${NAMESPACE}
Before creating, replace the values as mentioned above. Note: If your docker password contains special characters in it, please enclose the password in double quotes or place an escape character before each special character. - (Optional) Only if you have problems with the credentials you can recreate it, but you have to deleted first
-
Before we run the Task using TaskRun let us create the Kubernetes service account and attach the needed permissions to the service account, the following Kubernetes resource defines a service account called
pipeline
in namespace$NAMESPACE
who will have administrative role within the$NAMESPACE
namespace. - Create the file sa.yaml
-
Create sa role as follows:
-
Create an environment variable for location to push the image to be build. Replace
NAMESPACE
for the dockerhub username, or IBM CR Namespace -
Lets create a Task Run for
buildah
Task using thetkn
CLI passing the inputs, outputs and service account.tkn task start buildah --showlog \ -p url=https://github.com/ibm-cloud-architecture/cloudnative_sample_app \ -p image=${IMAGE_URL} \ -s pipeline \ -n $NAMESPACE
The task will start and logs will start printing automatically
-
Verify the status of the Task Run
Output should look like this - To clean up all Pods associated with all Task Runs, delete all the task runs resources
- (Optional) Instead of starting the Task via
tkn task start
you could also use yaml TaskRun, create a file taskrun-buildah.yaml Make sure update value for parameterimage
with your registry info.Then create the TaskRun withapiVersion: tekton.dev/v1beta1 kind: TaskRun metadata: generateName: buildah-task-run- spec: serviceAccountName: pipeline taskRef: name: buildah params: - name: url value: https://github.com/ibm-cloud-architecture/cloudnative_sample_app - name: image value: docker.io/csantanapr/cloudnative_sample_app
generateName
Follow the logs with:
Pipelines
Pipeline Creation
-
Pipelines allows to start multiple Tasks, in parallel or in a certain order
-
Create the file pipeline.yaml, the Pipeline contains two Tasks
apiVersion: tekton.dev/v1beta1 kind: Pipeline metadata: name: test-build spec: params: - name: repo-url default: https://github.com/ibm-cloud-architecture/cloudnative_sample_app - name: revision default: master - name: image-server - name: image-namespace - name: image-repository default: cloudnative_sample_app tasks: - name: test taskRef: name: java-test params: - name: url value: $(params.repo-url) - name: revision value: $(params.revision) - name: build runAfter: [test] taskRef: name: buildah params: - name: image value: $(params.image-server)/$(params.image-namespace)/$(params.image-repository) - name: url value: $(params.repo-url) - name: revision value: $(params.revision)
-
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.
- Create the Pipeline using the command:
- Use the Tekton cli to inspect the created resources The above command should list one Pipeline as shown below:
PipelineRun
PipelineRun Creation
- To execute the Tasks in the Pipeline, you must create a PipelineRun. Creation of a PipelineRun will trigger the creation of TaskRuns for each Task in your pipeline.
- Create the file pipelinerun.yaml replace the values for
image-server
andimage-namespace
with your own.serviceAccount - it is always recommended to have a service account associated with PipelineRun, which can then be used to define fine grained roles. Replace the values forapiVersion: tekton.dev/v1beta1 kind: PipelineRun metadata: generateName: test-build-run- spec: serviceAccountName: pipeline pipelineRef: name: test-build params: - name: image-server value: us.icr.io - name: image-namespace value: student01-registry
image-server
andimage-namespace
- Create the PipelineRun using the command:
-
We will use the Tekton cli to inspect the created resources
-
The above command should list one PipelineRun as shown below:
-
Get the logs of the pipeline using the following command
- Wait for few minutes for your pipeline to complete all the tasks. If it is successful, you will see something like below.
-
Run again the pipeline ls command
If it is successful, go to your container registry account and verify if you have thecloudnative_sample_app
image pushed. -
(Optional) Run the pipeline again using the
tkn
CLI - (Optional) Re-run the pipeline using last pipelinerun values
Deploy Application
- Add the
imagePullSecret
to thedefault
Service Account - Create a deployment
- Verify if the pods are running:
- Expose the deployment
- Now access the compose the URL of the App using IP and NodePort
export APP_EXTERNAL_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}') export APP_NODEPORT=$(kubectl get svc cloudnative -n $NAMESPACE -o jsonpath='{.spec.ports[0].nodePort}') export APP_URL="http://${APP_EXTERNAL_IP}:${APP_NODEPORT}/greeting?name=Carlos" echo APP_URL=$APP_URL
- Now access the app from terminal or browser Output should be