cheshire/hscloud-docs
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: cheshire:53b81426da59956e3c81e405a8c78dcfbe4abe8d
Branches Tags
cheshire:master
...
compare: cheshire:eec447a94eaa4e52bbb9e2bb5975c2684bfc2418
Branches Tags
cheshire:master

No commits in common. "53b81426da59956e3c81e405a8c78dcfbe4abe8d" and "eec447a94eaa4e52bbb9e2bb5975c2684bfc2418" have entirely different histories.
53b81426da ... eec447a94e

8 changed files with 54 additions and 472 deletions
Show stats Expand all files Collapse all files

36
01-prepare-docker.md
View file

@ -1,36 +0,0 @@
# Preparing Docker environment
We create a `Dockerfile`:
```Dockerfile
FROM ubuntu:22.04
RUN apt-get -y update
RUN apt-get -y install default-jre default-jdk python3-dev build-essential clang wget libpq-dev zip git
RUN wget https://github.com/bazelbuild/bazelisk/releases/download/v1.18.0/bazelisk-linux-amd64 -O /usr/bin/bazel
RUN chmod +x /usr/bin/bazel
RUN git clone "https://gerrit.hackerspace.pl/hscloud"
WORKDIR /hscloud
RUN groupadd appgroup && useradd -m -s /bin/bash -g appgroup appuser
RUN chown -R appuser:appgroup /hscloud
USER appuser
RUN bazel build //tools:install
RUN bazel run //tools:install
```
Now we run
```bash
docker build -t hscloud:test .
```
after build we can access terminal by:
```bash
docker run hscloud:test -it
```

30
01-prepare-nixos.md
View file

