From d83df5314f71e07abea07128691de2a87fd5387b Mon Sep 17 00:00:00 2001 From: Frank Kong <50030060+Zaperex@users.noreply.github.com> Date: Tue, 23 Jan 2024 10:20:13 -0500 Subject: [PATCH] feat: add fallback value for janus-idp.hostname for openshift clusters (#169) * feat: add fallback value for janus-idp.hostname for openshift clusters * chore: update defaults, documentation and update errors to be more verbose * chore: update tests for new default value of `global.clusterRouterBase` * chore: update docs and error message --- .github/workflows/test.yml | 8 ++--- charts/backstage/Chart.yaml | 2 +- charts/backstage/README.md | 45 +++++++++++------------- charts/backstage/README.md.gotmpl | 37 +++++++++---------- charts/backstage/templates/_helpers.tpl | 12 ++++++- charts/backstage/values.schema.json | 4 +-- charts/backstage/values.schema.tmpl.json | 4 +-- charts/backstage/values.yaml | 9 ++--- 8 files changed, 63 insertions(+), 58 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a136d0ea..236f0e85 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -60,7 +60,7 @@ jobs: helm repo update - name: Run chart-testing (lint) - run: ct lint --config ct.yaml + run: ct lint --config ct.yaml --helm-extra-args="--set upstream.backstage.image.tag=latest --set global.clusterRouterBase=app.example.yaml" - name: Create KIND Cluster uses: helm/kind-action@dda0770415bac9fc20092cacbc54aa298604d140 # v1.8.0 @@ -70,7 +70,7 @@ jobs: - name: Run chart-testing (latest) # test with latest stable backstage-showcase release - run: ct install --config ct-install.yaml --helm-extra-set-args="--set=upstream.backstage.image.tag=latest" + run: ct install --config ct-install.yaml --helm-extra-set-args="--set=upstream.backstage.image.tag=latest --set=global.clusterRouterBase=app.example.com" test-next: name: Test Next Release runs-on: ubuntu-latest @@ -100,7 +100,7 @@ jobs: helm repo update - name: Run chart-testing (lint) - run: ct lint --config ct.yaml + run: ct lint --config ct.yaml --helm-extra-args="--set upstream.backstage.image.tag=next --set global.clusterRouterBase=app.example.yaml" - name: Create KIND Cluster uses: helm/kind-action@dda0770415bac9fc20092cacbc54aa298604d140 # v1.8.0 @@ -110,4 +110,4 @@ jobs: - name: Run chart-testing (next) # test with the next backstage-showcase version (main branch) - run: ct install --config ct-install.yaml --helm-extra-set-args="--set=upstream.backstage.image.tag=next" + run: ct install --config ct-install.yaml --helm-extra-set-args="--set=upstream.backstage.image.tag=next --set=global.clusterRouterBase=app.example.com" diff --git a/charts/backstage/Chart.yaml b/charts/backstage/Chart.yaml index a452acd5..64dec060 100644 --- a/charts/backstage/Chart.yaml +++ b/charts/backstage/Chart.yaml @@ -41,4 +41,4 @@ sources: # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 2.11.4 +version: 2.12.0 diff --git a/charts/backstage/README.md b/charts/backstage/README.md index 14501fec..89ad0ea4 100644 --- a/charts/backstage/README.md +++ b/charts/backstage/README.md @@ -2,7 +2,7 @@ # Janus-IDP Backstage Helm Chart [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/janus-idp&style=flat-square)](https://artifacthub.io/packages/search?repo=janus-idp) -![Version: 2.11.4](https://img.shields.io/badge/Version-2.11.4-informational?style=flat-square) +![Version: 2.12.0](https://img.shields.io/badge/Version-2.12.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) A Helm chart for deploying a Backstage application @@ -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
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,9 +173,9 @@ 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: -``` +```console quay.io/janus-idp/backstage-showcase:latest ``` @@ -194,11 +185,13 @@ 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` value. +Routes can be further configured via the `route` field. -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: +By default, the chart expects you to expose Backstage via the autogenerated hostname, which is automatically obtained from the OpenShift Ingress Configurations. + +To manually provide the Backstage pod with the right context, please add the following value: ```yaml # values.yaml @@ -206,7 +199,9 @@ global: clusterRouterBase: apps.example.com ``` -Custom hosts are also supported via following shorthand: +> Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file + +Custom hosts are also supported via the following shorthand: ```yaml # values.yaml @@ -214,9 +209,11 @@ 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. +> 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. -Please note that any custom modifications to how backstage is being exposed may require additional changes to values: +Any custom modifications to how backstage is being exposed may require additional changes to the `values.yaml`: ```yaml # values.yaml @@ -233,12 +230,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 further customizations 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 index 2e74fa23..78fc45c2 100644 --- 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,9 +129,9 @@ 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: -``` +```console quay.io/janus-idp/backstage-showcase:latest ``` @@ -150,11 +141,13 @@ 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` value. +Routes can be further configured via the `route` field. -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: +By default, the chart expects you to expose Backstage via the autogenerated hostname, which is automatically obtained from the OpenShift Ingress Configurations. + +To manually provide the Backstage pod with the right context, please add the following value: ```yaml # values.yaml @@ -162,7 +155,9 @@ global: clusterRouterBase: apps.example.com ``` -Custom hosts are also supported via following shorthand: +> Tip: you can use `helm upgrade -i --set global.clusterRouterBase=apps.example.com ...` instead of a value file + +Custom hosts are also supported via the following shorthand: ```yaml # values.yaml @@ -170,9 +165,11 @@ 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. +> 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. -Please note that any custom modifications to how backstage is being exposed may require additional changes to values: +Any custom modifications to how backstage is being exposed may require additional changes to the `values.yaml`: ```yaml # values.yaml @@ -190,12 +187,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 further customizations 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 index 53101c0f..cfaf08e4 100644 --- a/charts/backstage/templates/_helpers.tpl +++ b/charts/backstage/templates/_helpers.tpl @@ -6,8 +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 -}} + {{/* + 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, OCP Ingress Resource is missing `spec.domain` field. Please provide a valid hostname in `global.host` or `global.clusterRouterBase` instead" }} + {{- end }} {{- else -}} - {{ fail "Unable to generate hostname" }} + {{ 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 index ea7a7626..a4b9643b 100644 --- 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 index 0c4bde54..e60f9a36 100644 --- 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 index 725523da..54c6e259 100644 --- 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" . }}'