chore: update defaults, documentation and update errors to be more ve…

…rbose
janus-idp · Jan 22, 2024 · c53489e · c53489e
1 parent a7fa12f
commit c53489e
Show file tree

Hide file tree

Showing 6 changed files with 49 additions and 56 deletions.
diff --git a/charts/backstage/README.md b/charts/backstage/README.md
@@ -70,15 +70,6 @@ helm repo add janus-idp https://janus-idp.github.io/helm-backstage
 
 Once the chart has been added, install this chart. However before doing so, please review the default `values.yaml` and adjust as needed.
 
-- To get proper connection between frontend and backend of Backstage please update the `apps.example.com` to match your cluster host:
-
-   ```yaml
-   global:
-     clusterRouterBase: apps.example.com
-   ```
-
-   > Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file
-
 - If your cluster doesn't provide PVCs, you should disable PostgreSQL persistence via:
 
    ```yaml
@@ -132,12 +123,12 @@ Kubernetes: `>= 1.19.0-0`
 | global.auth.backend | Backend service to service authentication <br /> Ref: https://backstage.io/docs/auth/service-to-service-auth/ | object | `{"enabled":true,"existingSecret":"","value":""}` |
 | global.auth.backend.enabled | Enable backend service to service authentication, unless configured otherwise it generates a secret value | bool | `true` |
 | global.auth.backend.existingSecret | Instead of generating a secret value, refer to existing secret | string | `""` |
-| global.auth.backend.value | Instead of generating a secret value, use fo;lowing value | string | `""` |
-| global.clusterRouterBase | Shorthand for users who do not want to specify a custom HOSTNAME. Used ONLY with the DEFAULT upstream.backstage.appConfig value and with OCP Route enabled. | string | `"apps.example.com"` |
+| global.auth.backend.value | Instead of generating a secret value, use the following value | string | `""` |
+| global.clusterRouterBase | Shorthand for users who do not want to specify a custom HOSTNAME. Used ONLY with the DEFAULT upstream.backstage.appConfig value and with OCP Route enabled. | string | `""` |
 | global.dynamic.includes | Array of YAML files listing dynamic plugins to include with those listed in the `plugins` field. Relative paths are resolved from the working directory of the initContainer that will install the plugins (`/opt/app-root/src`). | list | `["dynamic-plugins.default.yaml"]` |
 | global.dynamic.includes[0] | List of dynamic plugins included inside the `janus-idp/backstage-showcase` container image, some of which are disabled by default. This file ONLY works with the `janus-idp/backstage-showcase` container image. | string | `"dynamic-plugins.default.yaml"` |
 | global.dynamic.plugins | List of dynamic plugins, possibly overriding the plugins listed in `includes` files. Every item defines the plugin `package` as a [NPM package spec](https://docs.npmjs.com/cli/v10/using-npm/package-spec), an optional `pluginConfig` with plugin-specific backstage configuration, and an optional `disabled` flag to disable/enable a plugin listed in `includes` files. It also includes an `integrity` field that is used to verify the plugin package [integrity](https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description). | list | `[]` |
-| global.host | Custom hostname shorthand, overrides `global.clusterRouterBase`, `upstream.ingress.host`, `route.host`, and url values in `upstream.backstage.appConfig` | string | `""` |
+| global.host | Custom hostname shorthand, overrides `global.clusterRouterBase`, `upstream.ingress.host`, `route.host`, and url values in `upstream.backstage.appConfig`. If neither `global.clusterRouterBase` nor `global.host` are set, the helm chart will attempt to autofill with the hostname of the [OCP Ingress configuration](https://access.redhat.com/documentation/en-us/openshift_container_platform/4.14/html/networking/configuring-ingress#nw-installation-ingress-config-asset_configuring-ingress) | string | `""` |
 | route | OpenShift Route parameters | object | `{"annotations":{},"enabled":true,"host":"{{ .Values.global.host }}","path":"/","tls":{"caCertificate":"","certificate":"","destinationCACertificate":"","enabled":true,"insecureEdgeTerminationPolicy":"Redirect","key":"","termination":"edge"},"wildcardPolicy":"None"}` |
 | route.annotations | Route specific annotations | object | `{}` |
 | route.enabled | Enable the creation of the route resource | bool | `true` |
@@ -167,7 +158,7 @@ Features enabled by the default chart configuration:
 2. Exposes a `Route` for easy access to the instance
 3. Enables OpenShift-compatible PostgreSQL database storage
 
-For additional instance features please consuls [documentation for `janus-idp/backstage-showcase`](https://github.com/janus-idp/backstage-showcase/).
+For additional instance features please consult the [documentation for `janus-idp/backstage-showcase`](https://github.com/janus-idp/backstage-showcase/tree/main/showcase-docs).
 
 Additional features can be enabled by extending the default configuration at:
 
@@ -182,7 +173,7 @@ upstream:
 
 ## Features
 
-This charts defaults to using the Janus-IDP Backstage Showcase image that is OpenShift compatible:
+This charts defaults to using the [latest Janus-IDP Backstage Showcase image](https://quay.io/janus-idp/backstage-showcase:latest) that is OpenShift compatible:
 
 ```
 quay.io/janus-idp/backstage-showcase:latest
