Skip to content

Commit a2b3867

Browse files
Laurin-NotemannDrAdamRoe
Laurin-Notemann
and
DrAdamRoe
authored
Setup Kubernetes plugin and documentation (#3)
* feat: configure deployment on kube cluster * feat: add github auth * feat: add examples * fix: cleanup config files and expose example templates * fix: typo in .env var * chore: add proper documentation for setting up Backstage * fix: uncomment nodeenv in dockerfile * chore: add minikube installation and explanation about app-config files * fix: typos in README.md * small clarifications to readme text --------- Co-authored-by: Adam Roe <[email protected]>
1 parent 5b9e442 commit a2b3867

30 files changed

+1475
-138
lines changed

‎.env.example‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
POSTGRES_HOST="backstage_pg_db"
1+
POSTGRES_HOST="backstage_postgres"
22
POSTGRES_PORT="5432"
33
POSTGRES_USER="postgres"
44
POSTGRES_PASSWORD="admin"
5+
6+
BASE_URL="http://localhost:7007"
7+
58
GITHUB_CLIENT_ID="your-id"
69
GITHUB_CLIENT_SECRET="your-secret"
10+
11+
GITHUB_TOKEN="your-token"
12+
13+
K8S_URL="k8s-url"
14+
K8S_ACCOUNT_TOKEN="k8s-account-token"
15+
K8S_CA_DATA="k8s-ca-data"
16+
K8S_CA_FILE="k8s-ca-file"

‎.example.app-config.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
backend:
2+
database:
3+
client: pg
4+
connection:
5+
host: 127.0.0.1
6+
port: 5433

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,7 @@ site
5252

5353
# E2E test reports
5454
e2e-test-report/
55+
56+
pg_values.yaml
57+
58+
*secret.yaml

‎Dockerfile‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid
3131

3232
COPY --chown=node:node . .
3333

34+
RUN ls
35+
36+
RUN ls /app
37+
3438
RUN yarn tsc
3539
RUN yarn --cwd packages/backend build
3640
# If you have not yet migrated to package roles, use the following command instead:
@@ -68,12 +72,16 @@ RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid
6872

6973
# Copy the built packages from the build stage
7074
COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./
75+
COPY --from=build --chown=node:node /app/minikube ./minikube/
76+
77+
ARG APP_ENV
7178

72-
# Copy any other files that we need at runtime
79+
# Copy any other files that we need at runtime, to understand how the configs work refer to the README.md
7380
COPY --chown=node:node app-config.yaml ./
74-
COPY --chown=node:node app-config.production.yaml ./
81+
COPY --chown=node:node app-config.docker.yaml ./app-config.docker.yaml
82+
COPY --chown=node:node app-config.${APP_ENV}.yaml ./app-config.env.yaml
7583

76-
# This switches many Node.js dependencies to production mode.
84+
# This switches many Node.js dependencies to production mode. Important APP_ENV and NODE_ENV serve two different purposes
7785
ENV NODE_ENV production
7886

79-
CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml"]
87+
CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.docker.yaml", "--config", "app-config.env.yaml"]

‎README.md‎

Lines changed: 281 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,300 @@
1-
# [Backstage](https://backstage.io)
2-
IMPORTANT:
3-
if you use docker you need a .env file
1+
### [Backstage](https://backstage.io)
42

3+
# Setup for code-idp as a developer:
4+
5+
Prerequisites:
6+
7+
- [Yarn 1 "Classic"](https://classic.yarnpkg.com/lang/en/docs/install/)
8+
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
9+
10+
Clone the repository and install node_modules:
11+
```sh
12+
git clone https://github.com/codeuniversity/code-idp
13+
14+
cd code-idp
15+
16+
yarn
17+
```
18+
19+
Setup environment variables using .env and app-config.local.yaml:
520
```sh
621
cp .env.example .env
22+
23+
cp .example.app-config.yaml app-config.local.yaml
724
```
825

9-
```sh
10-
cp .example.app-config.local.yaml app-config.local.yaml
26+
These two newly created files `.env` and ` app-config.local.yaml` are for your secrets and local configurations. These files do not get pushed to the GitHub repository and are safe to use.
27+
28+
# More on Environment variables
29+
30+
The following environment variables are currently used, please make sure they are in your .env:
1131
```
32+
POSTGRES_HOST="backstage_postgres"
33+
POSTGRES_PORT="5432"
34+
POSTGRES_USER="postgres"
35+
POSTGRES_PASSWORD="admin"
1236
13-
IMPORTANT: to setup Github follow this guide and change the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET values in the .env
37+
BASE_URL="http://localhost:7007"
1438
15-
https://backstage.io/docs/getting-started/configuration
39+
GITHUB_CLIENT_ID="your-id"
40+
GITHUB_CLIENT_SECRET="your-secret"
1641
42+
GITHUB_TOKEN="your-token"
1743
18-
to run in docker (this takes up to 3-5 mins):
19-
```sh
20-
docker compose up -d --build
44+
K8S_URL="k8s-url"
45+
K8S_ACCOUNT_TOKEN="k8s-account-token"
46+
K8S_CA_DATA="k8s-ca-data"
47+
K8S_CA_FILE="k8s-ca-file"
2148
```
2249

23-
Only use the --build command if you changed something otherwise this is enough
24-
```sh
25-
docker compose up -d
26-
```
50+
<details>
51+
<summary>Details to the environment variables</summary>
52+
<br>
2753

28-
To remove the docker container
29-
```sh
30-
docker compose down
31-
```
54+
**`POSTGRES`:**
55+
<br>
56+
All of the environment variables prefixed with POSTGRES_ should stay like they are in the .env.example for the optimal setup experince and only be changed if you know what you are doing.
3257

33-
If you to run the app locally (for quicker loading time and not having to reubild the image every time) but still connect to the docker pg database you need to run:
34-
```sh
35-
docker compose up -d pg_db
58+
**`BASE_URL`:**
59+
<br>
60+
Keep it the same as it is right now, this is the url on which the application is running.
61+
62+
**`GITHUB_CLIENT`:**
63+
<br>
64+
These environment variables are to setup correct [authentication](https://backstage.io/docs/getting-started/configuration#setting-up-authentication). Please follow [these](#github-auth) steps.
65+
66+
**`GITHUB_TOKEN`:**
67+
<br>
68+
This environment variable is to configure the [GitHub integration](https://backstage.io/docs/getting-started/configuration#setting-up-a-github-integration),
69+
so that Backstage can interact with your GitHub account and for example create a repository for you. Please follow [these](#github-integration) steps for the setup.
70+
71+
**`K8S_URL`:**
72+
<br>
73+
These environment variables are to configure the [kubernetes plugin](https://backstage.io/docs/features/kubernetes/).
74+
To setup you local minikube environment follow [these](#kubernetes) steps.
75+
</details>
76+
77+
# Setup Essentials
78+
The following setup steps are necessary to ensure that you have basic functionality in your app starting with
79+
a proper database, using docker set up a postgres db, after that setting aber GitHub authentication and the GitHub
80+
Integration so that you can interact with Github.
81+
82+
## Setup database (with `docker`)
83+
To start the database with docker run the following command:
84+
```sh
85+
yarn docker:start-database
3686
```
87+
This will create a new database container with the name `backstage_postgres` exposed on local port 5433. This non-standard port is chosen on purpose to not conflict with other postgres instances which may be running locally.
88+
89+
## GitHub Auth
90+
To setup you GitHub authentication follow these steps:
3791

38-
And then:
92+
1. Go to https://github.com/settings/applications/new
93+
2. Enter an `Application name` (can be anything)
94+
3. Enter `http://127.0.0.1:7007` for `Homepage URL`
95+
4. Enter `http://127.0.0.1:7007/api/auth/github/handler/frame` for `Authorization callback URL`
96+
<br>
97+
It should look like this (yes you can leave Enable Device Flow off for now):
98+
<br>
99+
<img height="400" alt="img" src="./images/gitauth.svg">
100+
101+
5. After clicking on `Register Application` click on `Generate a new client secret`, and then your screen should look like this:
102+
<br>
103+
<img height="350" alt="img" src="./images/githubauth2.svg">
104+
105+
6. Now copy and paste your `Client ID` and your `Client secret` into the correct environment variables (`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`).
106+
107+
## GitHub Integration
108+
To get you GitHub integration working you need to generate yourself a new token like so:
109+
110+
1. Go to https://github.com/settings/tokens/new
111+
2. Write a note (can be empty but encourged so you know what the tokens belongs to)
112+
3. Set an expiration date (can be unlimited just be careful not to share it or you might have to revoke it manully)
113+
4. Select a scope the following is enough for basic usage (may have to adjusted if you want to go beyong the basic scope)
114+
<img height="400" alt="img" src="./images/githubintegration.svg">
115+
5. Copy and paste your `GitHub Token` and paste it into the correct environment variable (`GITHUB_TOKEN`)
116+
117+
# Running Environments
118+
If you have followed the essential setup steps ([Setup database](#setup-database-with-docker), [GitHub Auth](#github-auth) and [GitHub Integration](#github-integration))
119+
then you can decide where you to run backstage:
120+
121+
1. [locally](#running-with-yarn-dev) with `yarn dev` (recommended for regular development due to short waiting time on changes)
122+
2. inside of a [docker container](#running-with-docker-compose) (recommended only to test certain environments due to high waiting time because of high image build time (up to 5 mins))
123+
3. inside of [minikube](#running-with-minikube) (only recommended to test to be the closest to the actual production environment (for testing))
124+
<br>
125+
!! Note this is based on assumption that we will host `Backstage` inside of the Kubernetes cluster where we host the other dev projects
126+
127+
## Running with `yarn dev`
128+
Run this command in the root directory of the project:
39129
```sh
40-
yarn install
41130
yarn dev
42131
```
132+
This should automatically open your browser with the correct url, otherwise open `http://127.0.0.1:3000` in your browser.
133+
134+
Note that when you run with `yarn dev`, hot reload is running on certain parts of the application, meaning that the page in the browser will automatically update if you change the code. If however you need to force the app to restart simply press C-c (control-c) to interrupt the program and run `yarn dev` again.
135+
136+
> Note you don't need to setup up a local `Kubernetes` environment if you do not specifically need to work with Kubernetes entities (This was written on the 20.02.2024 so possibly subject to change).
137+
138+
## Running with `docker compose`
139+
For first use and **every time** you change something in the project (except the value of an environment variable) run:
140+
```sh
141+
yarn docker:run-build-backstage
142+
```
143+
144+
This will build the image (which *can* take up to 5-10 mins depending on your machine) and then start a new docker container in the same network docker network as the postgres database is.
145+
146+
To open Backstage in the browser now open `http://127.0.0.1:7007`.
147+
148+
If you want simply run the docker container again without rebuilding it (reminder any changes you did are not applied then) run:
149+
```sh
150+
yarn docker:run-backstage
151+
```
152+
153+
To stop the Backstage container run (simply run `yarn docker:run-backstage` to start the container again):
154+
```sh
155+
yarn docker:stop-backstage
156+
```
157+
158+
To remove the Backstage container run:
159+
```sh
160+
yarn docker:remove-backstage
161+
```
162+
163+
To remove all containers (**IMPORTANT** this also removes the database container meaning even `yarn dev` won't work) run:
164+
```sh
165+
yarn docker:remove-all
166+
```
167+
168+
# Kubernetes
169+
The following talks about two different topics (it is highly encourged to watch a short [tutorial](https://www.youtube.com/watch?v=PziYflu8cB8) on Kubernetes before continuing):
170+
171+
1. How to setup minikube and how to use Backstage to monitor pods that are running inside of Kubernetes.
172+
2. How to run Backstage itself inside of the minikube cluster (and still be able to monitor the pods that are running in Kubernetes, which means the first step is a pre-requisite of this step).
173+
The reason for having the second step is more for testing purposes because this setup is the closest to the actual production environment
174+
175+
> Note again here the second step is only true if we actually host Backstage in the same cluster as the other deployments
176+
177+
## Setup with `minikube`
178+
Pre-requisite: Docker installed
179+
180+
To setup minikube and the [Kubernetes plugin](https://backstage.io/docs/features/kubernetes/) so that we can monitor Kubernetes pods
181+
through Backstage we need to do the following:
182+
1. Install `kubectl`
183+
<br>
184+
1.1 Install the correct version of `kubectl` depending on your operation system: [linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/),
185+
[macOS](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) or [windows](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/). On macOS installing with
186+
homebrew is recommended by me.
187+
<br>
188+
1.2 Quick Note about `kubectl`: `kubectl` is the cli tool that can interact with an existing Kubernetes cluster and it has different `contexts` for different cluster.
189+
If this is your first time installing `kubectl` and you most likely do not have a cluster that you are connected to at this point, we will set up a local cluster with `minikube`
190+
in the following setup, and that will automatically set your context to the correct cluster (in this case `minikube`).
191+
To see all your contexts run `kubectl config get-contexts`.
192+
2. Install `minikube`
193+
<br>
194+
2.1 Follow [this guide](https://minikube.sigs.k8s.io/docs/start/#installation) to install minikube and also how to run minikube inside of a docker, make sure you install minikube for the correct system.
195+
Installing on macOS with homebrew is recommended by me.
196+
<br>
197+
2.2 Start minikube clutser with `minikube start` (can take a few minutes)
198+
<br>
199+
NOTE: If you have installed kubectl, `minikube start` will automatically set your current context to the `minikube` context!
200+
<br>
201+
2.3 To test if the installation worked run: `kubectl get pods -A` and you should have an output similiar to this:
202+
```
203+
NAMESPACE NAME READY STATUS RESTARTS AGE
204+
kube-system coredns-5d78c9869d-4jq4h 1/1 Running 0 9m43s
205+
kube-system etcd-minikube 1/1 Running 0 9m56s
206+
kube-system kube-apiserver-minikube 1/1 Running 0 9m58s
207+
kube-system kube-controller-manager-minikube 1/1 Running 0 9m58s
208+
kube-system kube-proxy-8dzhs 1/1 Running 0 9m44s
209+
kube-system kube-scheduler-minikube 1/1 Running 0 9m56s
210+
kube-system storage-provisioner 1/1 Running 1 (9m39s ago) 9m56s
211+
```
212+
3. Setup `minikube` for Backstage
213+
<br>
214+
<br>
215+
**3.1 Create a service account so that backstage can access the cluster**
216+
```sh
217+
kubectl apply -f minikube/clusterrolebinding.yaml
218+
219+
kubectl get secrets cluster-admin-secret -o jsonpath="{.data['token']}" | base64 --decode; echo
220+
```
221+
copy and paste that token in the K8S_ACCOUNT_TOKEN environment variable in your .env
222+
<br>
223+
<br>
224+
**3.2 Get the certificate authority for minikube**
225+
```sh
226+
cat ~/.minikube/ca.crt | base64
227+
```
228+
copy and paste that certificate in the K8S_CA_DATA environment variable in your .env
229+
<br>
230+
<br>
231+
**3.3 Get the URL that `minikube` is running on**
232+
```sh
233+
kubectl cluster-info
234+
```
235+
copy and paste the first URL in the K8S_URL environment variable in your .env
236+
<br>
237+
<br>
238+
**3.4 Run pod in `minikube` to be inspected by `Backstage`**
239+
```sh
240+
kubectl apply -f minikube/test-deployment.yaml
241+
```
242+
243+
> NOTE: we leave the K8S_CA_FILE environment variable empty for now because that is only needed if you run Backstage in the cluster,
244+
for now it is recommended only to run it [locally](#running-with-yarn-dev) or run in [docker](#running-with-docker-compose) to be able to run it inside of minikube read [here](#running-with-minikube)
245+
246+
4. [Run](#running-environments) backstage (recommended [locally](#running-with-yarn-dev))
247+
<br>
248+
NOTE: If you want to run backstage inside of the docker container you need to change the K8S_URL variable to: https://host.docker.internal:[YOUR-PORT]
249+
<br>
250+
251+
4.1 Click on `test-minikube`
252+
<br>
253+
<img height="200" alt="img" src="./images/backstage-example.svg">
254+
255+
4.2 Click on `Kubernetes`
256+
<br>
257+
<img height="150" alt="img" src="./images/backstage-kubernetes.svg">
258+
259+
4.3 Now you should see this:
260+
<br>
261+
<img height="200" alt="img" src="./images/backstage-kube-success.svg">
262+
263+
5. To see how you can expose your own Backstage entities follow
264+
[this](https://backstage.io/docs/features/kubernetes/configuration#surfacing-your-kubernetes-components-as-part-of-an-entity) guide
265+
266+
## Running with `minikube`
267+
Work in progress -> Not necessary for development right now.
268+
269+
# Configuration
270+
To get a better understanding of how the app-config.yaml files work please refer to [this](https://backstage.io/docs/conf/writing).
271+
Specifically the part about the [config files](https://backstage.io/docs/conf/writing#configuration-files) is important to understand.
272+
273+
The following explanation will go more into detail about how we use them in our project but expects you to understand how they work in general:
274+
275+
Currently we have:
276+
- app-config.yaml
277+
- app-config.local.yaml
278+
- app-config.docker.yaml
279+
- app-config.production.yaml
280+
281+
**`app-config.yaml`:**
282+
<br>
283+
This is the basic configuration that get applied to all of our environments and should contain the bases for all environments.
284+
If you need to change something for all environments please add/delete or update them here in this file.
285+
286+
**`app-config.local.yaml`:**
287+
<br>
288+
All attributes in this file overwrite the `app-config.yaml` attributes when you run [locally](#running-with-yarn-dev).
289+
Currently we are only specifing the database host and port because they slightly different in our .env file, which is designed to work for the docker compose.
290+
291+
**`app-config.docker.yaml`:**
292+
<br>
293+
This file changes some base values that are necessary to build the correct image and it currently changes attributes such as:
294+
- baseUrl because the docker image bundles the frontend into the backend -> therefore we only have one
295+
- auth.github because we set the NODE_ENV to production for the image
296+
- catalog because it interprets the paths from local directories differently in the image
297+
298+
**`app-config.production.yaml`:**
299+
<br>
300+
This file adds one line to the kubernetes plugin setup, which is only needed if the app is hosted inside of a kubernetes cluster.

0 commit comments

Comments
 (0)