diff --git a/docs/antora.yml b/docs/antora.yml index 31c0ad2d7..4b0206089 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 83a05617c..7409e3109 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,9 @@ After the build and release complete, verify the security artifacts that {TSFSho . **Signature verification:** + -Verify the image signature using `cosign`: +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] ---- diff --git a/docs/modules/ROOT/pages/installing.adoc b/docs/modules/ROOT/pages/installing.adoc index 6a857782b..09b48a535 100644 --- a/docs/modules/ROOT/pages/installing.adoc +++ b/docs/modules/ROOT/pages/installing.adoc @@ -62,54 +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. - -. 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. +NOTE: If the configuration already exists (for example, in a pre-provisioned environment), add the `--force` flag: `tsf config --create --force`. === Verification @@ -233,6 +187,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 +224,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 0de68af7a..e0e5ef3ec 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: true` to `manageSubscription: false`. Then re-run the deployment. - [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 f46441af8..0e6d39843 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 -l app.kubernetes.io/part-of=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 label selector to retrieve the correct route. . 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