Skip to content

Commit 01d15f7

Browse files
GitHub Actionsjmagak
GitHub Actions
authored and
jmagak
committed
Default configuration
1 parent d3e365f commit 01d15f7

File tree

6 files changed

+185
-0
lines changed

6 files changed

+185
-0
lines changed

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
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/ref-rhdh-default-configuration.adoc[leveloffset=+1]
9+
10+
include::modules/configuring/con-metadata-generation.adoc[leveloffset=+1]
11+
12+
include::modules/configuring/con-multi-objects.adoc[leveloffset=+1]
13+
14+
include::modules/configuring/con-default-base-urls.adoc[leveloffset=+1]

‎modules/configuring/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 sets the base URLs fields in the default `app-config` ConfigMap known as `backstage-appconfig-{CR_name}` created per Custom Resource, based on the Route parameters and the OpenShift cluster ingress domain.
7+
8+
The following are the rules governing the mentioned behavior:
9+
10+
* No change if the cluster is not OpenShift.
11+
* No change if `spec.application.route.enabled` is explicitly set to false in the CR.
12+
* The base URLs are set to `https://<spec.application.route.host>` if `spec.application.route.host` is set in the {product-custom-resource-type} CR.
13+
* The base URLs are set to `https://<spec.application.route.subdomain>.<cluster_ingress_domain>` if `spec.application.route.subdomain` is set in the {product-custom-resource-type} CR.
14+
* The base URLs are set to `https://backstage-<CR_name>-<namespace>.<cluster_ingress_domain>`, which is the domain set by default for the Route object created by the Operator.
15+
16+
The following `app-config` fields might be updated 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 still have the ability to override such defaults by providing custom `app-config` ConfigMap.
25+
====
26+

‎modules/configuring/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 objects at runtime to ensure your {product-custom-resource-type} application functions properly.
7+
8+
For all the objects, `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 named `mybackstage` creates Kubernetes Deployment resource called `backstage-mybackstage`.
9+
10+
The following is per-object generated metadata:
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/con-multi-objects.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-multi-objects"]
4+
= Multi objects
5+
6+
You can define and create multiple objects of the same type in a single YAML file when the object type is marked with `Multi=true`.
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 of adding code snip to `pvcs.yaml`
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/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 resources is defined at the Operator level and can be customized for a specific instance using the {backstage} Custom Resource (CR). This approach gives you 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 namespace of the Operator which is by default, `rhdh-operator` on OpenShift. This ConfigMap contains the YAML manifests that define the foundational structure of the {product-very-short} instance.
9+
10+
The default configuration defines the set of resources the Operator should create and manage when the user applies an empty {product-custom-resource-type} Custom Resource as shown in the following example:
11+
12+
[source,yaml]
13+
----
14+
`apiVersion: backstage.redhat.com/v1alpha4
15+
kind: Backstage
16+
metadata:
17+
name: my-rhdh-instance
18+
namespace: rhdh
19+
----
20+
21+
The following is the list of resources created in the specified {product-very-short}namespace by default based on the default configuration:
22+
23+
.Floating action button parameters
24+
|===
25+
| File Name | Resource GVK | Resource Name | Description
26+
27+
| `deployment.yaml`
28+
| apps/v1/Deployment
29+
| backstage-{cr-name}
30+
| (Mandatory) The main Backstage application deployment.
31+
32+
| `service.yaml`
33+
| v1/Service
34+
| backstage-{cr-name}
35+
| (Mandatory) The Backstage application service.
36+
37+
| `db-statefulset.yaml`
38+
| apps/v1/StatefulSet
39+
| backstage-psql-{cr-name}
40+
| The PostgreSQL database stateful set. Needed if `spec.enabledDb=true`.
41+
42+
| `db-service.yaml`
43+
| v1/Service
44+
| backstage-psql-{cr-name}
45+
| The PostgreSQL database service. Needed if `spec.enabledDb=true`.
46+
47+
| `db-secret.yaml`
48+
| v1/Secret
49+
| backstage-psql-{cr-name}
50+
| The PostgreSQL database credentials secret. Needed if `spec.enabledDb=true`.
51+
52+
| `route.yaml`
53+
| route.openshift.io/v1
54+
| backstage-{cr-name}
55+
| The OpenShift Route to expose Backstage externally. (Optional) Applied to Openshift only.
56+
57+
| `{my-app-config-file}`
58+
| v1/ConfigMap
59+
| backstage-config-{cr-name}
60+
| (Optional) Specifies one or more {product-custom-resource-type} `{my-app-config-file}` files.
61+
62+
| `configmap-files.yaml`
63+
| v1/ConfigMap
64+
| backstage-files-{cr-name}
65+
| (Optional) Specifies additional ConfigMaps to be mounted as files into {product-custom-resource-type} Pod.
66+
67+
| `configmap-envs.yaml`
68+
| v1/ConfigMap
69+
| backstage-envs-{cr-name}
70+
| (Optional) Specifies additional ConfigMaps to be exposed as environment variables into {product-custom-resource-type} Pod.
71+
72+
| `secret-files.yaml`
73+
| v1/Secret or list of v1/Secret
74+
| backstage-files-{cr-name}-{secret-name}
75+
| (Optional) Specifies additional Secrets to be mounted as files into {product-custom-resource-type} Pod.
76+
77+
| `secret-envs.yaml`
78+
| v1/Secret or list of v1/Secret
79+
| backstage-envs-{cr-name}
80+
| (Optional) Specifies additional Secrets to be exposed as environment variables into {product-custom-resource-type} Pod.
81+
82+
| `dynamic-plugins.yaml`
83+
| v1/ConfigMap
84+
| backstage-dynamic-plugins-{cr-name}
85+
| (Optional) Specifies dynamic plugins to be installed into {product-custom-resource-type} instance.
86+
87+
| `pvcs.yaml`
88+
| list of v1/PersistentVolumeClaim
89+
| backstage-{cr-name}-{pvc-name}
90+
| (Optional) The Persistent Volume Claim for PostgreSQL database.
91+
|===
92+
93+
[NOTE]
94+
====
95+
The {cr-name} is the name of the {product-custom-resource-type} Custom Resource, for example 'my-rhdh-instance' in the above example.
96+
It is not expected that the user manages these resources manually. The Operator takes care of creating, updating and deleting them as necessary.
97+
====

‎titles/configuring/master.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,6 @@ include::assemblies/assembly-configuring-default-secret-pvc-mounts.adoc[leveloff
3434

3535

3636
include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1]
37+
38+
39+
include::assemblies/assembly-rhdh-default-configuration.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)