Skip to content

Commit 01e3ece

Browse files
author
Souvik Sarkar
committed
Tekton Hub
draft start basic structure more modules intermediate content intermediate content trying to fix build errors trying to fix build errors fixing errors fixing errors fixing errors majority of content added troubleshooting info incorporating reiew comments massive changes incorporated comments incorporated comments incorporating comments from Siamak incorporating comments from Siamak minor comments final comments
1 parent 05063f8 commit 01e3ece

10 files changed

+359
-1
lines changed

‎_attributes/common-attributes.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ endif::[]
8383
:pipelines-shortname: Pipelines
8484
:pipelines-ver: pipelines-1.7
8585
:tekton-chains: Tekton Chains
86+
:tekton-hub: Tekton Hub
8687
//odo
8788
:odo-title: odo
8889
//alibaba cloud

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1595,6 +1595,8 @@ Topics:
15951595
File: uninstalling-pipelines
15961596
- Name: Creating CI/CD solutions for applications using OpenShift Pipelines
15971597
File: creating-applications-with-cicd-pipelines
1598+
- Name: Using Tekton Hub with OpenShift Pipelines
1599+
File: using-tekton-hub-with-openshift-pipelines
15981600
- Name: Working with OpenShift Pipelines using the Developer perspective
15991601
File: working-with-pipelines-using-the-developer-perspective
16001602
- Name: Reducing resource consumption of OpenShift Pipelines

‎cicd/pipelines/creating-applications-with-cicd-pipelines.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,5 +67,6 @@ include::modules/op-triggering-a-pipelinerun.adoc[leveloffset=+1]
6767
* For more details on pipelines in the *Developer* perspective, see the xref:../../cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc#working-with-pipelines-using-the-developer-perspective[working with pipelines in the *Developer* perspective] section.
6868
* To learn more about Security Context Constraints (SCCs), see the xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing Security Context Constraints] section.
6969
* For more examples of reusable tasks, see the link:https://github.com/openshift/pipelines-catalog[OpenShift Catalog] repository. Additionally, you can also see the Tekton Catalog in the Tekton project.
70+
* To install and deploy a custom instance of Tekton Hub for resuable tasks and pipelines, see xref:../../cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc#using-tekton-hub-with-openshift-pipelines[Using {tekton-hub} with {pipelines-title}].
7071
* For more details on re-encrypt TLS termination, see link:https://docs.openshift.com/container-platform/3.11/architecture/networking/routes.html#re-encryption-termination[Re-encryption Termination].
7172
* For more details on secured routes, see the xref:../../networking/routes/secured-routes.adoc#secured-routes[Secured routes] section.

