| Key | Value |
|---|---|
| Version | 0.6.0 |
| Source | https://github.com/VNG-Realisatie/zgw-infra |
| Keywords | ZGW, kubernetes, helm |
| Related | https://github.com/VNG-Realisatie/gemma-zaken |
Om het zaakgericht werken in de Common Ground architectuuur te ondersteunen zijn de API's voor Zaakgericht werken ontwikkeld.
Hierbij een omschrijving wat er moet gebeuren wanneer je de helm chart wilt gebruiken op een lokaal en het productie systeem. Let er op dat deze omschrijving(en) gedaan zijn vanuit macos en er daarmee vanuit gaan dat je een terminal hebt en weet hoe je deze gebruikt.
Windows wordt hierin NIET meegenomen. Wanneer je toch Windows gebruikt wordt het aangeraden WSL te gebruiken zodat alle commando's vanuit een linux omgeving gedraaid kunnen worden.
Volg de insctructies op (login via gitlab nodig!):
De eerste stap om de helm chart te draaien is uiteraard het opzetten van een kubernetes cluster en een lokale versie van helm.
Het is aan de raden een helm versie van >= 3.8 te nemen omdat deze het toestaat helm charts als oci te downloaden.
Voor helm zie:
https://github.com/helm/helm/releases https://helm.sh/docs/intro/install/
Hoe je kubernetes lokaal draait hangt af van je systeem maar gemakshalve worden hier alleen minikube en docker-desktop behandeld.
Docker-desktop is de standaard om kubernetes te draaien op MacOs en Windwos (via een VM). Doordat docker-desktop een gui heeft is het voldoende docker-desktop te starten.
Docker-desktop heeft geen eigen ingress dus deze moet je instellen. Hiervoor zit in de Makefile een commando:
make -C helm/ri nginx_install minikube start --cpus 2 --memory 4000 --driver=hyperkit --container-runtime=docker
minikube addons enable ingress
minikube ip
eval $(minikube docker-env)Deze commando's starten een minikube cluster met docker en hyperkit. Er zijn veel varianten mogelijk dus dit dient louter als voorbeeld. Zie bijvoorbeeld minkube.
Zorg dat je ingress activeert en het ip-adres van minikube opvraagt (minikube draait immers in een virtuele machine met een eigen IP). Het IP heb je nodig in de ingress stap.
Mocht je lokaal images willen gebruiken dient de Makefile in de root als voorbeeld (minikube staat toe images van lokaal naar de VM te "loaden").
Hierna kun je aan de slag!
Voor je de helm chart installeert is het nodig een namespace te maken. Deze staat standaard op zgw maar is aan te passen in de values.yaml.
Onderstaand commando gaat uit van de standaard:
kubectl create ns zgwDe parser is een python script die voor lokaal gebruik een config opbouwt in de values.yaml.
De env.yaml wordt gebruikt om een configuratie te laden. Standaard wordt local genomen maar deze is eenvoudig te overschrijven door:
export ENV=productionte zetten. Of eventueel mee te geven in PyCharm. Laat deze variable echter weg voor lokaal of zet hem expliciet op local:
export ENV=localDaarna is het eenvoudig een kwestie van:
cd ./parser
pip install -r requirements.txt
python3 parser.pyAls je een nieuwe config hebt gemaakt met de parser kun je de helm chart installeren.
cd ./helm/ri-zgw
helm install ri-zgw .Het duurt ongeveer 3 minuten voordat alle services up and running zijn. Grofweg zijn er aantal stappen die elke service doorgaat:
- wachten tot de database beschikbaar is
- aanmaken van de database
- migrate van de schemas
- seeden van initiële data
- opstarten van de service
Als de installatie wilt verwijderen kun je het volgende commando gebruiken:
cd ./helm/ri-zgw
helm delete ri-zgwAl deze commando's zijn ook teurg te vinden in de ./helm/ri-zgw/Makefile
Het is ook mogelijk om direct een test of productie image te draaien. Zoals hieronder beschreven gebruiken we OCI voor het opslaan de helm charts.
helm install ri-zgw oci://ghcr.io/vng-realisatie/ri-zgw-test --version 0.0.29 --set global.config.createSecret=true --set global.namespace=zgwhelm install ri-zgw oci://ghcr.io/vng-realisatie/ri-zgw --version 0.1.1 --set global.config.createSecret=trueHet is belangrijk dat je de regel --set global.config.createSecret=true laat staan. Lokaal bestaan de secrets niet en in de prod en test helm charts bestaan deze juist wel.
Alle image tags zijn aan te passen in ./parser/env.yaml deze versie worden door de parser opgepakt en in alle helm charts verspreid.
Wanneer er dus een productie release plaats moet vinden zijn er de volgende stappen.
Voorbeeld. ZRC gaat naar versie 10.1.231.
git checkout -b release/summer-timePas dan de versie aan in ./parser/env.yaml :
zrc:
repo: ghcr.io/vng-realisatie/zaken-api
local:
tag: pr-267
ingressHost: k8s-zrc-local.test
test:
tag: sha-279ce65
ingressHost: zaken-api.test.vng.cloud
production:
tag: 10.1.231
ingressHost: zaken-api.vng.cloudHierna moet je de gitflow volgen: commit - push - pull request - merge naar main.
Als dit op main staat kun je via github (of de cli) een nieuwe release aanmaken vanaf main.
Hierna wordt de versie automatisch uitgerold (zie hieronder).
Op productie hebben wij momenteel 2 omgevingen zgw-test en zgw waarbij de laatste de prod omgeving is.
zgw-test is verbonden aan de OCI ri-zgw-test - https://github.com/VNG-Realisatie/zgw-infra/pkgs/container/ri-zgw-test
zgw is verbonden aan de OCI ri-zgw - https://github.com/VNG-Realisatie/zgw-infra/pkgs/container/ri-zgw
Doordat alles wat wij hebben in flux staat heb je met dit gedeelte als het goed is weinig te maken. Elke 5 minuten wordt er vanuit flux gekeken of er een nieuwe OCI aanwezig is.
Wanneer deze gevonden is wordt deze automatisch gedeployed.
Voor voorbeelden en verdere beschrijvingen zie:
./flux
en
./flux/README.md
Voor meer details zie ook GHCR.
Wanneer er een PR wordt gemaakt zal hier een helm chart voor worden gebouwd en gepushed als OCI naar:
https://github.com/VNG-Realisatie/zgw-infra/pkgs/container/ri-zgw-test
Wil je iets aan de versies aanpassen dan moet dat in parser.py:
if env == "test":
if stripped == "":
# GITHUB_REF_NAME contains the PR number
branch = os.getenv("GITHUB_REF_NAME")
version = branch.split("/")[0]
semver = f"0.{version}.0"
stripped = semverversion is hier het versie nummer van de PR. Doordat deze uniek is opgehoogd wordt wordt eer altijd een nieuwe OCI gebouwd. Door dit schema is het wel zo dat deze altijd major en patch 0 hebben.
Wanneer er een release wordt gemaakt van zgw-infra repo wordt er automatisch een nieuwe helm chart gebouwd en opgeslagen in GHCR als OCI.
https://github.com/VNG-Realisatie/zgw-infra/pkgs/container/ri-zgw
Wil je iets aan de versies aanpassen dan moet dat in parser.py:
if env == "production":
if stripped == "":
# GITHUB_REF_NAME is the name of a release when using github
branch = os.getenv("GITHUB_REF_NAME")
stripped = branchstripped is hierin de naam van de release die gedaan is. Dit is dan ook de versie van de helm chart. Hierdoor is productie altijd gelinkt aan de releases van zgw-infra:
https://github.com/VNG-Realisatie/zgw-infra/releases
.github/workflows/ci.ymlImages gemaakt tijdens het cicd proces kunnen gepulled worden als OCI. De version kan weggelaten worden voor een latest variant.
helm pull oci://ghcr.io/vng-realisatie/ri-zgw --version 0.0.6Hiermee wordt de productie versie van de helm chart lokaal neergezet. LET OP hierbij zit uiteraard geen parser!
Om lokaal je ingress in te stellen moeten de dns entries uit de env.yaml ook toegevoegd worden aan je /etc/hosts afhankelijk van je kubernetes implementatie.
Wederom wordt er hier uitgegaan van minikube en docker-desktop
De ingress van docker-desktop is normaliter te benaderen via localhost.
Onderstaand commando gaat uit van de standaard lokale records zoals beschreven in env.yaml. Let op hiervoor zijn sudo rechten nodig!
export ADDR=127.0.0.1
echo "# RI ingress points
${ADDR} k8s-ac-local.test
${ADDR} k8s-brc-local.test
${ADDR} k8s-contactmomenten-local.test
${ADDR} k8s-drc-local.test
${ADDR} k8s-klanten-local.test
${ADDR} k8s-nrc-local.test
${ADDR} k8s-tokens-local.test
${ADDR} k8s-verzoeken-local.test
${ADDR} k8s-vrl-local.test
${ADDR} k8s-zrc-local.test
${ADDR} k8s-ztc-local.test" | sudo tee -a /etc/hostsWanneer je minikube gebruikt dient 127.0.0.1 vervangen te worden door het ip van minikube op te vragen via:
minikube ipIn je browser kun je nu de RI benaderen op bijvoorbeeld:
http://k8s-ac-local.test
Het bewaken en uitrollen van secrets is altijd een uitdaging maar hier is gekozen voor kubeseal.
Voor installatie zie:
https://github.com/bitnami-labs/sealed-secrets#helm-chart
en
./flux/README.md
Deze folder bestaat uit legacy manieren om lokaal en op kubernetes te deployen. Deze zouden NIET meer gebruikt moeten worden.