Skip to content

Commit 3e29504

Browse files
jmagakjmagak
authored
Update the config in installation (#1296)
1 parent 16914d8 commit 3e29504

File tree

6 files changed

+202
-11
lines changed

6 files changed

+202
-11
lines changed

‎modules/installation/proc-install-operator.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,44 @@ Containers are available for the following CPU architectures:
1515

1616
* You are logged in as an administrator on the {ocp-short} web console.
1717
* 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].
18+
* You have installed {ocp-brand-name} 4.17 or later.
1819
20+
.Procedure
21+
22+
. In the navigation menu of the {ocp-short} console, click *Operators > OperatorHub*.
23+
. In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card.
24+
. On the *{product} Operator* page, read the information about the Operator and click *Install* to open the *Install Operator* page.
25+
. After the Operator is successfully installed, provision your custom configuration:
26+
+
27+
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.
28+
+
29+
For detailed steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
30+
. From the *Update channel* drop-down menu, select the update channel that you want to use, for example, *fast* or *fast-{product-version}*.
31+
+
32+
[IMPORTANT]
33+
====
34+
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.
35+
36+
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.
37+
====
38+
. 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.
39+
. Select the Operator *Installation mode*.
40+
//** 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.
41+
//** 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.
42+
+
43+
[NOTE]
44+
====
45+
The *All namespaces on the cluster (default)* option is selected by default. The *Specific namespace on the cluster* option is not currently supported.
46+
====
47+
. In the *Installed Namespace* field, do one of the following actions:
48+
+
49+
** Select *Operator recommended Namespace* to create and use the *rhdh-operator* namespace. This option is selected by default.
50+
** Select *Select a Namespace* to use an alternative namespace.
51+
*** From the *Select Project* drop-down menu, do one of the following actions:
52+
**** Select an existing project.
53+
**** Select *Create Project* to create a new project for the Operator.
54+
***** On the *Create Project* dialog, enter text into the required fields and click *Create*.
55+
+
1956
[IMPORTANT]
2057
====
2158
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.

‎modules/installation/proc-install-rhdh-ocp-operator.adoc‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,72 @@
77
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.
88

99
.Prerequisites
10-
10+
* 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.
1111
* xref:proc-install-operator_{context}[An {ocp-short} administrator has installed the {product} Operator].
1212
* xref:{configuring-book-url}#provisioning-your-custom-configuration[You have provisioned your custom config maps and secrets in your `_<{my-product-namespace}>_` project].
1313
* xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[You have authored your {product-custom-resource-type} custom resource].
1414

1515
.Procedure
1616