‎cicd/pipelines/installing-pipelines.adoc‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ include::modules/op-disabling-automatic-creation-of-rbac-resources.adoc[leveloff
4747

4848
* You can learn more about installing Operators on {product-title} in the xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[adding Operators to a cluster] section.
4949

50-
* To install Tekton Chains using the {pipelines-title} Operator, see xref:../../cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc#using-tekton-chains-for-openshift-pipelines-supply-chain-security[Using Tekton Chains for OpenShift Pipelines supply chain security].
50+
* To install {tekton-chains} using the {pipelines-title} Operator, see xref:../../cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc#using-tekton-chains-for-openshift-pipelines-supply-chain-security[Using {tekton-chains} for {pipelines-title} supply chain security].
51+
52+
* To install and deploy in-cluster {tekton-hub}, see xref:../../cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc#using-tekton-hub-with-openshift-pipelines[Using {tekton-hub} with {pipelines-title}].
5153

5254
* For more information on using pipelines in a restricted environment, see:
5355

‎cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_content-type: ASSEMBLY
2+
[id="using-tekton-hub-with-openshift-pipelines"]
3+
= Using Tekton Hub with OpenShift Pipelines
4+
include::_attributes/common-attributes.adoc[]
5+
:context: using-tekton-hub-with-openshift-pipelines
6+
7+
toc::[]
8+
9+
:FeatureName: Tekton Hub
10+
include::snippets/technology-preview.adoc[]
11+
12+
[role="_abstract"]
13+
{tekton-hub} helps you discover, search, and share reusable tasks and pipelines for your CI/CD workflows. A public instance of {tekton-hub} is available at link:https://hub.tekton.dev/[hub.tekton.dev]. Cluster administrators can also install and deploy a custom instance of {tekton-hub} for enterprise use.
14+
15+
include::modules/op-installing-and-deploying-tekton-hub-on-an-openshift-cluster.adoc[leveloffset=+1]
16+
17+
include::modules/op-manually-refreshing-the-catalog-in-tekton-hub.adoc[leveloffset=+2]
18+
19+
include::modules/op-setting-a-cron-job-for-refreshing-catalog-in-tekton-hub.adoc[leveloffset=+2]
20+
21+
include::modules/op-adding-new-users-in-tekton-hub-configuration.adoc[leveloffset=+2]
22+
23+
include::modules/op-opting-out-of-tekton-hub-in-the-developer-perspective.adoc[leveloffset=+1]
24+
25+
[role="_additional-resources"]
26+
[id="additional-resources-tekton-hub"]
27+
== Additional resources
28+
29+
* GitHub repository of link:https://github.com/tektoncd/hub[Tekton Hub].
30+
31+
* xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing OpenShift Pipelines]
32+
33+
* xref:../../cicd/pipelines/op-release-notes.adoc#op-release-notes[{pipelines-title} release notes]

‎modules/op-adding-new-users-in-tekton-hub-configuration.adoc‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="adding-new-users-in-tekton-hub-configuration_{context}"]
7+
= Optional: Adding new users in {tekton-hub} configuration
8+
9+
[discrete]
10+
.Procedure
11+
. Depending on the intended scope, cluster administrators can add new users in the `config.yaml` file.
12+
+
13+
[source,yaml]
14+
----
15+
...
16+
scopes:
17+
- name: agent:create
18+
users: [<username_1>, <username_2>] <1>
19+
- name: catalog:refresh
20+
users: [<username_3>, <username_4>]
21+
- name: config:refresh
22+
users: [<username_5>, <username_6>]
23+
24+
default:
25+
scopes:
26+
- rating:read
27+
- rating:write
28+
...
29+
----
30+
<1> The usernames registered with the Git repository hosting service provider.
31+
+
32+
[NOTE]
33+
====
34+
When any user logs in for the first time, they will have only the default scope even if they are added in the `config.yaml`. To activate additional scopes, ensure the user has logged in at least once.
35+
====
36+
37+
. Ensure that in the `config.yaml` file, you have the `config-refresh` scope.
38+
39+
. Refresh the configuration.
40+
+
41+
[source,terminal]
42+
----
43+
$ curl -X POST -H "Authorization: <access-token>" \ <1>
44+
--header "Content-Type: application/json" \
45+
--data '{"force": true} \
46+
<api-route>/system/config/refresh
47+
----
48+
<1> The JWT token.