@@ -194,30 +185,34 @@ Additionally this chart enhances the upstream Backstage chart with following Ope
 
 This chart offers a drop-in replacement for the `Ingress` resource already provided by the upstream chart via an OpenShift `Route`.
 
-OpenShift routes are enabled by default. In order to use the chart without it, please switch to the `Ingress` resource via `upstream.ingress` values.
+OpenShift routes are enabled by default. In order to use the chart without it, please set `route.enabled` to `false` and switch to the `Ingress` resource via `upstream.ingress` values.
+
+Routes can be further configured via the `route` field.
 
-Routes can be further configured via the `route` value.
+By default, the chart expects you to expose Backstage via the autogenerated hostname, which is automatically obtained from the OpenShift Ingress Configurations.
 
-By default, the chart expects you to expose Backstage via the autogenerated hostname. To provide Backstage pod with the right context, please adjust following value:
+To manually provide the Backstage pod with the right context, please add the following value:
 
 ```yaml
 # values.yaml
 global:
   clusterRouterBase: apps.example.com
 ```
+> Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file
 
-Custom hosts are also supported via following shorthand:
+Custom hosts are also supported via the following shorthand:
 
 ```yaml
 # values.yaml
 global:
   host: backstage.example.com
 ```
 
-Please note this is just a templating shorthand. For full manual configuration please pay attention to values under `route` key.
-
-Please note that any custom modifications to how backstage is being exposed may require additional changes to values:
+> Note: Setting either `global.host` or `global.clusterRouterBase` will disable the automatic hostname discovery.
+        When both fields are set, `global.host` will take precedence.
+        These are just templating shorthands. For full manual configuration please pay attention to values under the `route` key.
 
+Any custom modifications to how backstage is being exposed may require additional changes to the `values.yaml`:
 ```yaml
 # values.yaml
 upstream:
@@ -233,12 +228,12 @@ upstream:
 
 ### Vanilla Kubernetes compatibility mode
 
-In order to deploy this chart on vanilla Kubernetes or any other non-OCP platform, please make sure to apply following changes. Further customization may be required, depending on your exact Kubernetes setup:
+In order to deploy this chart on vanilla Kubernetes or any other non-OCP platform, please make sure to apply the following changes. Note that fieldsurther customization may be required, depending on your exact Kubernetes setup:
 
 ```yaml
 # values.yaml
 global:
-  host: # Specify your own Ingress host
+  host: # Specify your own Ingress host as automatic hostname discovery is not supported outside of OpenShift
 route:
   enabled: false  # OpenShift Routes do not exist on vanilla Kubernetes
 upstream:

diff --git a/charts/backstage/README.md.gotmpl b/charts/backstage/README.md.gotmpl
@@ -64,15 +64,6 @@ helm repo add janus-idp https://janus-idp.github.io/helm-backstage
 
 Once the chart has been added, install this chart. However before doing so, please review the default `values.yaml` and adjust as needed.
 
