Skip to content

Commit 10ecaa4

Browse files
JSticklerJStickler
authored
Merge pull request #43307 from sounix000/3750-3704-tekton-hub
RHDEVDOCS-3750+3704 Tekton Hub with OpenShift Pipelines
2 parents 7fbe79f + 01e3ece commit 10ecaa4

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)