@ -1,33 +1,33 @@
# Compiling in a NixOS environment
# Kompilacja w środowisku NixOS
NixOS is an operating system that allows you to describe your environment declaratively. This chapter describes the steps needed to build an environment in which cloud services can be built.
NixOS jest systemem operacyjnym, który pozwala na deklaratywne opisywanie środowiska. W tym rozdziale opisane są kroki potrzebne do zbudowania środowiska, w którym można budować usługi w chmurze.
This tutorial uses NixOS version 23.05.
W tym tutorialu została wykorzystana wersja NixOS 23.05.
The execution script available in [01-build-nixos.sh](01-build-nixos.sh) performs all the steps described in this chapter.
Skrypt wykonujący dostępny w [01-build-nixos.sh](01-build-nixos.sh) wykonuje wszystkie kroki opisane w tym rozdziale.
## Requirements
Całość opisu opiera się na informacjach uzyskanych z rozmów oraz z [dokumentacji użytkownika hscloud](https://code.hackerspace.pl/hswaw/hscloud/src/branch/master/cluster/doc/user.md).
Willingness to install NixOS, bare metal or virtually. Virtualization can be done with [VirtualBox](https://www.virtualbox.org/), for example.
## Wymagania
## Steps
Chęć do zainstalowania NixOSa, bare metal lub wirtualnie. Wirtualizacja może być wykonana np. za pomocą [VirtualBox](https://www.virtualbox.org/).
Download NixOS from [nixos.org](https://nixos.org/download.html#nixos-iso) and install it on your machine.
## Kroki
We need to install the `git` package and clone the repository with the source code of the cloud services. In the terminal we type:
Pobierz system NixOS z [nixos.org](https://nixos.org/download.html#nixos-iso) i zainstaluj go na swojej maszynie.
Potrzebujemy zainstalować pakiet `git` i sklonować repozytorium z kodem źródłowym usług w chmurze. W terminalu wpisujemy:
```bash
nix-env -iA nixos.git
git clone "https://gerrit.hackerspace.pl/hscloud"
git clone https://code.hackerspace.pl/hswaw/hscloud
cd hscloud
```
If we want to commit anything on gerrit, we have to do additional steps ([source](https://gerrit.hackerspace.pl/admin/repos/hscloud,general)):
Ze względu na drobny błąd, należy pozbyć się z `shell.nix` komendy kompilacji `clang`:
```bash
mkdir -p .git/hooks/
curl -Lo .git/hooks/commit-msg https://gerrit.hackerspace.pl/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg
sed -i '/gcc binutils clang/s/clang//g' "shell.nix"
```
Next step: [Build environment](02-build-environment.md)
Następny krok: [Budowa środowiska](02-build-environment.md)

41
01-prepare-ubuntu.md
View file

@ -1,41 +1,32 @@
# Compiling in an Ubuntu environment
# Kompilacja w środowisku Ubuntu
This chapter describes the steps needed to build an environment in which to build hscloud services. The instructions are modeled after [01-build-nixos.md](01-build-nixos.md), only with the additional step of downloading and installing the `nix` package manager.
W tym rozdziale opisane są kroki potrzebne do zbudowania środowiska, w którym można budować usługi w chmurze hscloud. Instrukcja wzoruje się na [01-build-nixos.md](01-build-nixos.md), jedynie z dodatkowym krokiem pobierania i instalacji menedżera pakietów `nix`.
## Requirements
## Wymagania
Administrator privileges, Ubuntu 22.04 or later environment, or a suitable Ubuntu-like desktop.
Uprawnienia administratora, środowisko Ubuntu 22.04 lub nowsze, bądź odpowiedni Ubuntu-like desktop.
## Steps
## Kroki
Install the `git` and `curl` packages:
Instalujemy pakiety `git` oraz `curl`:
```bash
sudo apt update
sudo apt install git curl
```
Clone the repository with the source code of the cloud services:
```bash
git clone "https://gerrit.hackerspace.pl/hscloud"
cd hscloud
```
If we want to commit anything on gerrit, we have to do additional steps ([source](https://gerrit.hackerspace.pl/admin/repos/hscloud,general)):
```bash
mkdir -p .git/hooks/
curl -Lo .git/hooks/commit-msg https://gerrit.hackerspace.pl/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```
We download and install the `nix` package manager (source: [nixos.org](https://nixos.org/download)):
Pobieramy i instalujemy menadżer pakietów `nix` (źródło: [nixos.org](https://nixos.org/download)):
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
```
After this operation, log out and log back in to use `nix`.
Po tej operacji należy wylogować się i zalogować ponownie, aby móc korzystać z `nix`.
Next step: [Build environment](02-build-environment.md)
Klonujemy repozytorium z kodem źródłowym usług w chmurze:
```bash
git clone https://code.hackerspace.pl/hswaw/hscloud
cd hscloud
```
Następny krok: [Budowa środowiska](02-build-environment.md)

48
02-build-environment.md
View file

@ -1,66 +1,52 @@
# Building an environment
# Budowa środowiska
In this chapter, I will describe how to build an environment on an already prepared platform (NixOS, Ubuntu, etc.) in which we will build hscloud services.
W tym rozdziale przedstawię, jak na przygotowanej już platformie (NixOS, Ubuntu, etc.) zbudować środowisko, w którym będziemy budować usługi w chmurze hscloud.
The description is based on information obtained from conversations with @inf and from [hscloud user documentation](https://code.hackerspace.pl/hswaw/hscloud/src/branch/master/cluster/doc/user.md).
## Kroki
## Requirements
Working nix. You can install nix with command:
Ze względu na drobny błąd, należy pozbyć się z `shell.nix` komendy kompilacji `clang`:
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
sed -i '/gcc binutils clang/s/clang//g' "shell.nix"
```
We create the environment in which we will build services. To do this, we create the environment based on the definitions in the `shell.nix` file:
Tworzymy środowisko, w którym będziemy budować usługi. W tym celu tworzymy środowisko na podstawie definicji w pliku `shell.nix`:
```bash
nix-shell
```
We now use the `bazel` tool to build and run the necessary services, including `prodaccess` and `kubectl`:
Używamy teraz narzędzia `bazel`, aby zbudować i uruchomić potrzebne usługi, m.in. `prodaccess` oraz `kubectl`:
```bash
bazel build //tools:install
bazel run //tools:install
```
## Steps
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:
Teraz możemy poprosić o przyznanie nam dostępu do klastra hscloud poprzez narzędzie [prodaccess](https://pkg.go.dev/code.hackerspace.pl/hscloud/cluster/prodaccess#section-readme). w miejsce `$hs_username` należy wstawić nazwę użytkownika w SSO hackerspejsu:
```bash
hs_username=$USER # if your username is the same as your SSO username
prodaccess -username $hs_username
prodaccess -u $hs_username
```
If you do not have access to the cluster, contact [Matrix](https://matrix.hackerspace.pl/) within [@q3k](q3k:hackerspace.pl) or [@inf](informatic:hackerspace.pl).
W przypadku braku dostępu do klastra, należy skontaktować się w ramach [Matrix](https://matrix.hackerspace.pl/) z [@q3k](q3k:hackerspace.pl) bądź z [@inf](informatic:hackerspace.pl).
To check if we have access to the cluster, we can run the command:
Aby sprawdzić, czy mamy dostęp do klastra, możemy wykonać polecenie:
```bash
# shows the Kubernetes version
# pokazuje wersję Kubernetesów
kubectl version
# shows the statistics of the cluster
# pokazuje statystyki klastra
kubectl top nodes
```
We can also call the public Docker image (again, in place of `$hs_username`, insert the username in SSO hackerspace):
Możemy również wywołać publiczny obraz Dockera (ponownie, w miejsce `$USER` należy wstawić nazwę użytkownika w SSO hackerspejsu):
```bash
# to create an instance of (sub) alpine
# aby utworzyć obraz
kubectl -n personal-$hs_username run --image=alpine:latest -it foo
```
If you want to delete the instance, run:
```bash
# to delete an instance (sub) of alpine
# aby skasować obraz
kubectl -n personal-$hs_username delete pod foo
```
## Next step
Next step: [Create http service](03-create-service.md)
```

117
03-create-service.md
View file

@ -1,117 +0,0 @@
# Creating a public service in hscloud
In this chapter, I will show you how to create a service that will be publicly available on the Internet.
## Requirements
Working nix. You can install nix with command:
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
```
and start it with:
```bash
nix-shell
bazel build //tools:install
bazel run //tools:install
```
## Creating a copy of ldapweb
We start by enabling the nix-shell environment:
```bash
cd hscloud
nix-shell
```
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 (remember to replace `$hs_username` with your username!):
```jsonnet
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
```

126
04-build-web-app.md
View file

@ -1,126 +0,0 @@
# Building your own Flask web service
In this chapter, we will build our own web service using the Flask framework, dockerize it and register it in the registry.
## Requirements
Working nix. You can install nix with command:
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
```
and start it with:
```bash
nix-shell
bazel build //tools:install
bazel run //tools:install
```
You will require `docker` in this example. Install it from your standard shell.
```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.
## Steps
We create a simple Flask application:
```py
# app.py
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
return 'Hello, World!'
if __name__ == '__main__':
app.run()
```
We can check if the application works by running it:
```bash
pip3 install flask
python3 app.py
```
Now we create `Dockerfile` file for our application:
```Dockerfile
# Use an official Python runtime as a base image
FROM python:3.8-slim-buster
# Set the working directory in docker
WORKDIR /app
# Copy the current directory contents into the container at /app
COPY . /app
# Install any needed packages specified in requirements.txt
RUN pip install --upgrade pip && \
pip install flask gunicorn
# Set environment variables
ENV FLASK_APP=app.py
ENV FLASK_RUN_HOST=0.0.0.0
# Expose port 5000 for the Flask app to listen on
EXPOSE 5000
# Define command to run the application using gunicorn
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
```
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:
```
https://registry.k0.hswaw.net
```
You should get command similar to:
```
docker login -u $hs_username -p *************** https://registry.k0.hswaw.net
```
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
```
To remove the image from the registry, you can use:
```bash
docker rmi registry.k0.hswaw.net/$hs_username/myflask:latest
```

107
05-deploy-web-app.md
View file

@ -1,107 +0,0 @@
# Deploying docker image on hscloud
In this chapter, we will deploy our registered docker image on hscloud as a simple HTTP kube service with HTTPS from Let's Encrypt.
## Requirements
Working nix. You can install nix with command:
```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
```
and start it with:
```bash
nix-shell
bazel build //tools:install
bazel run //tools:install
```
inside `hscloud` repo.
We need a registered docker image in the registry. If you don't have one, you can create it by following the [Building your own Flask web service](04-build-web-app.md) chapter. We also need a running `prodaccess` authorization (details: [Building environment](02-build-environment.md)).
## Steps
We create a `prod.jsonnet` file in location `//personal/$hs_username/myflask/prod.jsonnet`:
```jsonnet
# Remember to replace $hs_username with your SSO username!
local kube = import "../../../kube/kube.libsonnet";
{
local top = self,
local cfg = self.cfg,
cfg:: {
name: 'web-app',
namespace: 'personal-$hs_username',
domain: 'web-app.$hs_username.hscloud.ovh',
image: 'registry.k0.hswaw.net/$hs_username/myflask:latest',
},
ns: kube.Namespace(cfg.namespace),
deployment: top.ns.Contain(kube.Deployment(cfg.name)) {
spec+: {
replicas: 1,
template+: {
spec+: {
containers_: {
default: kube.Container("default") {
image: cfg.image,
ports_: {
http: { containerPort: 5000 },
}
},
},
},
},
},
},
service: top.ns.Contain(kube.Service(cfg.name)) {
target_pod:: top.deployment.spec.template,
},
ingress: top.ns.Contain(kube.Ingress(cfg.name)) {
metadata+: {
annotations+: {
"kubernetes.io/tls-acme": "true",
"cert-manager.io/cluster-issuer": "letsencrypt-prod",
"nginx.ingress.kubernetes.io/proxy-body-size": "0",
},
},
spec+: {
tls: [ { hosts: [ cfg.domain ], secretName: cfg.name + "-tls" } ],
rules: [
{
host: cfg.domain,
http: {
paths: [
{ path: "/", backend: top.service.name_port },
],
},
},
],
},
},
}
```
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.
To remove the application, execute:
```bash
kubecfg delete prod.jsonnet
```

21
README.md
View file

@ -1,21 +1,12 @@
# hscloud-docs
Introduction to creating services in hscloud. This set of documents is intended to document the process of biting into the operation of the cloud.
Wprowadzenie do tworzenia usług w hscloud. Niniejszy zestaw dokumentów ma na celu dokumentację procesu wgryzania się w działanie chmury.
## Preparing the environment
## Przygotowanie środowiska
- [Building on NixOS](01-prepare-nixos.md)
- [Building on Ubuntu](01-prepare-ubuntu.md)
- [Budowa na NixOS](01-prepare-nixos.md)
- [Budowa na Ubuntu](01-prepare-ubuntu.md)
## Preparing tools
## Przygotowywanie narzędzi
- [Building environment](02-build-environment.md)
## Deploying a sample service
- [Deploying the ldapweb service](03-create-service.md)
## Building own service
- [Building a simple Flask web application](04-build-web-app.md)
- [Deploying docker image on hscloud](05-deploy-web-app.md)
- [Budowa środowiska](02-build-environment.md)