-- To get proper connection between frontend and backend of Backstage please update the `apps.example.com` to match your cluster host:
-
-   ```yaml
-   global:
-     clusterRouterBase: apps.example.com
-   ```
-
-   > Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file
-
 - If your cluster doesn't provide PVCs, you should disable PostgreSQL persistence via:
 
    ```yaml
@@ -123,7 +114,7 @@ Features enabled by the default chart configuration:
 2. Exposes a `Route` for easy access to the instance
 3. Enables OpenShift-compatible PostgreSQL database storage
 
-For additional instance features please consuls [documentation for `janus-idp/backstage-showcase`](https://github.com/janus-idp/backstage-showcase/).
+For additional instance features please consult the [documentation for `janus-idp/backstage-showcase`](https://github.com/janus-idp/backstage-showcase/tree/main/showcase-docs).
 
 Additional features can be enabled by extending the default configuration at:
 
@@ -138,7 +129,7 @@ upstream:
 
 ## Features
 
-This charts defaults to using the Janus-IDP Backstage Showcase image that is OpenShift compatible:
+This charts defaults to using the [latest Janus-IDP Backstage Showcase image](https://quay.io/janus-idp/backstage-showcase:latest) that is OpenShift compatible:
 
 ```
 quay.io/janus-idp/backstage-showcase:latest
@@ -150,30 +141,34 @@ Additionally this chart enhances the upstream Backstage chart with following Ope
 
 This chart offers a drop-in replacement for the `Ingress` resource already provided by the upstream chart via an OpenShift `Route`.
 
-OpenShift routes are enabled by default. In order to use the chart without it, please switch to the `Ingress` resource via `upstream.ingress` values.
+OpenShift routes are enabled by default. In order to use the chart without it, please set `route.enabled` to `false` and switch to the `Ingress` resource via `upstream.ingress` values.
+
+Routes can be further configured via the `route` field.
 
-Routes can be further configured via the `route` value.
+By default, the chart expects you to expose Backstage via the autogenerated hostname, which is automatically obtained from the OpenShift Ingress Configurations.
 
-By default, the chart expects you to expose Backstage via the autogenerated hostname. To provide Backstage pod with the right context, please adjust following value:
+To manually provide the Backstage pod with the right context, please add the following value:
 
 ```yaml
 # values.yaml
 global:
   clusterRouterBase: apps.example.com
 ```
+> Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file
 
-Custom hosts are also supported via following shorthand:
+Custom hosts are also supported via the following shorthand:
 
 ```yaml
 # values.yaml
 global:
   host: backstage.example.com
 ```
 
-Please note this is just a templating shorthand. For full manual configuration please pay attention to values under `route` key.
-
-Please note that any custom modifications to how backstage is being exposed may require additional changes to values:
+> Note: Setting either `global.host` or `global.clusterRouterBase` will disable the automatic hostname discovery.
+        When both fields are set, `global.host` will take precedence.
+        These are just templating shorthands. For full manual configuration please pay attention to values under the `route` key.
 
+Any custom modifications to how backstage is being exposed may require additional changes to the `values.yaml`:
 ```yaml
 # values.yaml
 upstream:
@@ -190,12 +185,12 @@ upstream:
 
 ### Vanilla Kubernetes compatibility mode
 
-In order to deploy this chart on vanilla Kubernetes or any other non-OCP platform, please make sure to apply following changes. Further customization may be required, depending on your exact Kubernetes setup:
+In order to deploy this chart on vanilla Kubernetes or any other non-OCP platform, please make sure to apply the following changes. Note that fieldsurther customization may be required, depending on your exact Kubernetes setup:
 
 ```yaml
 # values.yaml
 global:
-  host: # Specify your own Ingress host
+  host: # Specify your own Ingress host as automatic hostname discovery is not supported outside of OpenShift
 route:
   enabled: false  # OpenShift Routes do not exist on vanilla Kubernetes
 upstream:

diff --git a/charts/backstage/templates/_helpers.tpl b/charts/backstage/templates/_helpers.tpl
@@ -6,16 +6,18 @@ Returns custom hostname
         {{- .Values.global.host -}}
     {{- else if .Values.global.clusterRouterBase -}}
         {{- printf "%s-%s.%s" (include "common.names.fullname" .) .Release.Namespace .Values.global.clusterRouterBase -}}
-    {{- else -}}
-        {{/*
-        Attempt to obtain a fallback value for the hostname from the openshift cluster if both global.host and global.clusterRouterBase are ""
-        */}}
+    {{/*
+    Attempt to obtain a fallback value for the hostname from the openshift cluster if both global.host and global.clusterRouterBase are "" and if deployed on Openshift
+    */}}
+    {{- else if .Capabilities.APIVersions.Has "config.openshift.io/v1/Ingress" }}  
         {{- $cluster := (lookup "config.openshift.io/v1" "Ingress" "" "cluster") -}}
         {{- if and (hasKey $cluster "spec") (hasKey $cluster.spec "domain") }}
             {{- printf "%s-%s.%s" (include "common.names.fullname" .) .Release.Namespace $cluster.spec.domain -}}
         {{- else -}}
