paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 30 Packages Projects Releases Wiki Activity

Add more documentation to charts README and k8s guide

Browse Source
This commit is contained in:
Martina Iglesias Fernandez
2020-10-07 17:37:03 +02:00
parent 9f44b650f0
commit 6289cea398
2 changed files with 169 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contrib/chart/backstage/README.md
+107 -8
View File
@@ -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: <host>
user: <pg user>
password: <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: <image-name>
tag: <image-tag>
backend:
image:
repository: <image-name>
tag: <image-tag>
frontend:
image:
repository: <image-name
tag: <image-tag>
```
### Different namespace
To install the charts a specific namespace use `--namespace <ns>`:
@@ -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:
```
<release-name>-postgresql-certs -- contains the certificates used by the deployed PostgreSQL
```
Persistent volumes:
```
data-<release-name>-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-<release-name>-postgresql-0`
ConfigMaps:
```
<release-name>-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.
<!-- TODO Add example command when we know the final name of the charts -->
## Uninstalling Backstage
To uninstall Backstage simply run:
```
RELEASE_NAME=<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
```
docs/getting-started/deployment-k8s.md
+62 -1
View File
@@ -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)