Skip to content

Commit 8ba4468

Browse files
jmagakjmagak
authored
Default configuration (#1398)
1 parent 4674de0 commit 8ba4468

10 files changed

+212
-25
lines changed

‎assemblies/assembly-configuring-default-secret-pvc-mounts.adoc‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎assemblies/assembly-rhdh-default-configuration.adoc‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-rhdh-default-configuration_{context}"]
4+
= {product} default configuration
5+
6+
You can deploy a standard {product} ({product-very-short}) instance, understand the structure, and tailor {product-very-short} instance to meet your needs.
7+
8+
include::modules/configuring-external-databases/ref-rhdh-default-configuration.adoc[leveloffset=+1]
9+
10+
include::modules/configuring-external-databases/con-automated-operator-features.adoc[leveloffset=+1]
11+
12+
include::modules/configuring-external-databases/con-metadata-generation.adoc[leveloffset=+2]
13+
14+
include::modules/configuring-external-databases/con-multiple-resources.adoc[leveloffset=+2]
15+
16+
include::modules/configuring-external-databases/con-default-base-urls.adoc[leveloffset=+2]
17+
18+
include::modules/configuring-external-databases/con-configuring-default-secret-pvc-mounts.adoc[leveloffset=+1]
19+
20+
include::modules/configuring-external-databases/proc-configuring-mount-paths.adoc[leveloffset=+2]
21+
22+
include::modules/configuring-external-databases/proc-mounting-to-specific-containers.adoc[leveloffset=+2]

‎modules/configuring-external-databases/con-automated-operator-features.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-automated-operator-features_{context}"]
4+
= Automated Operator features
5+
6+
You can use the Operator to automate several key processes to effectively configure your {product-custom-resource-type} application.

‎modules/configuring-external-databases/con-configuring-default-secret-pvc-mounts.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-configuring-default-secret-pvc-mounts_{context}"]
4+
= Configuring mounts for default Secrets and Persistent Volume Claims (PVCs)
5+
6+
You can use annotations to configure mount paths and specify containers for Secrets and Persistent Volume Claims (PVCs) that are attached to the Operator default resources in your {product} deployment. This method is specific for default objects, for instance, the {product-custom-resource-type} Deployment that the Operator manages.

‎modules/configuring-external-databases/con-default-base-urls.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-default-base-urls"]
4+
= Default base URLs
5+
6+
The Operator automatically sets the base URLs for your {product-custom-resource-type} application in the default `app-config` ConfigMap known as `backstage-appconfig-{CR_name}`. The Operator does so based on your Route parameters and the OpenShift cluster ingress domain.
7+
8+
The Operator follows these rules to set the base URLs for your application:
9+
10+
* If the cluster is not OpenShift, the Operator makes no changes.
11+
* If you explicitly set the `spec.application.route.enabled` field in your Custom Resource (CR) to `false`, no changes are made.
12+
* If you define `spec.application.route.host` in the {product-custom-resource-type} CR, the base URLs are set to `https://<spec.application.route.host>`.
13+
* If you specify the `spec.application.route.subdomain` in the {product-custom-resource-type} CR, the base URLs are set to `https://<spec.application.route.subdomain>.<cluster_ingress_domain>`.
14+
* If no custom host or subdomain is provided, the Operator sets the base URLs to `https://backstage-{cr_name}-<namespace>.<cluster_ingress_domain>`, which is the default domain for the created _Route_ resource.
15+
16+
The Operator updates the following base URLs in the default `app-config` ConfigMap:
17+
18+
* `app.baseUrl`
19+
* `backend.baseUrl`
20+
* `backend.cors.origin`
21+
22+
[NOTE]
23+
====
24+
You can perform these actions on a best-effort basis and only on OpenShift. During an error or on non-OpenShift clusters, you can still override these defaults by providing a custom `app-config` ConfigMap.
25+
====
26+

‎modules/configuring-external-databases/con-metadata-generation.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-metadata-generation"]
4+
= Metadata generation
5+
6+
The Operator automatically generates specific metadata values for all default resources at runtime to ensure your {product-custom-resource-type} application functions properly.
7+
8+
For all the default resources, `metadata.name` is generated according to the rules defined in the _Default Configuration files_, particularly the _Resource name_ column. For example, {product-custom-resource-type} Custom Resource (CR) named `mybackstage` creates Kubernetes Deployment resource called `backstage-mybackstage`.
9+
10+
The following metadata is generated for each resource:
11+
12+
* `deployment.yaml`
13+
** `spec.selector.matchLabels[rhdh.redhat.com/app] = backstage-{cr-name}`
14+
** `spec.template.metadata.labels[rhdh.redhat.com/app] = backstage-{cr-name}`
15+
* `service.yaml`
16+
** `spec.selector[rhdh.redhat.com/app] = backstage-{cr-name}`
17+
* `db-statefulset.yaml`
18+
** `spec.selector.matchLabels[rhdh.redhat.com/app] = backstage-psql-{cr-name}`
19+
** `spec.template.metadata.labels[rhdh.redhat.com/app] = backstage-psql-{cr-name}`
20+
* `db-service.yaml`
21+
** `spec.selector[rhdh.redhat.com/app] = backstage-psql-{cr-name}`

‎modules/configuring-external-databases/con-multiple-resources.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-multiple-resources"]
4+
= Multiple resources
5+
6+
You can define and create multiple resources of the same type in a single YAML file. This is applicable to any resource type that is a `list` in the resource table. To define multiple resources, use the `---` delimiter to separate each resource definition.
7+
8+
For example, adding the following code snip to `pvcs.yaml` creates two PersistentVolumeClaims (PVCs) called `backstage-{cr-name}-myclaim1` and `backstage-{cr-name}-myclaim2` and mounts them to {product-custom-resource-type} container accordingly.
9+
10+
.Example creating multiple PVCs
11+
[source,yaml]
12+
----
13+
apiVersion: v1
14+
kind: PersistentVolumeClaim
15+
metadata:
16+
name: myclaim1
17+
...
18+
---
19+
apiVersion: v1
20+
kind: PersistentVolumeClaim
21+
metadata:
22+
name: myclaim2
23+
...
24+
----

‎modules/configuring-external-databases/proc-configuring-mount-paths.adoc‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,24 @@
11
:_mod-docs-content-type: PROCEDURE
22
[id="proc-configuring-mount-paths_{context}"]
3-
= Configuring mount paths for Secrets and PVCs
3+
= Configuring mount paths for default Secrets and Persistent Volume Claims (PVCs)
44

5-
By default, the mount path is the working directory of the {product-short} container. If you do not define the mount path, it defaults to `/opt/app-root/src`.
5+
By default, the mount path is `/opt/app-root/src`. To specify a different path, add the `rhdh.redhat.com/mount-path` annotation to your resource.
66

77
.Procedure
88

99
. To specify a PVC mount path, add the `rhdh.redhat.com/mount-path` annotation to your configuration file as shown in the following example:
1010
+
11-
.Example specifying where the PVC mounts
11+
.Example specifying the PVC mount path
1212
[source,yaml,subs="+attributes,+quotes"]
1313
----
1414
apiVersion: v1
1515
kind: PersistentVolumeClaim
1616
metadata:
17-
name: _<my_claim>_
17+
name: _<my_claim>_ # Specifies the PVC to mount
1818
annotations:
19+
# Specifies which mount path the PVC mounts to (in this case, `/mount/path/from/annotation` directory)
1920
rhdh.redhat.com/mount-path: /mount/path/from/annotation
2021
----
21-
where:
22-
23-
`rhdh.redhat.com/mount-path`:: Specifies which mount path the PVC mounts to (in this case, `/mount/path/from/annotation` directory).
24-
_<my_claim>_:: Specifies the PVC to mount.
2522

2623
. To specify a Secret mount path, add the `rhdh.redhat.com/mount-path` annotation to your configuration file as shown in the following example:
2724
+
@@ -31,10 +28,7 @@ _<my_claim>_:: Specifies the PVC to mount.
3128
apiVersion: v1
3229
kind: Secret
3330
metadata:
34-
name: _<my_secret>_
31+
name: _<my_secret>_ # Specifies the Secret name
3532
annotations:
3633
rhdh.redhat.com/mount-path: /mount/path/from/annotation
3734
----
38-
where:
39-
40-
_<my_secret>_:: Specifies the Secret name.

‎modules/configuring-external-databases/ref-rhdh-default-configuration.adoc‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="rhdh-default-configuration"]
4+
= {product} default configuration guide
5+
6+
The {product} ({product-very-short}) Operator creates a set of Kubernetes resources to deploy and manage a {backstage} instance. The default configuration for these default resources is defined at the Operator level and can be customized for a specific instance using the {backstage} Custom Resource (CR). This approach provides a clear starting point while offering flexibility to tailor each deployment.
7+
8+
The default configuration is stored in a ConfigMap named `rhdh-default-config` located in the `rhdh-operator` namespace on OpenShift. This ConfigMap contains the YAML manifests that define the foundational structure of the {product-very-short} instance.
9+
10+
You can create a basic {product-very-short} instance by applying an empty {product-custom-resource-type} Custom Resource as follows:
11+
12+
.Example creating a {product-very-short} instance
13+
[source,yaml]
14+
----
15+
apiVersion: backstage.redhat.com/v1alpha4
16+
kind: Backstage
17+
metadata:
18+
name: my-rhdh-instance
19+
namespace: rhdh
20+
----
21+
22+
The Operator automatically creates the following resources in the specified {product-very-short} namespace by default based on the default configuration:
23+
24+
.Floating action button parameters
25+
|===
26+
| File Name | Resource GVK | Resource Name | Description
27+
28+
| `deployment.yaml`
29+
| `apps/v1/Deployment`
30+
| `backstage-{cr-name}`
31+
| (Mandatory) The main Backstage application deployment.
32+
33+
| `service.yaml`
34+
| `v1/Service`
35+
| `backstage-{cr-name}`
36+
| (Mandatory) The Backstage application service.
37+
38+
| `db-statefulset.yaml`
39+
| `apps/v1/StatefulSet`
40+
| `backstage-psql-{cr-name}`
41+
| The PostgreSQL database stateful set. Needed if `spec.enabledDb=true`.
42+
43+
| `db-service.yaml`
44+
| `v1/Service`
45+
| `backstage-psql-{cr-name}`
46+
| The PostgreSQL database service. Needed if `spec.enabledDb=true`.
47+
48+
| `db-secret.yaml`
49+
| `v1/Secret`
50+
| `backstage-psql-{cr-name}`
51+
| The PostgreSQL database credentials secret. Needed if `spec.enabledDb=true`.
52+
53+
| `route.yaml`
54+
| `route.openshift.io/v1`
55+
| `backstage-{cr-name}`
56+
| The OpenShift Route to expose Backstage externally. (Optional) Applied to Openshift only.
57+
58+
| `{my-app-config-file}`
59+
| `v1/ConfigMap`
60+
| `backstage-config-{cr-name}`
61+
| (Optional) Specifies one or more {product-custom-resource-type} `{my-app-config-file}` files.
62+
63+
| `configmap-files.yaml`
64+
| `v1/ConfigMap`
65+
| `backstage-files-{cr-name}`
66+
| (Optional) Specifies additional ConfigMaps to be mounted as files into {product-custom-resource-type} Pod.
67+
68+
| `configmap-envs.yaml`
69+
| `v1/ConfigMap`
70+
| `backstage-envs-{cr-name}`
71+
| (Optional) Specifies additional ConfigMaps to be exposed as environment variables into {product-custom-resource-type} Pod.
72+
73+
| `secret-files.yaml`
74+
| `v1/Secret` or list of `v1/Secret`
75+
| `backstage-files-{cr-name}-{secret-name}`
76+
| (Optional) Specifies additional Secrets to be mounted as files into {product-custom-resource-type} Pod.
77+
78+
| `secret-envs.yaml`
79+
| `v1/Secret` or list of `v1/Secret`
80+
| `backstage-envs-{cr-name}`
81+
| (Optional) Specifies additional Secrets to be exposed as environment variables into {product-custom-resource-type} Pod.
82+
83+
| `dynamic-plugins.yaml`
84+
| `v1/ConfigMap`
85+
| `backstage-dynamic-plugins-{cr-name}`
86+
| (Optional) Specifies dynamic plugins to be installed into {product-custom-resource-type} instance.
87+
88+
| `pvcs.yaml`
89+
| list of `v1/PersistentVolumeClaim`
90+
| `backstage-{cr-name}-{pvc-name}`
91+
| (Optional) The Persistent Volume Claim for PostgreSQL database.
92+
|===
93+
94+
[NOTE]
95+
====
96+
`{cr-name}` is the name of the {product-custom-resource-type} Custom Resource, for example 'my-rhdh-instance' in the above example.
97+
====

‎titles/configuring/master.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ include::artifacts/attributes.adoc[]
2020
include::assemblies/assembly-provisioning-a-custom-configuration.adoc[leveloffset=+1]
2121

2222

23+
include::assemblies/assembly-rhdh-default-configuration.adoc[leveloffset=+1]
24+
25+
2326
include::assemblies/assembly-configuring-external-postgresql-databases.adoc[leveloffset=+1]
2427

2528

@@ -38,7 +41,4 @@ include::modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kube
3841
include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.adoc[ leveloffset=+1]
3942

4043

41-
include::assemblies/assembly-configuring-default-secret-pvc-mounts.adoc[leveloffset=+1]
42-
43-
44-
include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]
44+
include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)