17-
. In the {ocp-short} web console, select your `_<{my-product-namespace}>_` project.
18-
19-
. From the *Developer* perspective on the {ocp-short} web console, click *+Add*.
17+
. In the {ocp-short} web console, select your `_<{my_product_namespace}>_` project, then click *Add*.
2018
. From the *Developer Catalog* panel, click *Operator Backed*.
2119
. In the *Filter by keyword* box, enter _{product-short}_ and click the *{product}* card.
20+
. Provision your custom configuration using the following template:
21+
+
22+
[source,yaml,subs="attributes+"]
23+
----
24+
apiVersion: v1
25+
kind: ConfigMap
26+
metadata:
27+
name: app-config-rhdh
28+
data:
29+
"app-config-rhdh.yaml": |
30+
app:
31+
title: {product}
32+
baseUrl: {my-product-url}
33+
backend:
34+
auth:
35+
externalAccess:
36+
- type: legacy
37+
options:
38+
subject: legacy-default-config
39+
secret: "${BACKEND_SECRET}"
40+
baseUrl: {my-product-url}
41+
cors:
42+
origin: {my-product-url}
43+
----
44+
+
45+
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`).
46+
+
47+
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.
48+
+
49+
[NOTE]
50+
====
51+
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.
52+
====
53+
54+
. 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:
55+
+
56+
--
57+
[source,yaml,subs="+attributes,+quotes"]
58+
----
59+
apiVersion: v1
60+
kind: Secret
61+
metadata:
62+
name: {my-product-secrets}
63+
stringData:
64+
# TODO: Add the necessary auth secrets for service-to-service auth setup
65+
BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret
66+
----
67+
--
68+
+
69+
[NOTE]
70+
====
71+
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].
72+
====
2273
. Click *Create*.
2374
. xref:{configuring-book-url}#using-the-operator-to-run-rhdh-with-your-custom-configuration[Add your {product-custom-resource-type} custom resource content].
24-
. On the *Create Backstage* page, click *Create*
75+
. On the *Create Backstage* page, click *Create*.
2576

2677
.Verification
2778

‎modules/installation/proc-install-rhdh-osd-gcp-helm.adoc‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,28 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product
1717
. In the *Filter by keyword* box, enter {product-short} and click the *{product}* card.
1818
. From the {product} page, click *Create*.
1919
. From your cluster, copy the {ocp-short} router host (for example: `apps.<clusterName>.com`).
20-
. 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.
20+
. Select the radio button to configure the {product-short} instance with either the form view or YAML view.
21+
+
22+
[IMPORTANT]
23+
====
24+
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.
25+
26+
To configure the `baseUrl`, set the following values in your Helm configuration:
27+
[source,yaml]
28+
----
29+
global:
30+
app:
31+
baseUrl: https://<your-developer-hub-url>
32+
backend:
33+
baseUrl: https://<your-developer-hub-url>
34+
cors:
35+
origin: https://<your-developer-hub-url>
36+
----
37+
You can also define additional secrets, plugins, and advanced configuration in your `values.yaml` file. For full instructions, see:
38+
xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
39+
====
40+
+
41+
The *Form view* is selected by default.
2142
+
2243
--
2344
.. Using *Form view*

‎modules/installation/proc-install-rhdh-osd-gcp-operator.adoc‎

Lines changed: 76 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,83 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product
1313

1414
.Procedure
1515

16-
. In the *Administrator* perspective of the {ocp-short} web console, click *Operators > OperatorHub*.
17-
. In the *Filter by keyword* box, enter {product-short} and click the *{product} Operator* card.
16+
. In the {ocp-short} web console menu, go to *Operators > OperatorHub*.
17+
. In the *Filter by keyword* field, enter {product-short} and click the *{product} Operator* card.
1818
. On the *{product} Operator* page, click *Install*.
19-
. In the {ocp-short} console, navigate to *Installed Operators* and select *{product} Operator*.
20-
. From the {product-short} Operator page, click *Create New Instance* and specify the name and namespace where you want to deploy {product-short}.
21-
. Configure the required settings such as Git integration, secret management, and user permissions.
19+
. After the installation completes, navigate to *Installed Operators* and select *Red Hat {product-short} Operator*.
20+
. Provision your custom configuration:
21+
+
22+
--
23+
[source,yaml,subs="attributes+"]
24+
----
25+
apiVersion: v1
26+
kind: ConfigMap
27+
metadata:
28+
name: app-config-rhdh
29+
data:
30+
"app-config-rhdh.yaml": |
31+
app:
32+
title: {product}
33+
baseUrl: {my-product-url}
34+
backend:
35+
auth:
36+
externalAccess:
37+
- type: legacy
38+
options:
39+
subject: legacy-default-config
40+
secret: "${BACKEND_SECRET}"
41+
baseUrl: {my-product-url}
42+
cors:
43+
origin: {my-product-url}
44+
----
45+
--
46+
+
47+
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.
48+
+
49+
For further steps, see xref:{configuring-book-url}#provisioning-and-using-your-custom-configuration[Provisioning your custom {product} configuration].
50+
. Create a config map named `app-config-rhdh` that includes your `{my-app-config-file}` as shown:
51+
+
52+
--
53+
[source,yaml,subs="attributes+"]
54+
----
55+
apiVersion: v1
56+
kind: ConfigMap
57+
metadata:
58+
name: app-config-rhdh
59+
data:
60+
"app-config-rhdh.yaml": |
61+
app:
62+
title: {product}
63+
baseUrl: {my-product-url}
64+
backend:
65+
auth:
66+
externalAccess:
67+
- type: legacy
68+
options:
69+
subject: legacy-default-config
70+
secret: "${BACKEND_SECRET}"
71+
baseUrl: {my-product-url}
72+
cors:
73+
origin: {my-product-url}
74+
----
75+
--
76+
. Create a secret named `{my-product-secrets}` and add a key named `BACKEND_SECRET` with a `Base64-encoded` string as value:
77+
+
78+
--
79+
[source,yaml,subs="+attributes,+quotes"]
80+
----
81+
apiVersion: v1
82+
kind: Secret
83+
metadata:
84+
name: {my-product-secrets}
85+
stringData:
86+
# TODO: Add the necessary auth secrets for service-to-service auth setup
87+
BACKEND_SECRET: "xxx" # Replace with your `Base64-encoded` secret
88+
----
89+
--
90+
. Return to the *{product-short} Operator* page and click *Create New Instance*.
91+
. Specify the name and target namespace for the {product-short} deployment.
92+
. Configure required options such as Git integration, secrets, and user permissions.
2293
. Review the configuration, select deployment options, and click *Create*.
2394

2495
.Verification

‎titles/install-rhdh-ocp/master.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@ The {product} Helm chart::
2727
* Requires manual installation and management
2828
--
2929

30+
[IMPORTANT]
31+
====
32+
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`).
33+
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.
34+
====
35+
3036
Use the installation method that best meets your needs and preferences.
3137

3238
.Additional resources

‎titles/install-rhdh-osd-gcp/master.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ You can install {product-short} on {osd-short} on {gcp-brand-name} ({gcp-short})
1212
* The {product} Operator
1313
* The {product} Helm chart
1414
15+
[IMPORTANT]
16+
====
17+
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.
18+
====
19+
1520
// Operator procedure
1621
include::modules/installation/proc-install-rhdh-osd-gcp-operator.adoc[leveloffset=+1]
1722

0 commit comments

Comments
 (0)