From dbdb9ae64c9ed809ac6ca58c54c0a4d54b38848f Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Tue, 28 Apr 2026 17:06:42 +0530 Subject: [PATCH 1/3] docs: fix issues from workshop tester feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address documentation issues reported during TSF workshop testing: - Use items[0] selector for route commands (names are auto-generated) - Add --force note for tsf config --create in pre-provisioned envs - Add note to skip Quay integration if secret pre-exists - Note that cosign must be installed locally, not in installer container - Update UI flow: View my namespaces → select tenant → Create Application - Move Add component under Actions dropdown - Add GitLab example URL for component creation - Rename tssc-keycloak namespace to tsf-keycloak - Add missing namespaces (cert-manager, konflux-cli, konflux-info, tsf) - Update troubleshooting to reference manageSubscription auto value Co-Authored-By: Claude Opus 4.6 --- docs/modules/ROOT/pages/getting-started.adoc | 19 ++++++++++++++----- docs/modules/ROOT/pages/installing.adoc | 10 ++++++++-- docs/modules/ROOT/pages/troubleshooting.adoc | 2 +- .../ROOT/pages/verifying-and-accessing.adoc | 15 ++++++++++----- 4 files changed, 33 insertions(+), 13 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index 83a05617..a74f2981 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -19,13 +19,17 @@ After installing and verifying {TSFShortName}, onboard your first application to . Authorize the `dex-client` service account when prompted. -The {KonfluxName} dashboard displays the *Get started with {KonfluxName}* landing page. +The {KonfluxName} dashboard displays the landing page. == Create an application An application in {KonfluxName} is a logical grouping of one or more components that are built, tested, and released together. -. In the {KonfluxName} UI, click *Create an application*. +. In the {KonfluxName} UI, click *View my namespaces*. + +. Select your tenant namespace (for example, `default-tenant`). + +. Click *Create Application*. . Enter a name for your application, for example, `my-app`. @@ -37,9 +41,14 @@ For more details, see link:https://konflux-ci.dev/docs/building/creating/#creati A component maps to a single Git repository and branch. When you create a component, {KonfluxName} onboards the repository and configures the build pipeline. -. From your application page, click *Add component*. +. From your application page, open the *Actions* dropdown and click *Add component*. -. Enter the Git repository URL for your source code. For example: `\https://github.com/konflux-ci/sample-component-golang`. +. Enter the Git repository URL for your source code. ++ +-- +* GitHub example: `\https://github.com/konflux-ci/sample-component-golang` +* GitLab example: `\https://gitlab.com//sample-component-golang` +-- . Select the branch to build from. @@ -135,7 +144,7 @@ After the build and release complete, verify the security artifacts that {TSFSho . **Signature verification:** + -Verify the image signature using `cosign`: +Verify the image signature using `cosign`. You must have `cosign` installed on your local machine (it is not included in the installer container). + [source,bash] ---- diff --git a/docs/modules/ROOT/pages/installing.adoc b/docs/modules/ROOT/pages/installing.adoc index 6a857782..7069e851 100644 --- a/docs/modules/ROOT/pages/installing.adoc +++ b/docs/modules/ROOT/pages/installing.adoc @@ -62,6 +62,8 @@ tsf config --create ---- + This command creates a `tsf-config` ConfigMap in the `tsf` namespace. The ConfigMap contains a `config.yaml` key that lists all components with their namespaces and `manageSubscription` settings. ++ +NOTE: If the configuration already exists (for example, in a pre-provisioned environment), add the `--force` flag: `tsf config --create --force`. . Check if the Red Hat Cert-Manager Operator is already installed on the cluster: + @@ -233,6 +235,8 @@ tsf integration quay \ --verbose ---- +NOTE: If the Quay integration secret already exists (for example, in a pre-provisioned environment), you can skip this step. Verify by running `oc get secret tsf-quay-integration -n tsf`. + NOTE: When a new component is onboarded to {KonfluxName}, a repository is automatically created in the specified Quay organization. If you are using a free quay.io account, you must manually change the visibility of new repositories to public because of account limitations. If you are using a paid quay.io account, the repositories can remain private. === Verification @@ -268,13 +272,15 @@ tsf deploy + The deployment process installs 9 Helm charts sequentially, creating the following {OCPShortName} projects: + -* `cert-manager-operator` +* `cert-manager` and `cert-manager-operator` +* `konflux-cli` and `konflux-info` * `konflux-operator` * `konflux-ui` * `openshift-storage` * `rhbk-operator` * `rhtpa-operator` -* `tssc-keycloak` +* `tsf` +* `tsf-keycloak` * `tssc-quay` * `tsf-tas` * `tsf-tpa` diff --git a/docs/modules/ROOT/pages/troubleshooting.adoc b/docs/modules/ROOT/pages/troubleshooting.adoc index 0de68af7..f568bab6 100644 --- a/docs/modules/ROOT/pages/troubleshooting.adoc +++ b/docs/modules/ROOT/pages/troubleshooting.adoc @@ -65,7 +65,7 @@ tsf deploy oc edit configmap tsf-config -n tsf ---- -Locate the Cert-Manager entry and change `manageSubscription: true` to `manageSubscription: false`. Then re-run the deployment. +Locate the Cert-Manager entry and change `manageSubscription` to `auto` or `false`. Then re-run the deployment. See xref:installing.adoc#_configure_the_cluster[Configure the cluster] for details on `manageSubscription` values. [id="rhtpa-ui-url-is-not-accessible"] == {RHTPAName} UI URL is not accessible diff --git a/docs/modules/ROOT/pages/verifying-and-accessing.adoc b/docs/modules/ROOT/pages/verifying-and-accessing.adoc index f46441af..f5e8fd4a 100644 --- a/docs/modules/ROOT/pages/verifying-and-accessing.adoc +++ b/docs/modules/ROOT/pages/verifying-and-accessing.adoc @@ -15,14 +15,15 @@ Access the {KonfluxName} web interface to verify that the deployment succeeded a . Open the {KonfluxName} UI URL in a web browser. + -If you did not save the URL from the deployment output, find it through the {OCPShortName} Routes: +If you did not save the URL from the deployment output, retrieve it from the {OCPShortName} route: + [source,bash] ---- -oc get routes -n konflux-ui +KONFLUX_URL=$(oc get route -n konflux-ui -o jsonpath='{.items[0].spec.host}') +echo "Konflux UI: https://$KONFLUX_URL" ---- + -Open the URL in the `HOST/PORT` column. +NOTE: The route name is auto-generated and varies per deployment. The command above uses a selector to retrieve the first route in the `konflux-ui` namespace. . On the {OCPShortName} login page, enter your credentials and click *Log in*. @@ -33,7 +34,7 @@ Open the URL in the `HOST/PORT` column. === Verification -The {KonfluxName} dashboard loads and displays the *Get started with {KonfluxName}* landing page with options to view namespaces and access the Release Monitor Board. +The {KonfluxName} dashboard loads and displays the landing page with options to view your namespaces and access the Release Monitor Board. == Deployed components @@ -49,7 +50,7 @@ The {TSFShortName} installer deploys the following components to your {OCPShortN | Manages application certificate lifecycle. | Red Hat build of Keycloak -| `tssc-keycloak` +| `tsf-keycloak` | `tsf-infrastructure` | Provides identity management and single sign-on. @@ -86,9 +87,13 @@ The {TSFShortName} installer deploys the following components to your {OCPShortN The installer also creates the following supporting namespaces: +* `cert-manager` +* `konflux-cli` +* `konflux-info` * `openshift-storage` * `rhbk-operator` * `rhtpa-operator` +* `tsf` == Next step From 2e4fb39d62910f9542486c2577ebe2e231d42370 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Tue, 28 Apr 2026 20:57:57 +0530 Subject: [PATCH 2/3] docs: address SME review feedback on PR #177 - Link to RHTAS docs for downloading cosign from the cluster - Remove Cert-Manager steps from installing (auto is now default) - Remove Cert-Manager troubleshooting section (no longer applicable) - Use label selector for Konflux UI route instead of items[0] Co-Authored-By: Claude Opus 4.6 --- docs/modules/ROOT/pages/getting-started.adoc | 2 +- docs/modules/ROOT/pages/installing.adoc | 48 ------------------- docs/modules/ROOT/pages/troubleshooting.adoc | 17 ------- .../ROOT/pages/verifying-and-accessing.adoc | 4 +- 4 files changed, 3 insertions(+), 68 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index a74f2981..0667df10 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -144,7 +144,7 @@ After the build and release complete, verify the security artifacts that {TSFSho . **Signature verification:** + -Verify the image signature using `cosign`. You must have `cosign` installed on your local machine (it is not included in the installer container). +Verify the image signature using `cosign`. The `cosign` binary is not included in the installer container. You can download it from the cluster by following the link:https://docs.redhat.com/en/documentation/red_hat_trusted_artifact_signer/1/html-single/deployment_guide/index#downloading-the-trusted-artifact-signer-cli-binaries_deploy[Downloading the {RHTASName} CLI binaries] instructions. + [source,bash] ---- diff --git a/docs/modules/ROOT/pages/installing.adoc b/docs/modules/ROOT/pages/installing.adoc index 7069e851..09b48a53 100644 --- a/docs/modules/ROOT/pages/installing.adoc +++ b/docs/modules/ROOT/pages/installing.adoc @@ -65,54 +65,6 @@ This command creates a `tsf-config` ConfigMap in the `tsf` namespace. The Config + NOTE: If the configuration already exists (for example, in a pre-provisioned environment), add the `--force` flag: `tsf config --create --force`. -. Check if the Red Hat Cert-Manager Operator is already installed on the cluster: -+ -[source,bash] ----- -oc get subscription openshift-cert-manager-operator -n cert-manager-operator ----- -+ -* If the command returns a subscription, Cert-Manager is already installed. Continue to step 3. -* If the command returns `NotFound`, Cert-Manager is not installed. Skip to the verification step. - -. Edit the `tsf-config` ConfigMap to disable the Cert-Manager managed subscription: -+ -[source,bash] ----- -oc edit configmap tsf-config -n tsf ----- -+ -Locate the Cert-Manager product entry and set `manageSubscription` to `auto` or `false`: -+ -[source,yaml] ----- -products: - - name: Cert-Manager - enabled: true - properties: - manageSubscription: auto ----- - -The `tsf-config` ConfigMap in the `tsf` namespace controls which components are installed. Each component has an `enabled` flag and a `manageSubscription` property. The `manageSubscription` property accepts the following values: - -[cols="1,3", options="header"] -|=== -| Value | Behavior - -| `true` -| Manage the subscription. Fails if a subscription not controlled by the tsf-subscription chart already exists. - -| `false` -| Do not manage the subscription. Fails if a required subscription has not been deployed manually. - -| `auto` -| Manage the subscription if it is controlled by the tsf-subscription chart or does not exist. Skip management if the subscription exists and is not controlled by tsf-subscription. -|=== - -TIP: Use `auto` when you are unsure whether an operator is already installed. This value handles both fresh clusters and clusters with pre-installed operators without failing. - -NOTE: The {TSFShortName} installer assumes a fresh cluster. If other {TSFShortName}-managed operators are already installed (such as Red Hat OpenShift Pipelines or {RHTASName}), set `manageSubscription` to `auto` or `false` for each pre-installed component to prevent conflicts. - === Verification Verify that the ConfigMap was created: diff --git a/docs/modules/ROOT/pages/troubleshooting.adoc b/docs/modules/ROOT/pages/troubleshooting.adoc index f568bab6..e0e5ef3e 100644 --- a/docs/modules/ROOT/pages/troubleshooting.adoc +++ b/docs/modules/ROOT/pages/troubleshooting.adoc @@ -6,7 +6,6 @@ Use this guide to diagnose and resolve common issues during {TSFShortName} insta **On this page:** * <> -* <> * <> * <> * <> @@ -51,22 +50,6 @@ tsf integration quay \ tsf deploy ---- -[id="cert-manager-subscription-conflict"] -== Cert-Manager subscription conflict - -**Symptom:** The deployment fails with a subscription conflict error for the Cert-Manager operator. - -**Cause:** The Red Hat Cert-Manager Operator is already installed on the cluster. The {TSFShortName} installer attempts to create a second subscription, which conflicts with the existing one. - -**Resolution:** Edit the `tsf-config` ConfigMap and set `manageSubscription` to `false` for the Cert-Manager component: - -[source,bash] ----- -oc edit configmap tsf-config -n tsf ----- - -Locate the Cert-Manager entry and change `manageSubscription` to `auto` or `false`. Then re-run the deployment. See xref:installing.adoc#_configure_the_cluster[Configure the cluster] for details on `manageSubscription` values. - [id="rhtpa-ui-url-is-not-accessible"] == {RHTPAName} UI URL is not accessible diff --git a/docs/modules/ROOT/pages/verifying-and-accessing.adoc b/docs/modules/ROOT/pages/verifying-and-accessing.adoc index f5e8fd4a..0e6d3984 100644 --- a/docs/modules/ROOT/pages/verifying-and-accessing.adoc +++ b/docs/modules/ROOT/pages/verifying-and-accessing.adoc @@ -19,11 +19,11 @@ If you did not save the URL from the deployment output, retrieve it from the {OC + [source,bash] ---- -KONFLUX_URL=$(oc get route -n konflux-ui -o jsonpath='{.items[0].spec.host}') +KONFLUX_URL=$(oc get route -n konflux-ui -l app.kubernetes.io/part-of=konflux-ui -o jsonpath='{.items[0].spec.host}') echo "Konflux UI: https://$KONFLUX_URL" ---- + -NOTE: The route name is auto-generated and varies per deployment. The command above uses a selector to retrieve the first route in the `konflux-ui` namespace. +NOTE: The route name is auto-generated and varies per deployment. The command above uses a label selector to retrieve the correct route. . On the {OCPShortName} login page, enter your credentials and click *Log in*. From 4cfe80805ecb8c314a1a74b278be3ece4ac4799f Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Tue, 28 Apr 2026 21:01:09 +0530 Subject: [PATCH 3/3] docs: add RHTASVersion attribute and link to cosign docs Add {RHTASVersion} attribute (1.4) to antora.yml so the RHTAS docs version can be updated in one place. Link cosign verification step to RHTAS "Signing and verifying containers" section for download and setup instructions. Co-Authored-By: Claude Opus 4.6 --- docs/antora.yml | 1 + docs/modules/ROOT/pages/getting-started.adoc | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/antora.yml b/docs/antora.yml index 31c0ad2d..4b020608 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -24,4 +24,5 @@ asciidoc: OCPCli: 'oc' KonfluxName: 'Konflux' RHTASName: 'Red Hat Trusted Artifact Signer' + RHTASVersion: '1.4' RHTPAName: 'Red Hat Trusted Profile Analyzer' diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index 0667df10..7409e310 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -144,7 +144,9 @@ After the build and release complete, verify the security artifacts that {TSFSho . **Signature verification:** + -Verify the image signature using `cosign`. The `cosign` binary is not included in the installer container. You can download it from the cluster by following the link:https://docs.redhat.com/en/documentation/red_hat_trusted_artifact_signer/1/html-single/deployment_guide/index#downloading-the-trusted-artifact-signer-cli-binaries_deploy[Downloading the {RHTASName} CLI binaries] instructions. +Download `cosign` from the {OCPShortName} cluster to your local machine. The `cosign` binary is not included in the installer container. For download and setup instructions, see link:https://docs.redhat.com/en/documentation/red_hat_trusted_artifact_signer/{RHTASVersion}/html-single/deployment_guide/index#signing-and-verifying-containers-by-using-cosign-from-the-command-line-interface-for-openshift_deploy[Signing and verifying containers by using Cosign from the command-line interface]. ++ +Verify the image signature: + [source,bash] ----