-            {{ fail "Unable to generate hostname" }}
+            {{ fail "Unable to generate hostname, OCP Ingress Resource is missing `spec.domain` field" }}
         {{- end }}
+    {{- else -}}
+        {{ fail "Unable to generate hostname, please provide a valid hostname in `global.host` or `global.clusterRouterBase`" }}
     {{- end -}}
 {{- end -}}
 

diff --git a/charts/backstage/values.schema.json b/charts/backstage/values.schema.json
@@ -21,7 +21,7 @@
                                 },
                                 "value": {
                                     "default": "",
-                                    "title": "Instead of generating a secret value, use fo;lowing value",
+                                    "title": "Instead of generating a secret value, use the following value",
                                     "type": "string"
                                 }
                             },
@@ -33,7 +33,7 @@
                     "type": "object"
                 },
                 "clusterRouterBase": {
-                    "default": "apps.example.com",
+                    "default": "",
                     "title": "Shorthand for users who do not want to specify a custom HOSTNAME. Used ONLY with the DEFAULT upstream.backstage.appConfig value and with OCP Route enabled.",
                     "type": "string"
                 },

diff --git a/charts/backstage/values.schema.tmpl.json b/charts/backstage/values.schema.tmpl.json
@@ -23,7 +23,7 @@
                 "clusterRouterBase": {
                     "title": "Shorthand for users who do not want to specify a custom HOSTNAME. Used ONLY with the DEFAULT upstream.backstage.appConfig value and with OCP Route enabled.",
                     "type": "string",
-                    "default": "apps.example.com"
+                    "default": ""
                 },
                 "host": {
                     "title": "Custom hostname shorthand, overrides `global.clusterRouterBase`, `upstream.ingress.host`, `route.host`, and url values in `upstream.backstage.appConfig`",
@@ -93,7 +93,7 @@
                                     "default": ""
                                 },
                                 "value": {
-                                    "title": "Instead of generating a secret value, use fo;lowing value",
+                                    "title": "Instead of generating a secret value, use the following value",
                                     "type": "string",
                                     "default": ""
                                 }

diff --git a/charts/backstage/values.yaml b/charts/backstage/values.yaml
@@ -14,8 +14,9 @@ global:
     plugins: []
 
   # -- Shorthand for users who do not want to specify a custom HOSTNAME. Used ONLY with the DEFAULT upstream.backstage.appConfig value and with OCP Route enabled.
-  clusterRouterBase: apps.example.com
-  # -- Custom hostname shorthand, overrides `global.clusterRouterBase`, `upstream.ingress.host`, `route.host`, and url values in `upstream.backstage.appConfig`
+  clusterRouterBase: ""
+  # -- Custom hostname shorthand, overrides `global.clusterRouterBase`, `upstream.ingress.host`, `route.host`, and url values in `upstream.backstage.appConfig`.
+  # If neither `global.clusterRouterBase` nor `global.host` are set, the helm chart will attempt to autofill with the hostname of the [OCP Ingress configuration](https://access.redhat.com/documentation/en-us/openshift_container_platform/4.14/html/networking/configuring-ingress#nw-installation-ingress-config-asset_configuring-ingress)
   host: ""
   # -- Enable service authentication within Backstage instance
   auth:
@@ -26,7 +27,7 @@ global:
       enabled: true
       # -- Instead of generating a secret value, refer to existing secret
       existingSecret: ""
-      # -- Instead of generating a secret value, use fo;lowing value
+      # -- Instead of generating a secret value, use the following value
       value: ""
 
 # -- Upstream Backstage [chart configuration](https://github.com/backstage/charts/blob/main/charts/backstage/values.yaml)
@@ -48,7 +49,7 @@ upstream:
     # can't accommodate that properly.
     appConfig:
       app:
-        # Please update to match host in case you don't want to configure hostname via `global.clusterRouterBase` or `global.host`.
+        # Please update to match host in case you don't want to configure hostname via `global.clusterRouterBase` or `global.host` if not deploying on an openshift cluster.
         baseUrl: 'https://{{- include "janus-idp.hostname" . }}'
       backend:
         baseUrl: 'https://{{- include "janus-idp.hostname" . }}'