https://github.com/rse/k8s-sample
Kubernetes (K8S) Sample Application
https://github.com/rse/k8s-sample
docker kubernetes postgresql sample sqlite
Last synced: 9 months ago
JSON representation
Kubernetes (K8S) Sample Application
- Host: GitHub
- URL: https://github.com/rse/k8s-sample
- Owner: rse
- Created: 2019-09-30T20:28:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-16T11:27:04.000Z (over 1 year ago)
- Last Synced: 2025-04-15T21:55:48.035Z (9 months ago)
- Topics: docker, kubernetes, postgresql, sample, sqlite
- Language: JavaScript
- Homepage:
- Size: 665 KB
- Stars: 4
- Watchers: 5
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
k8s-sample — Kubernetes Sample Application
================================================
This is a sample application to showcase the software deployment on
the container run-time environments [Docker](https://www.docker.com/)
and [Kubernetes (K8S)](https://kubernetes.io/). The
sample application uses a Rich-Client architecture, comprised of an
[HTML5](https://en.wikipedia.org/wiki/HTML5) Single-Page Application
(SPA) client and a [Node.js](https://nodejs.org/) server and runs
under an arbitrary URL prefix. To showcase important run-time aspects,
the application shows detailed environment information, persists data
(both locally via [SQLite](https://www.sqlite.org/) and remotely
via [PostgreSQL](https://www.postgresql.org/)) and allows one to
control the application process. The application is packaged into a
[Docker](https://www.docker.com/) container and then this container
is deployed onto a [Docker](https://www.docker.com/) run-time
environment via [Docker-Compose](https://docs.docker.com/compose/) and
onto a [Kubernetes](https://kubernetes.io/) run-time environment via
[Helm](https://helm.sh/).
This project provides you the entire life-cycle: connecting and
bootstrapping the run-time environments, building and running the
application locally, building the application into a container
and deploying the container onto the run-time environments. On
the client side all this just needs a plain Linux/amd64 system
(e.g. [use Windows Subsystem for Linux (WSL) under Windows 10](https://github.com/rse/unix-under-windows))
with the [git(1)](https://git-scm.com/) and [curl(1)](https://curl.haxx.se/) programs installed.
Everything is performed remotely, does not need any local privileges (including the local
downloaded client programs) and does not change the local Linux system
at all.
Sneak Preview
-------------
Quick Test-Drive
----------------
For standard contexts:
```sh
$ git clone https://github.com/rse/k8s-sample/ # clone repository
$ cd k8s-sample # enter working copy
$ (cd 1-env-util && make) # etablish environment utility
$ bash 2-env-setup/1-setup-std.bash [] # setup environment
$ source 2-env-setup/2-env.bash # attach environment
$ source 2-env-setup/3-root.bash # create cluster admin
$ source 2-env-setup/4-namespace.bash # create application namespace
$ cd 6-run-kubernetes # enter Kubernetes deployment procedure
$ make install [DB_ENABLED=true] # execute Kubernetes deployment procedure
$ open http[s]:///k8s-sample/ # open deployed application
```
For special msg Project Server (PS) contexts
(where `` is the FQDN of the msg Project Server instance
where you have SSH access to):
```sh
$ git clone https://github.com/rse/k8s-sample/ # clone repository
$ cd k8s-sample # enter working copy
$ (cd 1-env-util && make) # etablish environment utility
$ bash 2-env-setup/1-setup-ps.bash # setup environment
$ source 2-env-setup/2-env.bash # attach environment
$ source 2-env-setup/3-root.bash # create cluster admin
$ source 2-env-setup/4-namespace.bash # create application namespace
$ cd 6-run-kubernetes # enter Kubernetes deployment procedure
$ make install [DB_ENABLED=true] # execute Kubernetes deployment procedure
$ open http[s]:///ase-k3s/k8s-sample/ # open deployed application
```
Short Background
----------------
On the application development side, the Docker and Kubernetes worlds
are primarily driven by four command-line client programs this
**k8s-sample** is using, too:
| | low-level
(commands) | high-level
(stacks) |
|----------- | ------------------------ | ----------------------- |
| Docker | `docker` | `docker-compose` |
| Kubernetes | `kubectl` | `helm` |
The Parts In Detail
-------------------
The **k8s-sample** consists of the following parts:
- **Kubernetes Environment Utility**: `1-env-util`
Here you can find a procedure for locally installing the companion
[**k8s-util(1)**](https://github.com/rse/k8s-util) utility. It ensures
that the command-line clients for accessing a Docker and Kubernetes
run-time environment are available and helps managing the
run-time access credentials in the part `2-env-setup`:
```sh
$ (cd 1-env-util && make)
```
- **Kubernetes Environment Setup**: `2-env-setup`
Here you can find the scripts for establishing and attaching to the
Kubernetes run-time environment.
For standard contexts (arbitrary locally pre-existing Docker and
remotely pre-existing Kubernetes installation), use the following
command (where `` is the Kubernetes configuration of the
admin account as manually fetched from the Kubernetes installation):
```sh
$ bash 2-env-setup/1-setup-std.bash []
```
For msg Project Server (PS) contexts (where `` is the
hostname of the msg Project Server instance), instead the following
command should be used (which installs the Rancher K3S software stack
and uses both Docker and Kubernetes remotely):
```sh
$ bash 2-env-setup/1-setup-ps.bash
```
In case you have trouble with the TLS connectivity to your Kubernetes
cluster (usually in case of self-signed server certificates or a
certificate of an unknown CA), you can force Kubernetes to accept the
situation with:
```sh
$ kubectl config get-clusters
$ kubectl config set clusters..insecure-skip-tls-verify true
```
Now we import the setup results into our shell environment with:
```sh
$ source 2-env-setup/2-env.bash
```
Then we create a cluster admin service account `root`, because
applications like the official Kubernetes Dashboard allow
authentication of "on-cluster" accounts only (instead of "off-cluster"
account like the initial admin account):
```sh
$ source 2-env-setup/3-root.bash
```
Finally, we create a dedicated namespace (and corresponding namespace
service account) `k8s-sample` for our application:
```sh
$ source 2-env-setup/4-namespace.bash
```
- **Application Source Code**: `3-app-source`
Here you can find the sources of the **k8s-sample** HTML5 SPA client and
the corresponding Node.js server. Only used by you in case you want
to understand and locally test-drive the application itself.
```sh
$ (cd 3-app-source/fe && make build)
$ (cd 3-app-source/be && make build start)
```
After this you can access the application under `https://127.0.0.1:9090/`.
You can stop the application with `CTRL+C`.
- **Application Container Build Procedure**: `4-app-container`
Here you can find the procedure for building and packaging the
**k8s-sample** application as a Docker/OCI container for use in both
step 5 and 6. Only used by you in case you want to understand the
Docker/OCI container packaging or build and push the container to
your container image repository/registry (e.g. Docker Hub).
```sh
$ (cd 4-app-container && make build push)
```
- **Docker Deployment Procedure**: `5-run-docker`
Here you can find the procedure for installing the **k8s-sample**
container (from step 4) onto a Docker run-time environment via the
clients docker(1) and docker-compose(1).
```sh
$ (cd 5-run-docker && make install [DATABASE=pgsql])
```
After this you can access the application under `http://:9090/`.
You can uninstall the application again with:
```sh
$ (cd 5-run-docker && make uninstall)
```
- **Kubernetes Deployment Procedure**: `6-run-kubernetes`
Here you can find the procedure for installing the **k8s-sample**
container (from step 4) onto a Kubernetes run-time environment via the
clients kubectl(1) and helm(1).
```sh
$ (cd 6-run-kubernetes && make install [DB_ENABLED=true])
```
After this you can access the application under `http:///k8s-sample/`
where `` is your Kubernetes ingress endpoint. For a msg Project Server
with the K3S Kubernetes stack, the URL is `http:///ase-k3s/k8s-sample/`
where `` is your msg Project Server instance.
You can uninstall the application again with:
```sh
$ (cd 6-run-kubernetes && make uninstall)
```
License
-------
Copyright © 2019-2020 Dr. Ralf S. Engelschall (http://engelschall.com/)
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.