‎modules/op-installing-and-deploying-tekton-hub-on-an-openshift-cluster.adoc‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="op-installing-and-deploying-tekton-hub-on-an-openshift-cluster_{context}"]
7+
= Installing and deploying {tekton-hub} on a {product-title} cluster
8+
9+
[role="_abstract"]
10+
{tekton-hub} is an optional component; cluster administrators cannot install it using the `TektonConfig` custom resource (CR). To install and manage {tekton-hub}, use the `TektonHub` CR.
11+
12+
[NOTE]
13+
====
14+
If you are using Github Enterprise or Gitlab Enterprise, install and deploy {tekton-hub} in the same network as the enterprise server. For example, if the enterprise server is running behind a VPN, deploy {tekton-hub} on a cluster that is also behind the VPN.
15+
====
16+
17+
[discrete]
18+
.Prerequisites
19+
* Ensure that the {pipelines-title} Operator is installed in the default `openshift-pipelines` namespace on the cluster.
20+
21+
[discrete]
22+
.Procedure
23+
24+
. Create a fork of the link:https://github.com/tektoncd/hub[Tekton Hub] repository.
25+
26+
. Clone the forked repository.
27+
28+
. Update the `config.yaml` file to include at least one user with the following scopes:
29+
* A user with `agent:create` scope who can set up a cron job that refreshes the {tekton-hub} database after an interval, if there are any changes in the catalog.
30+
* A user with the `catalog:refresh` scope who can refresh the catalog and all resources in the database of the {tekton-hub}.
31+
* A user with the `config:refresh` scope who can get additional scopes.
32+
+
33+
[source,yaml]
34+
----
35+
...
36+
scopes:
37+
- name: agent:create
38+
users: <username_registered_with_the_Git_repository_hosting_service_provider>
39+
- name: catalog:refresh
40+
users: <username_registered_with_the_Git_repository_hosting_service_provider>
41+
- name: config:refresh
42+
users: <username_registered_with_the_Git_repository_hosting_service_provider>
43+
...
44+
----
45+
+
46+
The supported service providers are GitHub, GitLab, and BitBucket.
47+
48+
. Create an OAuth application with your Git repository hosting provider, and note the Client ID and Client Secret.
49+
* For a GitHub OAuth application, set the `Homepage URL` and the `Authorization callback URL` as `<auth-route>`.
50+
* For a GitLab OAuth application, set the `REDIRECT_URI` as `<auth-route>/auth/gitlab/callback`.
51+
* For a BitBucket OAuth application, set the `Callback URL` as `<auth-route>`.
52+
53+
. Edit the following fields in the `<tekton_hub_repository>/config/02-api/20-api-secret.yaml` file for the {tekton-hub} API secret:
54+
* `GH_CLIENT_ID`: The Client ID from the OAuth application created with the Git repository hosting service provider.
55+
* `GH_CLIENT_SECRET`: The Client Secret from the OAuth application created with the Git repository hosting service provider.
56+
* `GHE_URL`: GitHub Enterprise URL, if you are authenticating using GitHub Enterprise. Do not provide the URL to the catalog as a value for this field.
57+
* `GL_CLIENT_ID`: The Client ID from the GitLab OAuth application.
58+
* `GL_CLIENT_SECRET`: The Client Secret from the GitLab OAuth application.
59+
* `GLE_URL`: GitLab Enterprise URL, if you are authenticating using GitLab Enterprise. Do not provide the URL to the catalog as a value for this field.
60+
* `BB_CLIENT_ID`: The Client ID from the BitBucket OAuth application.
61+
* `BB_CLIENT_SECRET`: The Client Secret from the BitBucket OAuth application.
62+
* `JWT_SIGNING_KEY`: A long, random string used to sign the JSON Web Token (JWT) created for users.
63+
* `ACCESS_JWT_EXPIRES_IN`: Add the time limit after which the access token expires. For example, `1m`, where `m` denotes minutes. The supported units of time are seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`).
64+
* `REFRESH_JWT_EXPIRES_IN`: Add the time limit after which the refresh token expires. For example, `1m`, where `m` denotes minutes. The supported units of time are seconds (`s`), minutes (`m`), hours (`h`), days (`d`), and weeks (`w`). Ensure that the expiry time set for token refresh is greater than the expiry time set for token access.
65+
* `AUTH_BASE_URL`: Route URL for the OAuth application.
66+
+
67+
[NOTE]
68+
====
69+
* Use the fields related to Client ID and Client Secret for any one of the supported Git repository hosting service providers.
70+
* The account credentials registered with the Git repository hosting service provider enables the users with `catalog: refresh` scope to authenticate and load all catalog resources to the database.
71+
====
72+
73+
. Commit and push the changes to your forked repository.
74+
75+
. Ensure that the `TektonHub` CR is similar to the following example:
76+
+
77+
[source,yaml]
78+
----
79+
apiVersion: operator.tekton.dev/v1alpha1
80+
kind: TektonHub
81+
metadata:
82+
name: hub
83+
spec:
84+
targetNamespace: openshift-pipelines <1>
85+
api:
86+
hubConfigUrl: https://raw.githubusercontent.com/tektoncd/hub/main/config.yaml <2>
87+
----
88+
<1> The namespace in which Tekton Hub must be installed; default is `openshift-pipelines`.
89+
<2> Substitute with the URL of the `config.yaml` file of your forked repository.
90+
91+
. Install the {tekton-hub}.
92+
+
93+
[source,terminal]
94+
----
95+
$ oc apply -f TektonHub.yaml <1>
96+
----
97+
<1> The file name or path of the `TektonConfig` CR.
98+
99+
. Check the status of the installation.
100+
+
101+
[source,terminal]
102+
----
103+
$ oc get tektonhub.operator.tekton.dev
104+
NAME VERSION READY REASON APIURL UIURL
105+
hub v1.7.2 True https://api.route.url/ https://ui.route.url/
106+
----

‎modules/op-manually-refreshing-the-catalog-in-tekton-hub.adoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="manually-refreshing-the-catalog-in-tekton-hub_{context}"]
7+
= Manually refreshing the catalog in {tekton-hub}
8+
9+
[role="_abstract"]
10+
When you install and deploy {tekton-hub} on a {product-title} cluster, a Postgres database is also installed. Initially, the database is empty. To add the tasks and pipelines available in the catalog to the database, cluster administrators must refresh the catalog.
11+
12+
[discrete]
13+
.Prerequisites
14+
* Ensure that you are in the `<tekton_hub_repository>/config/` directory.
15+
16+
[discrete]
17+
.Procedure
18+
. In the {tekton-hub} UI, click **Login** --> **Sign In With GitHub**.
19+
+
20+
[NOTE]
21+
====
22+
GitHub is used as an example from the publicly available link:https://hub.tekton.dev/[Tekton Hub] UI. For custom installation on your cluster, all Git repository hosting service providers for which you have provided Client ID and Client Secret are listed.
23+
====
24+
25+
. On the home page, click the user profile and copy the token.
26+
27+
. Call the Catalog Refresh API.
28+
* To refresh a catalog with a specific name, run the following command:
29+
+
30+
[source,terminal]
31+
----
32+
$ curl -X POST -H "Authorization: <jwt-token>" \ <1>
33+
<api-url>/catalog/<catalog_name>/refresh <2>
34+
----
35+
<1> The {tekton-hub} token copied from UI.
36+
<2> The API pod URL and name of the catalog.
37+
+
38+
Sample output:
39+
+
40+
[source,terminal]
41+
----
42+
[{"id":1,"catalogName":"tekton","status":"queued"}]
43+
----
44+
* To refresh all catalogs, run the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ curl -X POST -H "Authorization: <jwt-token>" \ <1>
49+
<api-url>/catalog/refresh <2>
50+
----
51+
<1> The {tekton-hub} token copied from UI
52+
<2> The API pod URL.
53+
54+
55+
. Refresh the page in the browser.
56+

‎modules/op-opting-out-of-tekton-hub-in-the-developer-perspective.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="opting-out-of-tekton-hub-in-the-developer-perspective_{context}"]
7+
= Opting out of Tekton Hub in the Developer perspective
8+
9+
[role="_abstract"]
10+
Cluster administrators can opt out of displaying {tekton-hub} resources, such as tasks and pipelines, in the **Pipeline Builder** view of the **Developer** perspective of an {product-title} cluster.
11+
12+
[discrete]
13+
.Prerequisite
14+
15+
* Ensure that the {pipelines-title} Operator is installed on the cluster, and the `oc` command line tool is available.
16+
17+
[discrete]
18+
.Procedure
19+
20+
* To opt of displaying {tekton-hub} resources in the **Developer** perspective, set the value of the `enable-devconsole-integration` field in the `TektonConfig` custom resource (CR) to `false`.
21+
+
22+
[source,yaml]
23+
----
24+
apiVersion: operator.tekton.dev/v1alpha1
25+
kind: TektonConfig
26+
metadata:
27+
name: config
28+
spec:
29+
targetNamespace: openshift-pipelines
30+
...
31+
hub:
32+
params:
33+
- name: enable-devconsole-integration
34+
value: "false"
35+
...
36+
----
37+
+
38+
By default, the `TektonConfig` CR does not include the `enable-devconsole-integration` field, and the {pipelines-title} Operator assumes that the value is `true`.

‎modules/op-setting-a-cron-job-for-refreshing-catalog-in-tekton-hub.adoc‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-hub-with-openshift-pipelines.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="setting-a-cron-job-for-refreshing-catalog-in-tekton-hub_{context}"]
7+
= Optional: Setting a cron job for refreshing catalog in {tekton-hub}
8+
9+
[role="_abstract"]
10+
Cluster administrators can optionally set up a cron job to refresh the database after a fixed interval, so that changes in the catalog appear in the {tekton-hub} web console.
11+
12+
[NOTE]
13+
====
14+
If resources are added to the catalog or updated, refreshing the catalog displays these changes in the {tekton-hub} UI. However, if a resource is deleted from the catalog, refreshing the catalog does not remove the resource from the database. The {tekton-hub} UI continues displaying the deleted resource.
15+
====
16+
17+
[discrete]
18+
.Prerequisites
19+
* Ensure that you are in the `<project_root>/config/` directory, where `<project_root>` is the top level directory of the cloned {tekton-hub} repository.
20+
* Ensure that you have a JSON web token (JWT) token with a scope of refreshing the catalog.
21+
22+
[discrete]
23+
.Procedure
24+
. Create an agent-based JWT token for longer use.
25+
+
26+
[source,terminal]
27+
----
28+
$ curl -X PUT --header "Content-Type: application/json" \
29+
-H "Authorization: <access-token>" \ <1>
30+
--data '{"name":"catalog-refresh-agent","scopes": ["catalog:refresh"]}' \
31+
<api-route>/system/user/agent
32+
----
33+
<1> The JWT token.
34+
+
35+
The agent token with the necessary scopes are returned in the `{"token":"<agent_jwt_token>"}` format. Note the returned token and preserve it for the catalog refresh cron job.
36+
37+
. Edit the `05-catalog-refresh-cj/50-catalog-refresh-secret.yaml` file to set the `HUB_TOKEN` parameter to the `<agent_jwt_token>` returned in the previous step.
38+
+
39+
[source,yaml]
40+
----
41+
apiVersion: v1
42+
kind: Secret
43+
metadata:
44+
name: catalog-refresh
45+
type: Opaque
46+
stringData:
47+
HUB_TOKEN: <hub_token> <1>
48+
----
49+
<1> The `<agent_jwt_token>` returned in the previous step.
50+
51+
. Apply the modified YAML files.
52+
+
53+
[source,terminal]
54+
----
55+
$ oc apply -f 05-catalog-refresh-cj/ -n openshift-pipelines.
56+
----
57+
58+
. Optional: By default, the cron job is configured to run every 30 minutes. To change the interval, modify the value of the `schedule` parameter in the `05-catalog-refresh-cj/51-catalog-refresh-cronjob.yaml` file.
59+
+
60+
[source,yaml]
61+
----
62+
apiVersion: batch/v1
63+
kind: CronJob
64+
metadata:
65+
name: catalog-refresh
66+
labels:
67+
app: tekton-hub-api
68+
spec:
69+
schedule: "*/30 * * * *"
70+
...
71+
----

0 commit comments

Comments
 (0)