cheshire
/
hscloud
forked from hswaw/hscloud
1
0
Fork 0
Code Pull Requests Activity

doc/codelabs/getting-started: update tutorials

master
cheshire 2023-11-19 14:47:59 +01:00
parent 6a33e8f442
commit d82f9fa788
5 changed files with 51 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/codelabs/getting-started/building-web-app.md → doc/codelabs/getting-started/building-flask-web-app.md
View File

@ -4,16 +4,14 @@ In this chapter, we will build our own web service using the Flask framework, do
## Requirements
You will require `docker` in this example. Install it from your standard shell.
You will require `docker` in this example. You can find installation instructions [here](https://docs.docker.com/engine/install/). For example, on Ubuntu you can install it with:
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
You can actually create, build and register docker image in completely other environment, and just deploy it to kubernetes in hscloud environment.
It is advised to have done [Run first service](run-first-service.md) chapter.
To create, build and register docker image you don't need a compiled hscloud environment, howerver you will need it to deploy the image to kubernetes.
## Steps
@ -35,8 +33,21 @@ if __name__ == '__main__':
app.run()
```
We can check if the application works by running it:
We can check if the application works by running it. First we start the virtual environment and install Flask:
```bash
# for Linux and macOS environments
python3 -m venv .venv
source .venv/bin/activate
```
```bash
# for Windows environments
py -m venv .venv
.venv\bin\Activate.bat
```
After that:
```bash
pip3 install flask
python3 app.py
@ -46,7 +57,7 @@ Now we create `Dockerfile` file for our application:
```Dockerfile
# Use an official Python runtime as a base image
FROM python:3.8-slim-buster
FROM python:3.12.0-bullseye
# Set the working directory in docker
WORKDIR /app
@ -72,15 +83,15 @@ CMD ["gunicorn", "-w", "4", "-b", ":5000", "app:app"]
We can test if the application works in Docker:
```bash
docker build -t myflask . # Build the image
docker run -d -p 5000:5000 myflask # Run the container
docker build -t myflask:2137 . # Build the image
docker run -p 5000:5000 myflask:2137 # Run the container
```
We can check if the application works by opening the browser at `http://localhost:5000`.
## Pushing the image to the registry
First, we need to authenticate to the registry:
First, we need to authenticate to the registry. That will require visiting the link in a web browser:
```
https://registry.k0.hswaw.net
@ -92,26 +103,23 @@ You should get command similar to:
docker login -u $hs_username -p *************** https://registry.k0.hswaw.net
```
Run it in your environment.
Now we need to create local server for our docker image:
```bash
docker tag myflask registry.k0.hswaw.net/$hs_username/myflask:latest
docker push registry.k0.hswaw.net/$hs_username/myflask:latest
```
To check if the image is in the registry, you can use:
```bash
curl -X GET https://registry.k0.hswaw.net/v2/$hs_username/myflask/tags/list
# create local server for our docker image. Replace $hs_username with your sso username
docker tag myflask:2137 registry.k0.hswaw.net/$hs_username/myflask:2137
docker push registry.k0.hswaw.net/$hs_username/myflask:2137
```
To remove the image from the registry, you can use:
```bash
docker rmi registry.k0.hswaw.net/$hs_username/myflask:latest
# remove image from registry. Replace $hs_username with your sso username
docker rmi registry.k0.hswaw.net/$hs_username/myflask:2137
```
## Next step
[Deploying web app](deploying-web-app.md)
[Deploying Flask web app](deploying-flask-web-app.md)

26
doc/codelabs/getting-started/deploying-web-app.md → doc/codelabs/getting-started/deploying-flask-web-app.md
View File

@ -4,20 +4,19 @@ In this chapter, we will deploy our registered docker image on `hscloud` as a si
## Requirements
Registered image from [Building web app](building-web-app.md):
```
https://registry.k0.hswaw.net/$hs_username/myflask:latest
```
Registered image from [Building web app](building-web-app.md). Also, built `hscloud` environment from [Building an environment](prepare-environment.md) section.
## Steps
We create a `prod.jsonnet` file in location `//personal/$hs_username/myflask/prod.jsonnet`:
We create a `prod.jsonnet` file in location `//personal/$hs_username/myflask/prod.jsonnet`.
The format of `jsonnet` is very similar to `json`, but allows the use of variables, functions, and the import of other files.
For further reference on `jsonnet` see [jsonnet.org](https://jsonnet.org/learning/tutorial.html).
```jsonnet
# Remember to replace $hs_username with your SSO username!
# The import is done from the `kube.libsonnet` file in the `kube` folder in the `hscloud` folder.
local kube = import "../../../kube/kube.libsonnet";
{
@ -26,9 +25,11 @@ local kube = import "../../../kube/kube.libsonnet";
cfg:: {
name: 'web-app',
# The hscloud configuration only allows the namespace in `personal-$hs_username` format.
namespace: 'personal-$hs_username',
# The hscloud configuration only allows the domain in `*.$hs_username.hscloud.ovh` format.
domain: 'web-app.$hs_username.hscloud.ovh',
image: 'registry.k0.hswaw.net/$hs_username/myflask:latest',
image: 'registry.k0.hswaw.net/$hs_username/myflask:2137',
},
ns: kube.Namespace(cfg.namespace),
@ -80,16 +81,23 @@ local kube = import "../../../kube/kube.libsonnet";
}
```
We log into the cluster:
```bash
hs_username=$USER # if your username is the same as your SSO username
prodaccess -username $hs_username
```
We can now deploy our application:
```bash
kubecfg update prod.jsonnet
```
The application should be available at `http://web-app.$hs_username.hscloud.ovh`. You will have to wait several seconds for the working HTTPS service.
The application should be available at `http://web-app.$hs_username.hscloud.ovh`. You will have to wait a few minutes for a working HTTPS service.
To remove the application, execute:
```bash
kubecfg delete prod.jsonnet
kubectl delete service test -n personal-$hs_username
```

9
doc/codelabs/getting-started/prepare-environment.md
View File

@ -27,7 +27,7 @@ chmod +x .git/hooks/commit-msg
## Steps
We can configure the environment using niix-shell. To do this, we install `nix`:
We can configure the environment using nix-shell. To do this, we install `nix`:
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
@ -46,14 +46,15 @@ bazel build //tools:install
bazel run //tools:install
```
Now we can request to grant us access to the hscloud cluster through the [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme) tool. In place of `$hs_username` insert the username in SSO hackerspace:
Now we can request to grant us access to the hscloud cluster through the [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme) tool.
In place of `$hs_username` insert the username in SSO hackerspace:
```bash
hs_username=$USER # if your username is the same as your SSO username
prodaccess -username $hs_username
```
If you do not have access to the cluster, contact [@q3k](q3k:hackerspace.pl) or [@inf](informatic:hackerspace.pl) within [Matrix](https://matrix.hackerspace.pl/).
If you do not have access to the cluster, contact someone within [Matrix #infra channel](https://matrix.to/#/#infra:hackerspace.pl).
To check if we have access to the cluster, we can run the command:
@ -81,4 +82,4 @@ kubectl -n personal-$hs_username delete pod foo
## Next step
Next step: [Run first service](run-first-service.md)
Next step: [Building Flask web app](building-flask-web-app.md)

103
doc/codelabs/getting-started/run-first-service.md
View File

@ -1,103 +0,0 @@
# Running a public service in hscloud
In this chapter, I will show you how to run an existing service that will be publicly available on the Internet.
## Requirements
Done steps from [**Prepare environment**](prepare-environment.md) chapter.
## Creating a copy of ldapweb
We start in the `hscloud` folder, with the `nix-shell` environment enabled. If you don't have your namespace in the `//personal` folder yet, we create it:
```bash
mkdir personal/$hs_username
```
We copy the configuration of the `ldapweb` service into the workspace:
```bash
cp -r hswaw/ldapweb/ personal/$hs_username/
cd personal/$hs_username/ldapweb/
```
## Modifying the service
The configuration of `ldapweb` is contained in the `prod.jsonnet` file. The format of `jsonnet` is very similar to `json`, but allows the use of variables, functions, and the import of other files.
We are interested in the initial part of the file:
```jsonnet
local kube = import "../../kube/kube.libsonnet"
{
local top = self,
local cfg = self.cfg,
cfg:: {
name: 'ldapweb',
namespace: 'ldapweb',
domain: 'profile.hackerspace.pl',
image: 'registry.k0.hswaw.net/radex/ldap-web:1695486391',
},
...
}
```
The import is done from the `kube.libsonnet` file in the `kube` folder in the `hscloud` folder. In order for the import to proceed correctly in this case, we need to go back one more folder: `../../../kube/kube.libsonnet`.
The `hscloud` configuration only allows the namespace in `personal-$hs_username` format. In addition, we need to change the domain to `*.$hs_username.hscloud.ovh`. Finally, we change the service name to `test`.
Finally, the above fragment of the `prod.jsonnet` file should look like this:
```jsonnet
# remember to replace $hs_username with your username!
local kube = import "../../../kube/kube.libsonnet";
{
local top = self,
local cfg = self.cfg,
cfg:: {
name: 'test',
namespace: 'personal-$hs_username',
domain: 'test.$hs_username.hscloud.ovh',
image: 'registry.k0.hswaw.net/radex/ldap-web:1695486391',
},
...
}
```
We log into the cluster:
```bash
hs_username=$USER # if your username is the same as your SSO username
prodaccess -username $hs_username
```
We invoke the command to apply the changes:
```bash
kubecfg update prod.jsonnet
```
Our service should be at `https://test.$hs_username.hscloud.ovh/`. During the first couple of minutes we will get a message about an invalid certificate, because the Let's Encrypt service has not yet managed to generate a certificate for our domain.
To remove the service, call:
```bash
kubecfg delete prod.jsonnet
```
or
```bash
kubectl delete service test -n personal-$hs_username
```
## Next step
[Building web app](building-web-app.md)

5
doc/codelabs/index.md
View File

@ -12,9 +12,8 @@ Getting started
- [**Your First Change**](getting-started/your-first-change.md) - how to use Gerrit and git to send your first change to hscloud, and an intro to personal directories. Using Gerrit can be somewhat confusing even (or especially) if you're used to Gitflow or GitHub.
- [**Bazel & Go basics**](getting-started/bazel-go.md) - will (TODO) guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own.
- [**Preparing kubernetes environment**](getting-started/prepare-environment.md) - how to build environment using `nix` and `bazel`, to be able to run first kubernetes pod.
- [**Creating test pod**](getting-started/run-first-service.md) - how to deploy first service from available image.
- [**Building web app**](getting-started/building-web-app.md) - how to prepare our first Flask app and register it on hscloud k8s registry.
- [**Deploying web app**](getting-started/deploying-web-app.md) - how to deploy our registed web app.
- [**Building web app**](getting-started/building-flask-web-app.md) - how to prepare our first Flask app and register it on hscloud k8s registry.
- [**Deploying web app**](getting-started/deploying-flask-web-app.md) - how to deploy our registed Flask web app on hscloud.
See also
--------