diff --git a/downstream/assemblies/devtools/assembly-self-service-about.adoc b/downstream/assemblies/devtools/assembly-self-service-about.adoc new file mode 100644 index 000000000..466493ad8 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-about.adoc @@ -0,0 +1,33 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-about: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-about"] +endif::[] +ifdef::context[] +[id="self-service-about_{context}"] +endif::[] + += About {SelfService} + +:context: self-service-about + +{SelfService} connects with {PlatformName} using an OAuth application for authentication. +For the {SelfServiceShort} release, the following restrictions apply: + +* Users can only use one {PlatformNameShort} instance. +* Users can only use one {PlatformNameShort} Organization. + +[NOTE] +==== +{SelfService} uses a {RHDH} image. +You can use this image to run only {SelfService}. +==== + +ifdef::parent-context-of-self-service-about[:context: {parent-context-of-self-service-about}] +ifndef::parent-context-of-self-service-about[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-accessing-deployment.adoc b/downstream/assemblies/devtools/assembly-self-service-accessing-deployment.adoc new file mode 100644 index 000000000..d0ffc1c95 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-accessing-deployment.adoc @@ -0,0 +1,24 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-accessing-deployment: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-accessing-deployment"] +endif::[] +ifdef::context[] +[id="self-service-accessing-deployment_{context}"] +endif::[] + += Accessing the {SelfServiceShort} deployment + +:context: self-service-accessing-deployment + +include::devtools/proc-self-service-add-deployment-url-oauth-app.adoc[leveloffset=+1] +include::devtools/proc-self-service-sign-in.adoc[leveloffset=+1] + +ifdef::parent-context-of-self-service-accessing-deployment[:context: {parent-context-of-self-service-accessing-deployment}] +ifndef::parent-context-of-self-service-accessing-deployment[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-create-ocp-registry.adoc b/downstream/assemblies/devtools/assembly-self-service-create-ocp-registry.adoc new file mode 100644 index 000000000..3db0a2ce6 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-create-ocp-registry.adoc @@ -0,0 +1,23 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-create-ocp-registry: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-create-ocp-registry"] +endif::[] +ifdef::context[] +[id="self-service-create-ocp-registry_{context}"] +endif::[] + += Creating a plug-in registry in OpenShift + +:context: self-service-create-ocp-registry + +include::devtools/proc-self-service-download-tar.adoc[leveloffset=+1] + +ifdef::parent-context-of-self-service-create-ocp-registry[:context: {parent-context-of-self-service-create-ocp-registry}] +ifndef::parent-context-of-self-service-create-ocp-registry[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-create-ocp-secrets.adoc b/downstream/assemblies/devtools/assembly-self-service-create-ocp-secrets.adoc new file mode 100644 index 000000000..e440e0663 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-create-ocp-secrets.adoc @@ -0,0 +1,27 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-create-ocp-secrets: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-create-ocp-secrets"] +endif::[] +ifdef::context[] +[id="self-service-create-ocp-secrets_{context}"] +endif::[] + += Creating secrets in OpenShift for your environment variables + +:context: self-service-create-ocp-secrets + +Before installing the chart, you must create a set of secrets in your OpenShift project. +The {SelfServiceShort} Helm chart fetches environment variables from OpenShift secrets. + +include::devtools/proc-self-service-create-ocp-auth-secrets.adoc[leveloffset=+1] +include::devtools/proc-self-service-create-scm-secrets.adoc[leveloffset=+1] + +ifdef::parent-context-of-self-service-create-ocp-secrets[:context: {parent-context-of-self-service-create-ocp-secrets}] +ifndef::parent-context-of-self-service-create-ocp-secrets[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-generate-scm-tokens.adoc b/downstream/assemblies/devtools/assembly-self-service-generate-scm-tokens.adoc new file mode 100644 index 000000000..e634d5f3b --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-generate-scm-tokens.adoc @@ -0,0 +1,24 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-generate-scm-tokens: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-generate-scm-tokens"] +endif::[] +ifdef::context[] +[id="self-service-generate-scm-tokens_{context}"] +endif::[] + += Generating GitHub and Gitlab personal access tokens + +:context: self-service-generate-scm-tokens + +include::devtools/proc-self-service-create-gh-pat.adoc[leveloffset=+1] +include::devtools/proc-self-service-create-gl-pat.adoc[leveloffset=+1] + +ifdef::parent-context-of-self-service-generate-scm-tokens[:context: {parent-context-of-self-service-generate-scm-tokens}] +ifndef::parent-context-of-self-service-generate-scm-tokens[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-helm-install.adoc b/downstream/assemblies/devtools/assembly-self-service-helm-install.adoc new file mode 100644 index 000000000..4211213c2 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-helm-install.adoc @@ -0,0 +1,25 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-helm-install: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-helm-install"] +endif::[] +ifdef::context[] +[id="self-service-helm-install_{context}"] +endif::[] + += Installing the {SelfServiceShort} Helm chart + +:context: self-service-helm-install + +include::devtools/proc-self-service-install-helm-from-catalog.adoc[leveloffset=+1] +include::devtools/proc-self-service-install-verify.adoc[leveloffset=+1] +// include::devtools/zzz[leveloffset=+1] + +ifdef::parent-context-of-self-service-helm-install[:context: {parent-context-of-self-service-helm-install}] +ifndef::parent-context-of-self-service-helm-install[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-installation-overview.adoc b/downstream/assemblies/devtools/assembly-self-service-installation-overview.adoc new file mode 100644 index 000000000..b81231cb2 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-installation-overview.adoc @@ -0,0 +1,30 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-installation-overview: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-installation-overview"] +endif::[] +ifdef::context[] +[id="self-service-installation-overview_{context}"] +endif::[] + += Installation overview + +:context: self-service-installation-overview + +You can deploy {SelfServiceShort} from a Helm chart on OpenShift. + +Helm is a tool that simplifies deployment of applications on {OCP} clusters. +Helm uses a packaging format called Helm charts. +A Helm chart is a package of files that define how an application is deployed and managed on OpenShift. +The Helm chart for {SelfServiceShort} is available in the OpenShift Helm catalog. + +include::devtools/con-installation-prereqs.adoc[leveloffset=+1] + +ifdef::parent-context-of-self-service-installation-overview[:context: {parent-context-of-self-service-installation-overview}] +ifndef::parent-context-of-self-service-installation-overview[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-preinstall-config.adoc b/downstream/assemblies/devtools/assembly-self-service-preinstall-config.adoc new file mode 100644 index 000000000..62354c469 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-preinstall-config.adoc @@ -0,0 +1,29 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-preinstall-config: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-preinstall-config"] +endif::[] +ifdef::context[] +[id="self-service-preinstall-config_{context}"] +endif::[] + += Pre-installation configuration + +:context: self-service-preinstall-config + +include::devtools/proc-self-service-create-oauth-app.adoc[leveloffset=+1] +include::devtools/proc-self-service-generate-oauth-token.adoc[leveloffset=+1] +include::assembly-self-service-generate-scm-tokens.adoc[leveloffset=+1] +include::devtools/proc-self-service-ocp-project-setup.adoc[leveloffset=+1] +include::assembly-self-service-create-ocp-registry.adoc[leveloffset=+1] +include::assembly-self-service-create-ocp-secrets.adoc[leveloffset=+1] +// include::devtools/zzz[leveloffset=+1] + +ifdef::parent-context-of-self-service-preinstall-config[:context: {parent-context-of-self-service-preinstall-config}] +ifndef::parent-context-of-self-service-preinstall-config[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-rbac.adoc b/downstream/assemblies/devtools/assembly-self-service-rbac.adoc index 61aed8459..d8f8c8990 100644 --- a/downstream/assemblies/devtools/assembly-self-service-rbac.adoc +++ b/downstream/assemblies/devtools/assembly-self-service-rbac.adoc @@ -1,5 +1,5 @@ ifdef::context[:parent-context: {context}] -[id="self-service-rbac{context}"] +[id="self-service-rbac_{context}"] = Working with RBAC diff --git a/downstream/assemblies/devtools/assembly-self-service-scm-credentials-private-repos.adoc b/downstream/assemblies/devtools/assembly-self-service-scm-credentials-private-repos.adoc index 6f5c173b3..2418a8773 100644 --- a/downstream/assemblies/devtools/assembly-self-service-scm-credentials-private-repos.adoc +++ b/downstream/assemblies/devtools/assembly-self-service-scm-credentials-private-repos.adoc @@ -9,7 +9,7 @@ ifndef::context[] [id="self-service-using-scm-credentials-private-repos"] endif::[] ifdef::context[] -[id="self-service-using-scm-credentials-private-repos{context}"] +[id="self-service-using-scm-credentials-private-repos_{context}"] endif::[] = Configuring source control credentials for private repositories diff --git a/downstream/assemblies/devtools/assembly-self-service-telemetry-capture.adoc b/downstream/assemblies/devtools/assembly-self-service-telemetry-capture.adoc new file mode 100644 index 000000000..51519d245 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-telemetry-capture.adoc @@ -0,0 +1,36 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-telemetry: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-telemetry"] +endif::[] +ifdef::context[] +[id="self-service-telemetry_{context}"] +endif::[] + += Telemetry capturing + +:context: self-service-telemetry + +The telemetry data collection feature helps in collecting and analyzing the telemetry data to improve your experience with self-service technical preview. This feature is enabled by default. + +Red Hat collects and analyses the following data: + +* Events of page visits and clicks on links or buttons. +* System-related information, for example, locale, timezone, user agent including browser and OS details. +* Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters. +* Anonymized IP addresses, recorded as 0.0.0.0. +* Anonymized username hashes, which are unique identifiers used solely to identify the number of unique users of the RHDH application. +* Feedback and sentiment provided in the feedback form. + +// With Red Hat Developer Hub, you can disable or customize the telemetry data collection feature. +// For more information, refer to the Telemetry data collection guide in the Red Hat Developer Hub documentation. +// include::devtools/zzz[leveloffset=+1] + +ifdef::parent-context-of-self-service-telemetry[:context: {parent-context-of-self-service-telemetry}] +ifndef::parent-context-of-self-service-telemetry[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-using-repo-setup.adoc b/downstream/assemblies/devtools/assembly-self-service-using-repo-setup.adoc index 2f7ba3749..697684438 100644 --- a/downstream/assemblies/devtools/assembly-self-service-using-repo-setup.adoc +++ b/downstream/assemblies/devtools/assembly-self-service-using-repo-setup.adoc @@ -9,7 +9,7 @@ ifndef::context[] [id="self-service-using-repo-setup"] endif::[] ifdef::context[] -[id="self-service-using-repo-setup{context}"] +[id="self-service-using-repo-setup_{context}"] endif::[] = Setting up repositories for collections diff --git a/downstream/assemblies/devtools/assembly-self-service-view-deployment.adoc b/downstream/assemblies/devtools/assembly-self-service-view-deployment.adoc new file mode 100644 index 000000000..f9bdad00e --- /dev/null +++ b/downstream/assemblies/devtools/assembly-self-service-view-deployment.adoc @@ -0,0 +1,27 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 + +ifdef::context[:parent-context-of-self-service-view-deployment: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="self-service-view-deployment"] +endif::[] +ifdef::context[] +[id="self-service-view-deployment_{context}"] +endif::[] + += Inspecting the deployment on OpenShift + +:context: self-service-view-deployment + +You can inspect the deployment logs and ConfigMap on the OpenShift UI to verify that the deployment conforms with the settings in your Helm chart. + +include::devtools/proc-self-service-view-deployment-logs.adoc[leveloffset=+1] +include::devtools/proc-self-service-view-configmap.adoc[leveloffset=+1] +// include::devtools/zzz[leveloffset=+1] + +ifdef::parent-context-of-self-service-view-deployment[:context: {parent-context-of-self-service-view-deployment}] +ifndef::parent-context-of-self-service-view-deployment[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-self-service-working-templates.adoc b/downstream/assemblies/devtools/assembly-self-service-working-templates.adoc index f83c51f6a..29cfe24e0 100644 --- a/downstream/assemblies/devtools/assembly-self-service-working-templates.adoc +++ b/downstream/assemblies/devtools/assembly-self-service-working-templates.adoc @@ -9,7 +9,7 @@ ifndef::context[] [id="self-service-working-templates"] endif::[] ifdef::context[] -[id="self-service-working-templates{context}"] +[id="self-service-working-templates_{context}"] endif::[] = Working with templates diff --git a/downstream/images/rhaap-sign-in-page.png b/downstream/images/rhaap-sign-in-page.png new file mode 100644 index 000000000..4d29ba64e Binary files /dev/null and b/downstream/images/rhaap-sign-in-page.png differ diff --git a/downstream/images/self-service-create-oauth-app.png b/downstream/images/self-service-create-oauth-app.png new file mode 100644 index 000000000..b5d493f70 Binary files /dev/null and b/downstream/images/self-service-create-oauth-app.png differ diff --git a/downstream/images/self-service-plugin-registry.png b/downstream/images/self-service-plugin-registry.png new file mode 100644 index 000000000..ea1512c5e Binary files /dev/null and b/downstream/images/self-service-plugin-registry.png differ diff --git a/downstream/images/self-service-pod-env-variables.png b/downstream/images/self-service-pod-env-variables.png new file mode 100644 index 000000000..e13b22a0c Binary files /dev/null and b/downstream/images/self-service-pod-env-variables.png differ diff --git a/downstream/images/self-service-sign-in-page.png b/downstream/images/self-service-sign-in-page.png new file mode 100644 index 000000000..5e616783f Binary files /dev/null and b/downstream/images/self-service-sign-in-page.png differ diff --git a/downstream/images/self-service-templates-view.png b/downstream/images/self-service-templates-view.png new file mode 100644 index 000000000..b894277e3 Binary files /dev/null and b/downstream/images/self-service-templates-view.png differ diff --git a/downstream/images/self-service-verify-helm-install.png b/downstream/images/self-service-verify-helm-install.png new file mode 100644 index 000000000..495b0d4e7 Binary files /dev/null and b/downstream/images/self-service-verify-helm-install.png differ diff --git a/downstream/images/self-service-view-deployment-logs.png b/downstream/images/self-service-view-deployment-logs.png new file mode 100644 index 000000000..a10616178 Binary files /dev/null and b/downstream/images/self-service-view-deployment-logs.png differ diff --git a/downstream/images/self-service-view-install-messages.png b/downstream/images/self-service-view-install-messages.png new file mode 100644 index 000000000..92316ff09 Binary files /dev/null and b/downstream/images/self-service-view-install-messages.png differ diff --git a/downstream/modules/devtools/con-installation-prereqs.adoc b/downstream/modules/devtools/con-installation-prereqs.adoc new file mode 100644 index 000000000..4078c13d3 --- /dev/null +++ b/downstream/modules/devtools/con-installation-prereqs.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: CONCEPT + +[id="self-service-installation-prereqs_{context}"] += Prerequisites + +* A valid subscription to {PlatformName}. +* An {PlatformNameShort} instance with the appropriate permissions to create an OAuth application. +* An {OCPShort} instance (Version 4.12 or newer) with the appropriate permissions within your project to create an application. +* You have installed the OpenShift CLI (`oc`). +See the +link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/cli_tools/openshift-cli-oc#cli-getting-started[Getting started with the OpenShift CLI] +chapter of the _Understanding OpenShift Container Platform_ guide. +* You have installed Helm 3.10 or newer. +See the link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/building_applications/working-with-helm-charts#installing-helm[Installing Helm] +chapter of the _OpenShift Container Platform Building applications_ guide. + diff --git a/downstream/modules/devtools/proc-self-service-add-deployment-url-oauth-app.adoc b/downstream/modules/devtools/proc-self-service-add-deployment-url-oauth-app.adoc new file mode 100644 index 000000000..853a6deff --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-add-deployment-url-oauth-app.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-add-deployment-url-oauth-app_{context}"] += Adding the deployment URL to the OAuth Application + +When you set up your OAuth application in {PlatformNameShort} before deploying {SelfServiceShort}, +you added placeholder text for the `Redirect URL` value. + +You must update this value using the URL from the deployed application so that you can run automation on {SelfServiceShort} from {SelfServiceShort}. + + +. Open the URL for the deployment from the OpenShift console to display the sign-in page for {SelfServiceShort}. +. Copy the URL. +. To determine the Redirect URL value, append /api/auth/rhaap/handler/frame to the end of the deployment URL. ++ +For example, if the URL for the deployment is `\https://my-aap-self-service-technical-preview-backstage-myproject.mycluster.com`, +then the `Redirect URL` value is `\https://my-aap-self-service-technical-preview-backstage-myproject.mycluster.com/api/auth/rhaap/handler/frame`. +. In a browser, open your instance of {PlatformNameShort}. + diff --git a/downstream/modules/devtools/proc-self-service-create-gh-pat.adoc b/downstream/modules/devtools/proc-self-service-create-gh-pat.adoc new file mode 100644 index 000000000..c2e7df08a --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-create-gh-pat.adoc @@ -0,0 +1,18 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 +:_mod-docs-content-type: PROCEDURE + +[id="self-service-create-gh-pat_{context}"] += Creating a Personal access token (PAT) on GitHub + +. In a browser, log in to GitHub and navigate to the +link:https://github.com/settings/tokens[Personal access tokens] +page. +. Click *Generate new token(classic)*. +. In the *Select scopes:* section, enable the following: +** repo +** read:org +** workflow (as needed) +. Click *Generate token*. +. Save the Personal access token. + diff --git a/downstream/modules/devtools/proc-self-service-create-gl-pat.adoc b/downstream/modules/devtools/proc-self-service-create-gl-pat.adoc new file mode 100644 index 000000000..81f1eb2ce --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-create-gl-pat.adoc @@ -0,0 +1,19 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 +:_mod-docs-content-type: PROCEDURE + +[id="self-service-create-gl-pat_{context}"] += Creating a Personal access token (PAT) on Gitlab + + +. In a browser, log in to Gitlab and navigate to the +link:https://gitlab.com/-/user_settings/personal_access_tokens[Personal access tokens] +page. +. Click *Add new token*. +. Provide a name and expiration date for the token. +. In the *Scopes:* section, select the following: +** read_repository +** api +. Click *Create personal access token*. +. Save the Personal access token. + diff --git a/downstream/modules/devtools/proc-self-service-create-oauth-app.adoc b/downstream/modules/devtools/proc-self-service-create-oauth-app.adoc new file mode 100644 index 000000000..fbe3ee073 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-create-oauth-app.adoc @@ -0,0 +1,33 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 +:_mod-docs-content-type: PROCEDURE + +[id="self-service-create-oauth-app_{context}"] += Creating an OAuth application + +To use the Helm chart to deploy {SelfServiceShort}, you must have set up an OAuth application on your {PlatformNameShort} instance. +However, you cannot run automation on your {PlatformNameShort} instance until you have deployed your {SelfServiceShort} Helm chart, +because the OAuth configuration requires the URL for your deployment. + +Create the OAuth Application on your {PlatformNameShort} instance, +using a placeholder name for the deployment URL. + +After deploying {SelfServiceShort}, you must replace the placeholder value with your deployment to your OAuth application. + +The steps below describe how to create an OAuth Application in the {PlatformNameShort} Platform console. + +.Procedure +. Open your {PlatformNameShort} instance in a browser and log in. +. Navigate to {MenuAMAdminOauthApps}. +. Click *Create OAuth Application*. +. Complete the fields in the form, +adding a placeholder text (for example `http:example.com`) in the *Redirect URIs* field: ++ +image::self-service-create-oauth-app.png[Create OAuth application] +. Click *Create OAuth application*. ++ +The *Application information* popup displays the `clientId` and `clientSecret` values. +. Copy the `clientId` and `clientSecret` values and save them. ++ +These values are used in an OpenShift secret for {PlatformNameShort} authentication. + diff --git a/downstream/modules/devtools/proc-self-service-create-ocp-auth-secrets.adoc b/downstream/modules/devtools/proc-self-service-create-ocp-auth-secrets.adoc new file mode 100644 index 000000000..e7db84176 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-create-ocp-auth-secrets.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-create-ocp-auth-secrets_{context}"] += Creating {PlatformNameShort} authentication secrets + +. Log in to your {OCPShort} instance. +. Open your OpenShift project for {SelfServiceShort}. +. Click *Secrets* in the side pane. +. Click *Create* to open the form for creating a new secret. +. Select the *Key/Value* option. +. Create a secret named `secrets-rhaap-self-service-preview`. ++ +[NOTE] +==== +The secret must use this exact name. +==== +. Add the following key-value pairs to the secret. ++ +[NOTE] +==== +The secrets must use the exact key names specified below. +==== ++ +** Key: `aap-host-url` ++ +Value needed: {PlatformNameShort} instance URL ++ +** Key: `oauth-client-id` ++ +Value needed: {PlatformNameShort} OAuth client ID ++ +** Key: `oauth-client-secret` ++ +Value needed: {PlatformNameShort} OAuth client secret value ++ +** Key: `aap-token` ++ +Value needed: Token for {PlatformNameShort} user authentication (must have `write` access). +. Click *Create* to create the secret. + diff --git a/downstream/modules/devtools/proc-self-service-create-scm-secrets.adoc b/downstream/modules/devtools/proc-self-service-create-scm-secrets.adoc new file mode 100644 index 000000000..47d52645d --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-create-scm-secrets.adoc @@ -0,0 +1,33 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-create-scm-secrets_{context}"] += Creating Creating GitHub and Gitlab secrets + +. Log in to your {OCPShort} instance. +. Open your OpenShift project for {SelfServiceShort}. +. Click *Secrets* in the side pane. +. Click *Create* to open the form for creating a new secret. +. Select the *Key/Value* option. +. Create a secret named `secrets-scm`. ++ +[NOTE] +==== +The secret must use this exact name. +==== +. Add the following key-value pairs to the secret. +If you are only using one SCM, just add the key-value pair for that SCM. ++ +[NOTE] +==== +The secrets must use the exact key names specified below. +==== ++ +** Key: `github-token` ++ +Value needed: Github Personal Access Token (PAT) ++ +** Key: `gitlab-token` ++ +Value needed: Gitlab Personal Access Token (PAT) +. Click *Create* to create the secret. + diff --git a/downstream/modules/devtools/proc-self-service-download-tar.adoc b/downstream/modules/devtools/proc-self-service-download-tar.adoc new file mode 100644 index 000000000..d8efe6a5b --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-download-tar.adoc @@ -0,0 +1,47 @@ +:_mod-docs-content-type: PROCEDURE + +[id="rhdh-download-tar_{context}"] += Downloading the TAR files + +. Create a directory on your local machine to store the `.tar` files. ++ +---- +$ mkdir /path/to/ +---- +. Set an environment variable (`$DYNAMIC_PLUGIN_ROOT_DIR`) to represent the directory path. ++ +---- +$ export DYNAMIC_PLUGIN_ROOT_DIR=/path/to/ +---- +. Download the latest `.tar` file for the plug-ins from the +link:{PlatformDownloadUrl}[Red Hat Ansible Automation Platform Product Software downloads page]. ++ +The format of the filename is `ansible-backstage-rhaap-bundle-x.y.z.tar.gz`. ++ +Substitute the Ansible plug-ins release version, for example `1.0.0`, for `x.y.z`. +. Extract the `ansible-backstage-rhaap-bundle-.tar.gz` contents to `$DYNAMIC_PLUGIN_ROOT_DIR`. ++ +---- +$ tar --exclude='*code*' -xzf ansible-backstage-rhaap-bundle-x.y.z.tar.gz -C $DYNAMIC_PLUGIN_ROOT_DIR +---- ++ +Substitute the Ansible plug-ins release version, for example `1.0.0`, for `x.y.z`. + +.Verification + +Run `ls` to verify that the extracted files are in the `$DYNAMIC_PLUGIN_ROOT_DIR` directory: + +---- +$ ls $DYNAMIC_PLUGIN_ROOT_DIR +ansible-plugin-backstage-rhaap-x.y.z.tgz +ansible-plugin-backstage-rhaap-x.y.z.tgz.integrity +ansible-plugin-backstage-rhaap-backend-x.y.z.tgz +ansible-plugin-backstage-rhaap-backend-x.y.z.tgz.integrity +ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz +ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz.integrity + +---- + +The files with the `.integrity` file type contain the plugin SHA value. +The SHA value is used during the plug-in configuration. + diff --git a/downstream/modules/devtools/proc-self-service-generate-oauth-token.adoc b/downstream/modules/devtools/proc-self-service-generate-oauth-token.adoc new file mode 100644 index 000000000..f522bea92 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-generate-oauth-token.adoc @@ -0,0 +1,25 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 +:_mod-docs-content-type: PROCEDURE + +[id="self-service-generate-oauth-token_{context}"] += Generating a token for user authentication + +You must create a token in {PlatformNameShort}. +The token is used in an OpenShift secret for {PlatformNameShort} authentication. + +.Procedure +. Log in to your instance of {PlatformNameShort} as the `admin` user. +. Navigate to {MenuControllerUsers}. +. Select the `admin` user. +. Select the *Tokens* tab +. Click *Create Token*. +. Select your OAuth application. +In the *Scope* menu, select `Write`. +// + +// image::self-service-create-oauth-app.png[Create OAuth application] +. Click *Create Token* to generate the token. +. Save the new token. ++ +The token is used in an OpenShift secret that is fetched by the Helm chart. + diff --git a/downstream/modules/devtools/proc-self-service-install-helm-from-catalog.adoc b/downstream/modules/devtools/proc-self-service-install-helm-from-catalog.adoc new file mode 100644 index 000000000..ccfbd1012 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-install-helm-from-catalog.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-install-helm-from-catalog_{context}"] += Configuring the {SelfServiceShort} Helm chart from the OpenShift catalog + +.Prerequisites +. You have created a project for {SelfServiceShort} in OpenShift. +. You have created a plugin registry in your project. +. You have set up secrets for {PlatformNameShort} authentication and SCM authentication. + +.Procedure +. In a browser, navigate to your OpenShift project for {SelfServiceShort}. +. Click the *Helm* option in the OpenShift sidebar. +. In the *Helm* page, click *Create* and select *Helm Release*. +. Search for `AAP` in the Helm Charts filter, +and select the `AAP Technical Preview: Self-service automation` chart. +. In the modal dialog on the chart page, click *Create*. +. Select the *YAML view* in the *Create Helm Release* page. +. Locate the `clusterRouteBase` key in the YAML file and replace the placeholder value with the base URL of your OpenShift instance. ++ +The base URL is the URL portion of your OpenShift URL that follows `\https://console.openshift.console`, +for example `apps.example.com`: ++ +---- + redhat-developer-hub + global: + clusterRouterBase: apps.example.com +---- +. The Helm chart is set up for the Default {PlatformNameShort} organization. ++ +To update the Helm chart to use a different organization, +update the value for the `catalog.providers.rhaap.development.orgs` key from `default` to your {PlatformNameShort} organization name. +. Click *Create* to launch the deployment. + diff --git a/downstream/modules/devtools/proc-self-service-install-verify.adoc b/downstream/modules/devtools/proc-self-service-install-verify.adoc new file mode 100644 index 000000000..99413d296 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-install-verify.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-install-verify_{context}"] += Verifying the installation + +. In a browser, log in to your OpenShift instance. +. In the *Developer* view, +navigate to the *Topology* view for the namespace where you deployed the Helm chart. ++ +The deployment appears: the label on the icon is `D`. +The name of the deployment is `-backstage`, +for example ``. ++ +While it is deploying, the icon is light blue. +The color changes to dark blue when deployment is complete. + +image::self-service-verify-helm-install.png[Deployment on OpenShift console] diff --git a/downstream/modules/devtools/proc-self-service-ocp-project-setup.adoc b/downstream/modules/devtools/proc-self-service-ocp-project-setup.adoc new file mode 100644 index 000000000..16a6fa8d2 --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-ocp-project-setup.adoc @@ -0,0 +1,45 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-05 +:_mod-docs-content-type: PROCEDURE + +[id="self-service-ocp-project-setup_{context}"] += Setting up a project for {SelfServiceShort} in OpenShift + +. In a terminal, log in to OpenShift using your credentials: ++ +---- +oc login -u +---- ++ +For example: ++ +---- +$ oc login https://api..com:6443 -u kubeadmin +WARNING: Using insecure TLS client config. Setting this option is not supported! + +Console URL: https://api..com:6443/console +Authentication required for https://api..com:6443 (openshift) +Username: kubeadmin +Password: +Login successful. + +You have access to 22 projects, the list has been suppressed. You can list all projects with 'oc projects' + +Using project "default". +---- +. Create a new project: ++ +---- +$ oc new-project +---- +Example output: ++ +---- +Now using project "my-project" on server "https://openshift.example.com:6443". +---- +. Open your new project: ++ +---- +oc project +---- + diff --git a/downstream/modules/devtools/proc-self-service-setup-registry-image.adoc b/downstream/modules/devtools/proc-self-service-setup-registry-image.adoc new file mode 100644 index 000000000..b7bd61c8c --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-setup-registry-image.adoc @@ -0,0 +1,44 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-setup-registry-image_{context}"] += Setting up the plugin registry image + +Set up a registry in your OpenShift cluster to host the plug-ins and make them available for installation. + +.Procedure + +. Log in to your {OCPShort} instance with credentials to create a new application. +. Open your OpenShift project for {SelfServiceShort}. ++ +---- +$ oc project +---- +. Run the following commands to create a plug-in registry build in in your OpenShift project. ++ +---- +$ oc new-build httpd --name=plugin-registry --binary +$ oc start-build plugin-registry --from-dir=$DYNAMIC_PLUGIN_ROOT_DIR --wait +$ oc new-app --image-stream=plugin-registry +---- + +.Verification + +Verify that the plugin-registry was deployed successfully: + +. Open the *Topology* view in the *Developer* perspective for your project in the OpenShift web console. +. Click the plug-in registry to view the details pane. ++ +image::self-service-plugin-registry.png[Developer perspective] ++ +(1) Plug-in registry +. Click the *terminal* tab and log in to the container. +. In the terminal, run `ls` to confirm that the `.tar` files are in the plugin registry. ++ +---- +ansible-plugin-backstage-rhaap-x.y.z.tgz +ansible-plugin-backstage-rhaap-backend-x.y.z.tgz +ansible-plugin-scaffolder-backend-module-backstage-rhaap-x.y.z.tgz +---- ++ +The version numbers and file names can differ. + diff --git a/downstream/modules/devtools/proc-self-service-sign-in.adoc b/downstream/modules/devtools/proc-self-service-sign-in.adoc new file mode 100644 index 000000000..36a0990fa --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-sign-in.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-sign-in_{context}"] += Signing in to {SelfServiceShort} + +.Prerequisites +. You have configured an OAuth application in {PlatformNameShort} for {SelfServiceShort}. +. You have configured a user account in {PlatformNameShort}. + +.Procedure + +. In a browser, navigate to the URL for {SelfServiceShort} to open the sign-in page. ++ +image::self-service-sign-in-page.png[Self-service sign-in page] +. Click *Sign In*. +. The sign-in page for {PlatformNameShort} appears: ++ +image::rhaap-sign-in-page.png[{PlatformNameShort} sign-in page] +. Enter your {PlatformNameShort} credentials and click *Log in*. +. The {SelfServiceShort} UI opens. +. Click *Templates* to open a landing page where tiles are displayed, +representing templates. +When the page is populated with templates, the layout resembles the following screenshot: ++ +image::self-service-templates-view.png[Templates view] + diff --git a/downstream/modules/devtools/proc-self-service-view-configmap.adoc b/downstream/modules/devtools/proc-self-service-view-configmap.adoc new file mode 100644 index 000000000..d5d161e7f --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-view-configmap.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-view-configmap_{context}"] += Viewing the ConfigMaps + +. In a browser, open the project for your {SelfServiceShort} in your OpenShift instance. +. In the *Developer* view, +select *ConfigMaps* in the navigation pane. +. Select the `-backstage-app-config` ConfigMap, for example `my-aap-self-service-technical-preview-backstage-app-config`. +. Verify that the ConfigMap conforms with the values you updated in the Helm chart. +. Return to the list of ConfigMaps and select the `-dynamic-plugins` ConfigMap, +for example `my-aap-self-service-technical-preview-dynamic-plugins`. +. Verify that the ConfigMap conforms with the expected plugin values. + diff --git a/downstream/modules/devtools/proc-self-service-view-deployment-logs.adoc b/downstream/modules/devtools/proc-self-service-view-deployment-logs.adoc new file mode 100644 index 000000000..e023fb93e --- /dev/null +++ b/downstream/modules/devtools/proc-self-service-view-deployment-logs.adoc @@ -0,0 +1,45 @@ +:_mod-docs-content-type: PROCEDURE + +[id="self-service-view-deployment-logs_{context}"] += Viewing the deployment logs + +. In a browser, log in to your OpenShift instance. +. In the *Developer* view, +navigate to the *Topology* view for the namespace where you deployed the Helm chart. ++ +. The deployment appears: the label on the icon is `D`. ++ +The name of the deployment is `-backstage`, +for example ``. +. Click the icon representing the deployment. +. The *Details* pane for the deployment opens. +. Select the *Resources* tab. +. Click *View* logs for the deployment pod in the *Pods* section: ++ +image::self-service-view-deployment-logs.png[Deployment on OpenShift console] ++ +The *Pod details* page opens for the deployment pod. +. Select the *Logs* tab in the *Pod details* page. +. To view the install messages, +select the `install-dynamic-plugins` container from the *INIT CONTAINERS* section of the dropdown list of containers: ++ +image::self-service-view-install-messages.png[View install messages] ++ +The log stream displays the progress of the installation of the plug-ins from the plug-in registry. ++ +The log stream for successful installation of the plug-ins resembles the following output: ++ +---- + ======= Installing dynamic plugin http://plugin-registry:8080/ansible-backstage-plugin-catalog-backend-module-rhaap-dynamic-0.1.0.tgz + *=> Grabbing package archive through pm pack' + •=› Vertfying package Integrity + •*> Extracting package archtve /dynamtc-plugtns-root/anstble-backstage-plugtn-catalog-backend-nodule-rhaap-dynamic-0.1.0.tgz + •*› Removing package archive /dynamic-plugins-root/ansible-backstage-plugin-catalog-backend-module-rhaap-dynamic-0.1.0. tgz + -> Successfully installed dynamic plugin http://plugin-registry:8080/ansible-backstage-plugin-catalog-backend-module-rhaap-dynamic-0.1.0.tgz +---- +. Select the *Environment* tab in the *Pod details* page to view the environment variables for the containers. +If you set additional environment variables in your Helm chart, check that they are listed here. ++ +image::self-service-pod-env-variables.png[Pod environment variables] + + diff --git a/downstream/titles/self-service-install/master.adoc b/downstream/titles/self-service-install/master.adoc index 63e8f176e..03918dc41 100644 --- a/downstream/titles/self-service-install/master.adoc +++ b/downstream/titles/self-service-install/master.adoc @@ -11,8 +11,7 @@ include::attributes/attributes.adoc[] Thank you for your interest in {PlatformName}. {PlatformNameShort} is a commercial offering that helps teams manage complex multi-tier deployments by adding control, knowledge, and delegation to Ansible-powered environments. -This guide describes how to install {SelfService}. -This document has been updated to include information for the latest release of {PlatformNameShort}. +This guide describes how to install {SelfService} and connect it with an instance of {PlatformNameShort}. include::{Boilerplate}[] @@ -22,23 +21,11 @@ include::{Boilerplate}[] include::snippets/technology-preview.adoc[] ==== -// include::devtools/assembly-rhdh-intro.adoc[leveloffset=+1] - - -// Installation -// include::devtools/assembly-rhdh-install-ocp-helm.adoc[leveloffset=+1] -// -// Subscription warnings -// include::devtools/assembly-rhdh-subscription-warnings.adoc[leveloffset=+1] -// -// Upgrade -// include::devtools/assembly-rhdh-upgrade-ocp-helm.adoc[leveloffset=+1] -// include::devtools/assembly-rhdh-upgrade-ocp-operator.adoc[leveloffset=+1] -// -// Uninstall -// include::devtools/assembly-rhdh-uninstall-ocp-helm.adoc[leveloffset=+1] -// include::devtools/assembly-rhdh-uninstall-ocp-operator.adoc[leveloffset=+1] -// -// Telemetry -// include::devtools/assembly-rhdh-telemetry-capturing.adoc[leveloffset=+1] +include::devtools/assembly-self-service-about.adoc[leveloffset=+1] +include::devtools/assembly-self-service-installation-overview.adoc[leveloffset=+1] +include::devtools/assembly-self-service-preinstall-config.adoc[leveloffset=+1] +include::devtools/assembly-self-service-helm-install.adoc[leveloffset=+1] +include::devtools/assembly-self-service-view-deployment.adoc[leveloffset=+1] +include::devtools/assembly-self-service-accessing-deployment.adoc[leveloffset=+1] +include::devtools/assembly-self-service-telemetry-capture.adoc[leveloffset=+1]