diff --git a/modules/installation/proc-install-operator.adoc b/modules/installation/proc-install-operator.adoc index bae5470a1e..8b90a72013 100644 --- a/modules/installation/proc-install-operator.adoc +++ b/modules/installation/proc-install-operator.adoc @@ -15,7 +15,44 @@ Containers are available for the following CPU architectures: * You are logged in as an administrator on the {ocp-short} web console. * You have configured the appropriate roles and permissions within your project to create or access an application. For more information, see the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/building_applications/index#building-applications-overview[{ocp-brand-name} documentation on Building applications]. +* You have installed {ocp-brand-name} 4.17 or later. +.Procedure + +. In the navigation menu of the {ocp-short} console, click *Operators > OperatorHub*. +. In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card. +. On the *{product} Operator* page, read the information about the Operator and click *Install* to open the *Install Operator* page. +. After the Operator is successfully installed, provision your custom configuration: ++ +Before you create a {product-short} instance, you must create the required config map and Secret resources in your project. These include the `baseUrl` and service-to-service authentication secrets. ++ +For detailed steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration]. +. From the *Update channel* drop-down menu, select the update channel that you want to use, for example, *fast* or *fast-{product-version}*. ++ +[IMPORTANT] +==== +The `*fast* channel includes all of the updates available for a particular version. Any update might introduce unexpected changes in your {product} deployment. Check the release notes for details about any potentially breaking changes. + +The *fast-{product-version}* channel only provides z-stream updates, for example, updating from version {product-version}.1 to {product-version}.2. If you want to update the {product} y-version in the future, for example, updating from {product-version} to {product-version-next}, you must switch to the *fast-{product-version-next}* channel manually. +==== +. From the *Version* drop-down menu, select the version of the {product} Operator that you want to install. The default version is the latest version available in the selected channel. +. Select the Operator *Installation mode*. +//** If you select the *All namespaces on the cluster* option, the Operator is installed in all namespaces. This option is useful for Operators that manage cluster-wide resources. +//** If you select the *Specific namespace on the cluster* option, the Operator is installed in a specific namespace. This option is useful for Operators that manage resources in a specific namespace. ++ +[NOTE] +==== +The *All namespaces on the cluster (default)* option is selected by default. The *Specific namespace on the cluster* option is not currently supported. +==== +. In the *Installed Namespace* field, do one of the following actions: ++ +** Select *Operator recommended Namespace* to create and use the *rhdh-operator* namespace. This option is selected by default. +** Select *Select a Namespace* to use an alternative namespace. +*** From the *Select Project* drop-down menu, do one of the following actions: +**** Select an existing project. +**** Select *Create Project* to create a new project for the Operator. +***** On the *Create Project* dialog, enter text into the required fields and click *Create*. ++ [IMPORTANT] ==== For enhanced security, better control over the Operator lifecycle, and preventing potential privilege escalation, install the {product} Operator in a dedicated default `rhdh-operator` namespace. You can restrict other users' access to the Operator resources through role bindings or cluster role bindings. diff --git a/modules/installation/proc-install-rhdh-ocp-operator.adoc b/modules/installation/proc-install-rhdh-ocp-operator.adoc index 54f6bd196e..56e24b8c1a 100644 --- a/modules/installation/proc-install-rhdh-ocp-operator.adoc +++ b/modules/installation/proc-install-rhdh-ocp-operator.adoc @@ -7,21 +7,72 @@ As a developer, you can deploy a {product} instance on {ocp-short} by using the *Developer Catalog* in the {ocp-brand-name} web console. This deployment method uses the {product} Operator. .Prerequisites - +* You have set the `baseUrl` in your `{my-app-config-file}` to match the external URL of your {product-short} instance. Without it, frontend and backend services cannot communicate, and features might not work as expected. * xref:proc-install-operator_{context}[An {ocp-short} administrator has installed the {product} Operator]. * xref:{configuring-book-url}#provisioning-your-custom-configuration[You have provisioned your custom config maps and secrets in your `_<{my-product-namespace}>_` project]. * xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[You have authored your {product-custom-resource-type} custom resource]. .Procedure -. In the {ocp-short} web console, select your `_<{my-product-namespace}>_` project. - -. From the *Developer* perspective on the {ocp-short} web console, click *+Add*. +. In the {ocp-short} web console, select your `_<{my_product_namespace}>_` project, then click *Add*. . From the *Developer Catalog* panel, click *Operator Backed*. . In the *Filter by keyword* box, enter _{product-short}_ and click the *{product}* card. +. Provision your custom configuration using the following template: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: app-config-rhdh +data: + "app-config-rhdh.yaml": | + app: + title: {product} + baseUrl: {my-product-url} + backend: + auth: + externalAccess: + - type: legacy + options: + subject: legacy-default-config + secret: "${BACKEND_SECRET}" + baseUrl: {my-product-url} + cors: + origin: {my-product-url} +---- ++ +Use a config map named `app-config-rhdh` to provide your `app-config.yaml` file, and a Secret for service-to-service authentication (such as `BACKEND_SECRET`). ++ +To create and apply these configuration resources, follow the steps in xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration] for the full procedure. ++ +[NOTE] +==== +The `app-config-rhdh` config map must include your customized `app-config.yaml` file. This config map is mounted into the {product-short} container at runtime. +==== + +. Create a secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value, as shown in the following example: ++ +-- +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: {my-product-secrets} +stringData: + # TODO: Add the necessary auth secrets for service-to-service auth setup + BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret +---- +-- ++ +[NOTE] +==== +Ensure that your secret includes `BACKEND_SECRET`, used for service-to-service authentication. For structure and provisioning steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration]. +==== . Click *Create*. . xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[Add your {product-custom-resource-type} custom resource content]. -. On the *Create Backstage* page, click *Create* +. On the *Create Backstage* page, click *Create*. .Verification diff --git a/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc b/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc index df951f9169..ebddb9701c 100644 --- a/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc +++ b/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc @@ -17,7 +17,28 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product . In the *Filter by keyword* box, enter {product-short} and click the *{product}* card. . From the {product} page, click *Create*. . From your cluster, copy the {ocp-short} router host (for example: `apps..com`). -. Select the radio button to configure the {product-short} instance with either the form view or YAML view. The *Form view* is selected by default. +. Select the radio button to configure the {product-short} instance with either the form view or YAML view. ++ +[IMPORTANT] +==== +Before deploying {product-short} using the Helm chart, you must define custom configuration settings such as the public `baseUrl` for your instance. Without setting `baseUrl`, the application cannot function correctly. You can define this configuration either through the *Form view* or the *YAML view* in the Helm install wizard. + +To configure the `baseUrl`, set the following values in your Helm configuration: +[source,yaml] +---- +global: + app: + baseUrl: https:// + backend: + baseUrl: https:// + cors: + origin: https:// +---- +You can also define additional secrets, plugins, and advanced configuration in your `values.yaml` file. For full instructions, see: +xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration]. +==== ++ +The *Form view* is selected by default. + -- .. Using *Form view* diff --git a/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc b/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc index 995d878094..0f3e392f99 100644 --- a/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc +++ b/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc @@ -13,12 +13,83 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product .Procedure -. In the *Administrator* perspective of the {ocp-short} web console, click *Operators > OperatorHub*. -. In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card. +. In the {ocp-short} web console menu, go to *Operators > OperatorHub*. +. In the *Filter by keyword* field, enter {product-short} and click the *{product} Operator* card. . On the *{product} Operator* page, click *Install*. -. In the {ocp-short} console, navigate to *Installed Operators* and select *{product} Operator*. -. From the {product-short} Operator page, click *Create New Instance* and specify the name and namespace where you want to deploy {product-short}. -. Configure the required settings such as Git integration, secret management, and user permissions. +. After the installation completes, navigate to *Installed Operators* and select *Red Hat {product-short} Operator*. +. Provision your custom configuration: ++ +-- +[source,yaml,subs="attributes+"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: app-config-rhdh +data: + "app-config-rhdh.yaml": | + app: + title: {product} + baseUrl: {my-product-url} + backend: + auth: + externalAccess: + - type: legacy + options: + subject: legacy-default-config + secret: "${BACKEND_SECRET}" + baseUrl: {my-product-url} + cors: + origin: {my-product-url} +---- +-- ++ +You must create a config map named `app-config-rhdh` and a Kubernetes Secret containing the `BACKEND_SECRET`. These resources are used by the {product-short} instance for authentication and application settings. ++ +For further steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration]. +. Create a config map named `app-config-rhdh` that includes your `{my-app-config-file}` as shown: ++ +-- +[source,yaml,subs="attributes+"] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: app-config-rhdh +data: + "app-config-rhdh.yaml": | + app: + title: {product} + baseUrl: {my-product-url} + backend: + auth: + externalAccess: + - type: legacy + options: + subject: legacy-default-config + secret: "${BACKEND_SECRET}" + baseUrl: {my-product-url} + cors: + origin: {my-product-url} +---- +-- +. Create a secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value: ++ +-- +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: {my-product-secrets} +stringData: + # TODO: Add the necessary auth secrets for service-to-service auth setup + BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret +---- +-- +. Return to the *{product-short} Operator* page and click *Create New Instance*. +. Specify the name and target namespace for the {product-short} deployment. +. Configure required options such as Git integration, secrets, and user permissions. . Review the configuration, select deployment options, and click *Create*. .Verification diff --git a/titles/install-rhdh-ocp/master.adoc b/titles/install-rhdh-ocp/master.adoc index 929755a1ed..eef9c0f785 100644 --- a/titles/install-rhdh-ocp/master.adoc +++ b/titles/install-rhdh-ocp/master.adoc @@ -27,6 +27,12 @@ The {product} Helm chart:: * Requires manual installation and management -- +[IMPORTANT] +==== +You must set the `baseUrl` in `{my-app-config-file}` to match the external URL of your {product-short} instance (for example, `https://rhdh.example.com`). +This value is required for the {product} to function correctly. If it is not set, frontend and backend services cannot communicate properly, and features may not work as expected. +==== + Use the installation method that best meets your needs and preferences. .Additional resources diff --git a/titles/install-rhdh-osd-gcp/master.adoc b/titles/install-rhdh-osd-gcp/master.adoc index 975f2138f0..8f3f92e763 100644 --- a/titles/install-rhdh-osd-gcp/master.adoc +++ b/titles/install-rhdh-osd-gcp/master.adoc @@ -12,6 +12,11 @@ You can install {product-short} on {osd-short} on {gcp-brand-name} ({gcp-short}) * The {product} Operator * The {product} Helm chart +[IMPORTANT] +==== +You must set the `baseUrl` in `{my-app-config-file}` to match the external URL of your {product-short} instance. This value is required for the {product} to function correctly. If it is not set, frontend and backend services cannot communicate properly, and features may not work as expected. +==== + // Operator procedure include::modules/installation/proc-install-rhdh-osd-gcp-operator.adoc[leveloffset=+1]