Chapter 5. Pipelines CLI (tkn)
5.1. Installing tkn
Use the CLI tool to manage Red Hat OpenShift Pipelines from a terminal. The following section describes how to install the CLI tool on different platforms.
You can also find the URL to the latest binaries from the OpenShift Container Platform web console by clicking the ? icon in the upper-right corner and selecting Command Line Tools. :FeatureName: Running Red Hat OpenShift Pipelines on ARM hardware
{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
Both the archives and the RPMs contain the following executables:
- tkn
- tkn-pac
- opc
Running Red Hat OpenShift Pipelines with the opc
CLI tool is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
5.1.1. Installing the Red Hat OpenShift Pipelines CLI on Linux
For Linux distributions, you can download the CLI as a tar.gz
archive.
Procedure
Download the relevant CLI tool.
Unpack the archive:
$ tar xvzf <file>
-
Add the location of your
tkn
,tkn-pac
, andopc
files to yourPATH
environment variable. To check your
PATH
, run the following command:$ echo $PATH
5.1.2. Installing the Red Hat OpenShift Pipelines CLI on Linux using an RPM
For Red Hat Enterprise Linux (RHEL) version 8, you can install the Red Hat OpenShift Pipelines CLI as an RPM.
Prerequisites
- You have an active OpenShift Container Platform subscription on your Red Hat account.
- You have root or sudo privileges on your local system.
Procedure
Register with Red Hat Subscription Manager:
# subscription-manager register
Pull the latest subscription data:
# subscription-manager refresh
List the available subscriptions:
# subscription-manager list --available --matches '*pipelines*'
In the output for the previous command, find the pool ID for your OpenShift Container Platform subscription and attach the subscription to the registered system:
# subscription-manager attach --pool=<pool_id>
Enable the repositories required by Red Hat OpenShift Pipelines:
Linux (x86_64, amd64)
# subscription-manager repos --enable="pipelines-1.13-for-rhel-8-x86_64-rpms"
Linux on IBM Z and IBM® LinuxONE (s390x)
# subscription-manager repos --enable="pipelines-1.13-for-rhel-8-s390x-rpms"
Linux on IBM Power (ppc64le)
# subscription-manager repos --enable="pipelines-1.13-for-rhel-8-ppc64le-rpms"
Linux on ARM (aarch64, arm64)
# subscription-manager repos --enable="pipelines-1.13-for-rhel-8-aarch64-rpms"
Install the
openshift-pipelines-client
package:# yum install openshift-pipelines-client
After you install the CLI, it is available using the tkn
command:
$ tkn version
5.1.3. Installing the Red Hat OpenShift Pipelines CLI on Windows
For Windows, you can download the CLI as a zip
archive.
Procedure
- Download the CLI tool.
- Extract the archive with a ZIP program.
-
Add the location of your
tkn
,tkn-pac
, andopc
files to yourPATH
environment variable. To check your
PATH
, run the following command:C:\> path
5.1.4. Installing the Red Hat OpenShift Pipelines CLI on macOS
For macOS, you can download the CLI as a tar.gz
archive.
Procedure
Download the relevant CLI tool.
- Unpack and extract the archive.
-
Add the location of your
tkn
,tkn-pac
, andopc
files to yourPATH
environment variable. To check your
PATH
, run the following command:$ echo $PATH
5.2. Configuring the OpenShift Pipelines tkn CLI
Configure the Red Hat OpenShift Pipelines tkn
CLI to enable tab completion.
5.2.1. Enabling tab completion
After you install the tkn
CLI, you can enable tab completion to automatically complete tkn
commands or suggest options when you press Tab.
Prerequisites
-
You must have the
tkn
CLI tool installed. -
You must have
bash-completion
installed on your local system.
Procedure
The following procedure enables tab completion for Bash.
Save the Bash completion code to a file:
$ tkn completion bash > tkn_bash_completion
Copy the file to
/etc/bash_completion.d/
:$ sudo cp tkn_bash_completion /etc/bash_completion.d/
Alternatively, you can save the file to a local directory and source it from your
.bashrc
file instead.
Tab completion is enabled when you open a new terminal.
5.3. OpenShift Pipelines tkn reference
This section lists the basic tkn
CLI commands.
5.3.1. Basic syntax
tkn [command or options] [arguments…]
5.3.2. Global options
--help, -h
5.3.3. Utility commands
5.3.3.1. tkn
Parent command for tkn
CLI.
Example: Display all options
$ tkn
5.3.3.2. completion [shell]
Print shell completion code which must be evaluated to provide interactive completion. Supported shells are bash
and zsh
.
Example: Completion code for bash
shell
$ tkn completion bash
5.3.3.3. version
Print version information of the tkn
CLI.
Example: Check the tkn
version
$ tkn version
5.3.4. Pipelines management commands
5.3.4.1. pipeline
Manage pipelines.
Example: Display help
$ tkn pipeline --help
5.3.4.2. pipeline delete
Delete a pipeline.
Example: Delete the mypipeline
pipeline from a namespace
$ tkn pipeline delete mypipeline -n myspace
5.3.4.3. pipeline describe
Describe a pipeline.
Example: Describe the mypipeline
pipeline
$ tkn pipeline describe mypipeline
5.3.4.4. pipeline list
Display a list of pipelines.
Example: Display a list of pipelines
$ tkn pipeline list
5.3.4.5. pipeline logs
Display the logs for a specific pipeline.
Example: Stream the live logs for the mypipeline
pipeline
$ tkn pipeline logs -f mypipeline
5.3.4.6. pipeline start
Start a pipeline.
Example: Start the mypipeline
pipeline
$ tkn pipeline start mypipeline
5.3.5. Pipeline run commands
5.3.5.1. pipelinerun
Manage pipeline runs.
Example: Display help
$ tkn pipelinerun -h
5.3.5.2. pipelinerun cancel
Cancel a pipeline run.
Example: Cancel the mypipelinerun
pipeline run from a namespace
$ tkn pipelinerun cancel mypipelinerun -n myspace
5.3.5.3. pipelinerun delete
Delete a pipeline run.
Example: Delete pipeline runs from a namespace
$ tkn pipelinerun delete mypipelinerun1 mypipelinerun2 -n myspace
Example: Delete all pipeline runs from a namespace, except the five most recently executed pipeline runs
$ tkn pipelinerun delete -n myspace --keep 5 1
- 1
- Replace
5
with the number of most recently executed pipeline runs you want to retain.
Example: Delete all pipelines
$ tkn pipelinerun delete --all
Starting with Red Hat OpenShift Pipelines 1.6, the tkn pipelinerun delete --all
command does not delete any resources that are in the running state.
5.3.5.4. pipelinerun describe
Describe a pipeline run.
Example: Describe the mypipelinerun
pipeline run in a namespace
$ tkn pipelinerun describe mypipelinerun -n myspace
5.3.5.5. pipelinerun list
List pipeline runs.
Example: Display a list of pipeline runs in a namespace
$ tkn pipelinerun list -n myspace
5.3.5.6. pipelinerun logs
Display the logs of a pipeline run.
Example: Display the logs of the mypipelinerun
pipeline run with all tasks and steps in a namespace
$ tkn pipelinerun logs mypipelinerun -a -n myspace
5.3.6. Task management commands
5.3.6.1. task
Manage tasks.
Example: Display help
$ tkn task -h
5.3.6.2. task delete
Delete a task.
Example: Delete mytask1
and mytask2
tasks from a namespace
$ tkn task delete mytask1 mytask2 -n myspace
5.3.6.3. task describe
Describe a task.
Example: Describe the mytask
task in a namespace
$ tkn task describe mytask -n myspace
5.3.6.4. task list
List tasks.
Example: List all the tasks in a namespace
$ tkn task list -n myspace
5.3.6.5. task logs
Display task logs.
Example: Display logs for the mytaskrun
task run of the mytask
task
$ tkn task logs mytask mytaskrun -n myspace
5.3.6.6. task start
Start a task.
Example: Start the mytask
task in a namespace
$ tkn task start mytask -s <ServiceAccountName> -n myspace
5.3.7. Task run commands
5.3.7.1. taskrun
Manage task runs.
Example: Display help
$ tkn taskrun -h
5.3.7.2. taskrun cancel
Cancel a task run.
Example: Cancel the mytaskrun
task run from a namespace
$ tkn taskrun cancel mytaskrun -n myspace
5.3.7.3. taskrun delete
Delete a TaskRun.
Example: Delete the mytaskrun1
and mytaskrun2
task runs from a namespace
$ tkn taskrun delete mytaskrun1 mytaskrun2 -n myspace
Example: Delete all but the five most recently executed task runs from a namespace
$ tkn taskrun delete -n myspace --keep 5 1
- 1
- Replace
5
with the number of most recently executed task runs you want to retain.
5.3.7.4. taskrun describe
Describe a task run.
Example: Describe the mytaskrun
task run in a namespace
$ tkn taskrun describe mytaskrun -n myspace
5.3.7.5. taskrun list
List task runs.
Example: List all the task runs in a namespace
$ tkn taskrun list -n myspace
5.3.7.6. taskrun logs
Display task run logs.
Example: Display live logs for the mytaskrun
task run in a namespace
$ tkn taskrun logs -f mytaskrun -n myspace
5.3.8. Condition management commands
5.3.8.1. condition
Manage Conditions.
Example: Display help
$ tkn condition --help
5.3.8.2. condition delete
Delete a Condition.
Example: Delete the mycondition1
Condition from a namespace
$ tkn condition delete mycondition1 -n myspace
5.3.8.3. condition describe
Describe a Condition.
Example: Describe the mycondition1
Condition in a namespace
$ tkn condition describe mycondition1 -n myspace
5.3.8.4. condition list
List Conditions.
Example: List Conditions in a namespace
$ tkn condition list -n myspace
5.3.9. Pipeline Resource management commands
5.3.9.1. resource
Manage Pipeline Resources.
Example: Display help
$ tkn resource -h
5.3.9.2. resource create
Create a Pipeline Resource.
Example: Create a Pipeline Resource in a namespace
$ tkn resource create -n myspace
This is an interactive command that asks for input on the name of the Resource, type of the Resource, and the values based on the type of the Resource.
5.3.9.3. resource delete
Delete a Pipeline Resource.
Example: Delete the myresource
Pipeline Resource from a namespace
$ tkn resource delete myresource -n myspace
5.3.9.4. resource describe
Describe a Pipeline Resource.
Example: Describe the myresource
Pipeline Resource
$ tkn resource describe myresource -n myspace
5.3.9.5. resource list
List Pipeline Resources.
Example: List all Pipeline Resources in a namespace
$ tkn resource list -n myspace
5.3.10. ClusterTask management commands
In Red Hat OpenShift Pipelines 1.10, ClusterTask functionality of the tkn
command line utility is deprecated and is planned to be removed in a future release.
5.3.10.1. clustertask
Manage ClusterTasks.
Example: Display help
$ tkn clustertask --help
5.3.10.2. clustertask delete
Delete a ClusterTask resource in a cluster.
Example: Delete mytask1
and mytask2
ClusterTasks
$ tkn clustertask delete mytask1 mytask2
5.3.10.3. clustertask describe
Describe a ClusterTask.
Example: Describe the mytask
ClusterTask
$ tkn clustertask describe mytask1
5.3.10.4. clustertask list
List ClusterTasks.
Example: List ClusterTasks
$ tkn clustertask list
5.3.10.5. clustertask start
Start ClusterTasks.
Example: Start the mytask
ClusterTask
$ tkn clustertask start mytask
5.3.11. Trigger management commands
5.3.11.1. eventlistener
Manage EventListeners.
Example: Display help
$ tkn eventlistener -h
5.3.11.2. eventlistener delete
Delete an EventListener.
Example: Delete mylistener1
and mylistener2
EventListeners in a namespace
$ tkn eventlistener delete mylistener1 mylistener2 -n myspace
5.3.11.3. eventlistener describe
Describe an EventListener.
Example: Describe the mylistener
EventListener in a namespace
$ tkn eventlistener describe mylistener -n myspace
5.3.11.4. eventlistener list
List EventListeners.
Example: List all the EventListeners in a namespace
$ tkn eventlistener list -n myspace
5.3.11.5. eventlistener logs
Display logs of an EventListener.
Example: Display the logs of the mylistener
EventListener in a namespace
$ tkn eventlistener logs mylistener -n myspace
5.3.11.6. triggerbinding
Manage TriggerBindings.
Example: Display TriggerBindings help
$ tkn triggerbinding -h
5.3.11.7. triggerbinding delete
Delete a TriggerBinding.
Example: Delete mybinding1
and mybinding2
TriggerBindings in a namespace
$ tkn triggerbinding delete mybinding1 mybinding2 -n myspace
5.3.11.8. triggerbinding describe
Describe a TriggerBinding.
Example: Describe the mybinding
TriggerBinding in a namespace
$ tkn triggerbinding describe mybinding -n myspace
5.3.11.9. triggerbinding list
List TriggerBindings.
Example: List all the TriggerBindings in a namespace
$ tkn triggerbinding list -n myspace
5.3.11.10. triggertemplate
Manage TriggerTemplates.
Example: Display TriggerTemplate help
$ tkn triggertemplate -h
5.3.11.11. triggertemplate delete
Delete a TriggerTemplate.
Example: Delete mytemplate1
and mytemplate2
TriggerTemplates in a namespace
$ tkn triggertemplate delete mytemplate1 mytemplate2 -n `myspace`
5.3.11.12. triggertemplate describe
Describe a TriggerTemplate.
Example: Describe the mytemplate
TriggerTemplate in a namespace
$ tkn triggertemplate describe mytemplate -n `myspace`
5.3.11.13. triggertemplate list
List TriggerTemplates.
Example: List all the TriggerTemplates in a namespace
$ tkn triggertemplate list -n myspace
5.3.11.14. clustertriggerbinding
Manage ClusterTriggerBindings.
Example: Display ClusterTriggerBindings help
$ tkn clustertriggerbinding -h
5.3.11.15. clustertriggerbinding delete
Delete a ClusterTriggerBinding.
Example: Delete myclusterbinding1
and myclusterbinding2
ClusterTriggerBindings
$ tkn clustertriggerbinding delete myclusterbinding1 myclusterbinding2
5.3.11.16. clustertriggerbinding describe
Describe a ClusterTriggerBinding.
Example: Describe the myclusterbinding
ClusterTriggerBinding
$ tkn clustertriggerbinding describe myclusterbinding
5.3.11.17. clustertriggerbinding list
List ClusterTriggerBindings.
Example: List all ClusterTriggerBindings
$ tkn clustertriggerbinding list
5.3.12. Hub interaction commands
Interact with Tekton Hub for resources such as tasks and pipelines.
5.3.12.1. hub
Interact with hub.
Example: Display help
$ tkn hub -h
Example: Interact with a hub API server
$ tkn hub --api-server https://api.hub.tekton.dev
For each example, to get the corresponding sub-commands and flags, run tkn hub <command> --help
.
5.3.12.2. hub downgrade
Downgrade an installed resource.
Example: Downgrade the mytask
task in the mynamespace
namespace to it’s older version
$ tkn hub downgrade task mytask --to version -n mynamespace
5.3.12.3. hub get
Get a resource manifest by its name, kind, catalog, and version.
Example: Get the manifest for a specific version of the myresource
pipeline or task from the tekton
catalog
$ tkn hub get [pipeline | task] myresource --from tekton --version version
5.3.12.4. hub info
Display information about a resource by its name, kind, catalog, and version.
Example: Display information about a specific version of the mytask
task from the tekton
catalog
$ tkn hub info task mytask --from tekton --version version
5.3.12.5. hub install
Install a resource from a catalog by its kind, name, and version.
Example: Install a specific version of the mytask
task from the tekton
catalog in the mynamespace
namespace
$ tkn hub install task mytask --from tekton --version version -n mynamespace
5.3.12.6. hub reinstall
Reinstall a resource by its kind and name.
Example: Reinstall a specific version of the mytask
task from the tekton
catalog in the mynamespace
namespace
$ tkn hub reinstall task mytask --from tekton --version version -n mynamespace
5.3.12.7. hub search
Search a resource by a combination of name, kind, and tags.
Example: Search a resource with a tag cli
$ tkn hub search --tags cli
5.3.12.8. hub upgrade
Upgrade an installed resource.
Example: Upgrade the installed mytask
task in the mynamespace
namespace to a new version
$ tkn hub upgrade task mytask --to version -n mynamespace