diff --git a/contrib/chart/backstage/README.md b/contrib/chart/backstage/README.md index 22c1fae5df..1a045e09ca 100644 --- a/contrib/chart/backstage/README.md +++ b/contrib/chart/backstage/README.md @@ -2,15 +2,43 @@ This folder contains Helm charts that can easily create a Kubernetes deployment of a demo Backstage app. -To deploy it chose a DNS name where this demo will live and run +### Pre-requisites + +These charts depend on the `nginx-ingress` controller being present in the cluster. If it's not already installed you +can run: + +``` +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm install nginx-ingress ingress-nginx/ingress-nginx +``` + +### Installing the charts + +After choosing a DNS name where backstage will be hosted create a yaml file for your custom configuration. + +``` +appConfig: + app: + baseUrl: https://backstage.mydomain.com + title: Backstage + backend: + baseUrl: https://backstage.mydomain.com + cors: + origin: https://backstage.mydomain.com + lighthouse: + baseUrl: https://backstage.mydomain.com/lighthouse-api + techdocs: + storageUrl: https://backstage.mydomain.com/api/techdocs/static/docs + requestUrl: https://backstage.mydomain.com/api/techdocs + +``` + +Then use it to run: ``` git clone https://github.com/spotify/backstage.git cd contrib/chart/backstage -helm install backstage . \ ---set appConfig.app.baseUrl="https://backstage.mydomain.com" \ ---set appConfig.backend.baseUrl="https://backstage.mydomain.com" \ ---set appConfig.backend.cors.origin.baseUrl="https://backstage.mydomain.com" \ +helm install -f backstage-mydomain.yaml backstage . ``` This command will deploy the following pieces: @@ -23,16 +51,21 @@ This command will deploy the following pieces: After a few minutes Backstage should be up and running in your cluster under the DNS specified earlier. -Make sure to create the appropriate DNS entry in your infrastructure. To find the IP address run +Make sure to create the appropriate DNS entry in your infrastructure. To find the public IP address run: ```bash $ kubectl get ingress NAME HOSTS ADDRESS PORTS AGE -backstage-ingress * 34.77.171.192 80 17m +backstage-ingress * 123.1.2.3 80 17m ``` > **NOTE**: this is not a production ready deployment. +## Caveats + +The current implementation does not generate certificates for the ingress which means the browser will alert that the +site is insecure and using self-signed certificates. + ## Customization ### Custom PostgreSQL instance @@ -60,6 +93,9 @@ appConfig: host: user: password: + lighthouse: + baseUrl: https://backstage-demo.mydomain.com/lighthouse-api + lighthouse: database: client: pg @@ -84,6 +120,27 @@ cd contrib/chart/backstage helm install -f backstage-prod.yaml my-backstage . ``` +### Use your own docker images + +The docker images used for the deployment can be configured through the charts values: + +``` +frontend: + image: + repository: + tag: + +backend: + image: + repository: + tag: + +frontend: + image: + repository: +``` + ### Different namespace To install the charts a specific namespace use `--namespace `: @@ -100,8 +157,38 @@ To deploy backstage with the pre-loaded demo data disable `backend.demoData`: helm install -f my_values.yaml --set backend.demoData=false backstage . ``` +### Other options + +For more customization options take a look at the [values.yaml](/contrib/chart/backstage/values.yaml) file. + ## Troubleshooting +Some resources created by these charts are meant to survive after upgrades and even after uninstalls. When +troubleshooting these charts it can be useful to delete these resources between re-installs. + +Secrets: + +``` +-postgresql-certs -- contains the certificates used by the deployed PostgreSQL +``` + +Persistent volumes: + +``` +data--postgresql-0 -- this is the data volume used by PostgreSQL to store data and configuration +``` + +> **NOTE**: this volume also stores the configuration for PostgreSQL which includes things like the password for the +> `postgres` user. This means that uninstalling and re-installing the charts with `postgres.enabled` set to `true` and +> auto generated passwords will fail. The solution is to delete this volume with +> `kubectl delete pvc data--postgresql-0` + +ConfigMaps: + +``` +-postgres-ca -- contains the generated CA certificate for PostgreSQL when `postgres` is enabled +``` + #### Unable to verify signature ``` @@ -113,6 +200,18 @@ Backend failed to start up Error: unable to verify the first certificate code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' ``` -This error happens in the backend when it tries to connect to the configured PostgreSQL database and the specified CA is not correct. The solution is to make sure that the contents of the `configmap` that holds the certificate match the CA for the PostgreSQL instance. A workaround is to set `appConfig.backend.database.connection.ssl.rejectUnauthorized` to `false` in the chart's values. +This error happens in the backend when it tries to connect to the configured PostgreSQL database and the specified CA is not correct. The solution is to make sure that the contents of the `configMap` that holds the certificate match the CA for the PostgreSQL instance. A workaround is to set `appConfig.backend.database.connection.ssl.rejectUnauthorized` to `false` in the chart's values. + +## Uninstalling Backstage + +To uninstall Backstage simply run: + +``` +RELEASE_NAME= # use `helm list` to find out the name +helm uninstall ${RELEASE_NAME} +kubectl delete pvc data-${RELEASE_NAME}-postgresql-0 +kubectl delete secret ${RELEASE_NAME}-postgresql-certs +kubectl delete configMap ${RELEASE_NAME}-postgres-ca +``` diff --git a/docs/getting-started/deployment-k8s.md b/docs/getting-started/deployment-k8s.md index ddcbd290c6..c2682d85a4 100644 --- a/docs/getting-started/deployment-k8s.md +++ b/docs/getting-started/deployment-k8s.md @@ -4,4 +4,65 @@ title: Kubernetes description: Documentation on Kubernetes and K8s Deployment --- -Coming soon! +# Helm charts + +An example Backstage app can be deployed in Kubernetes using the [Backstage Helm +charts][backstage-helm-charts] + +First, choose a DNS name where backstage will be hosted create a yaml file for +your custom configuration. + +``` +appConfig: + app: + baseUrl: https://backstage.mydomain.com + title: Backstage + backend: + baseUrl: https://backstage.mydomain.com + cors: + origin: https://backstage.mydomain.com + lighthouse: + baseUrl: https://backstage.mydomain.com/lighthouse-api + techdocs: + storageUrl: https://backstage.mydomain.com/api/techdocs/static/docs + requestUrl: https://backstage.mydomain.com/api/techdocs + +``` + +Then use it to run: + +``` +git clone https://github.com/spotify/backstage.git +cd contrib/chart/backstage +helm install -f backstage-mydomain.yaml backstage . +``` + +This command will deploy the following pieces: + +- Backstage frontend +- Backstage backend with scaffolder and auth plugins +- (optional) a PostgreSQL instance +- lighthouse plugin +- ingress + +After a few minutes Backstage should be up and running in your cluster under the +DNS specified earlier. + +Make sure to create the appropriate DNS entry in your infrastructure. To find +the public IP address run: + +```bash +$ kubectl get ingress +NAME HOSTS ADDRESS PORTS AGE +backstage-ingress * 123.1.2.3 80 17m +``` + +> **NOTE**: this is not a production ready deployment. + +For more information on how to customize the deployment check the +[README][charts-readme]. + +[backstage-helm-charts]: + (https://github.com/spotify/backstage/tree/master/contrib/chart/backstage) +[charts-readme]: + (https://github.com/spotify/backstage/tree/master/contrib/chart/backstage/README.md)