# NLX Helm installatiehandleiding Dashkube

[TOC]

# Introductie

Let op: Deze handleiding is gemaakt met de intentie om NLX omgeving op te zetten op [dashkube](https://www.dashkube.com/) die met de demo omgeving van NLX verbindt. Deze omgeving is niet voor productie doeleinden.

In deze handleiding werken we toe naar het aanbieden van een API via een NLX inway. We regelen toegang tot die API en vervolgens bevragen we jouw API met een client via een NLX outway. Alle NLX componenten worden op een Kubernetes [(Haven)](https://haven.commonground.nl) cluster geinstalleerd.

# Stappenplan

1. Voorbereiding
2. PostgreSQL installeren
3. Certificaten aanmaken
4. NLX Management installeren
5. NLX Inway installeren
6. NLX Outway installeren
7. Voorbeeld API installeren en aanbieden
8. API benaderen via een client

# 1. Voorbereiding

De voorbereiding is een eenmalig onderdeel van de NLX installatie dat hergebruikt wordt voor het neerzetten van Management, Inway(s) en Outway(s).

## Cluster

Een Kubernetes cluster, minimaal versie v1.18.0. Als u deze training volgt via conduction ontvangt u credentials voor een cluster.

**Zorg er voor dat kubectl voor de duur van deze handleiding verbindt met het juiste cluster**

## Domeinnamen

Zorg dat je over een domeinnaam beschikt die gebruikt kan worden om de NLX inway publiek beschikbaar te maken. De inway, die je zal installeren, zal op jouw Kubernetes cluster een loadbalancer aanmaken. Het is belangrijk dat er verkeer richting deze loadbalancer wordt toegestaan (wellicht zijn er firewall regels?). Het domein dat je wilt gaan gebruiken voor jouw inway moet verwijzen naar het IP van deze loadbalancer. Daarnaast is er ook een domein nodig voor NLX management. Dit domein moet verkeer routeren richting jouw Kubernetes cluster.

Voor trainingsdoeleinden kan gebruik worden gemaakt van een .common-ground.nu domien, deze moeten handmatig worden toegevoegd. Behoeft aan een commonroung.nu domein? Neem contact op met [[e-mail]](mailto:[e-mail]) Bij het voorbereiden van de training is het nog niet nodig om een domein naam te hebben.

## Werk directory / Folder

Tijdens het volgen van deze installatie handleiding zal je meerdere malen gevraagd worden om bestanden te downloaden of te wijzigen. We gaan er in deze handleiding vanuit dat je al deze bestanden in dezelfde directory opslaat en vanuit deze directory met de terminal de commandos uitvoert.

mkdir jouw-werk-directory
cd jouw-werk-directory

## Voorbeelden en bestanden

De in deze training gebruikte voorbeelden en bestanden kunt u terugvinden in de [git repository](https://github.com/ConductionNL/nlx-training) van deze training.

## Tooling

* [Kubectl, versie minimaal v1.19.0](https://v1-18.docs.kubernetes.io/docs/tasks/tools/install-kubectl/)
* [Helm, minimaal v3.2.0](https://helm.sh/docs/intro/install/)
* [Homebrew package manager](https://brew.sh) **(alleen nodig voor MacOS gebruikers)**
* [Openssl](https://www.openssl.org/source/)
**MacOS gebruikers**
Openssl op Mac OS is niet geschikt om V3 CA certificaten mee te maken. Daarom alleen voor Mac OS gebruikers:` brew install openssl@1.1`
**Windows gebruikers**
Installeer OpenSSL met het volgende commando: `choco install OpenSSL.Light`
* [Git](https://git-scm.com/docs/git-archive)
* [Dashkube](https://www.dashkube.com/)
* [ID-Vault](id-vault.com)

Let er bij het uitvoeren van commandline opdrachten op een windows machine via Opdrachten propmt altijd op dat u deze als administator uitvoert (rechts klikken op opdrachten promt en klikken op uitvoeren als administrator)

## Dashkube

Dashkube is een online interface voor het beheren van Kubernetes en daarmee ook haven omgevingen, als u een NLX training volgt via [conduction](conduction.nl) wordt er een omgeving voor u aangemaakt. U ontvangt aan het begin van de training een uitnodiging voor een acount met admin rechten op dit cluster, deze rechten worden na de training weer ingetrokken.

### ID-Vault

Voor inlog doeleinden maakt dashkube gebruik van [id-vault](id-vault.com) u ontvang dan ook vanuit deze website een e-mail met het verzoek te te treden tot een organisatie.

## Basis bestanden ophalen
Haal nu de benodigde basis bestanden op je kunt deze terug vinden in deze repro in de map [bestanden](https://github.com/ConductionNL/nlx-training/tree/master/bestanden), kopier deze naar de folder die je op je computer hebt aangemaakt.

## Namespace

Voor deze training maken we gebruik van je voornaam als namespace op je cluster (zodat we met meerdere mensen tegelijkertijd op een cluster kunnen werken). We hoeven geen losse namespace aan te maken, op dashkube is dit een optioneel onderdeel van het installatie procces.

Voor deze training gebruiken we `<voornaam>-nlx`

## Kubeconfig

Er zijn een aantal manieren om vanaf je computer connectie te maken met een kubernetes clusters, voor deze training gebruiken we een kubeconfig bestand. Dat bevat naast de sleutels voor een cluster ook de benodige connectie gegevens zo als ip addres.

Je kan de kubeconfig voor je cluster downloaden via het dashkube dashboard door op je cluster te klikken en vervolgens naar "details" te gaan. De knop download kubeconfig staat vervolgens rechts onder aan. Plaats de kubeconfig in de zelfde maps als je basis bestanden.

# 2. PostgreSQL installeren

In plaats van met Helm op onze eigen computer installeren we Postgres via Dashkube. Als we het cluster openen, gaan we naar installations en klikken op "Add softare", vervolgens zoeken we op postgresql. Als we bitnami postgresql gevonden hebben, openen we het venster ‘Install’ en passen het veld ‘namespace’ aan naar onze eigen namespace `<voornaam>-nlx`. Daarna voegen we in het tabblad ‘Values’ het veld postgresqlDatabase toe met de waarde postgresqlDatabase=nlx_management (zodat NLX onze database herkend).

# 3. Extern certificaat aanmaken

Verkeer tussen organisaties vindt plaats via een extern certificaat. Voor de NLX demo-omgeving kun je eenvoudig een certificaat aanmaken met het certificaat portaal.

Genereer een private key en certificaatverzoek voor de organisatie met:

openssl req -utf8 -nodes -sha256 -newkey rsa:4096 -keyout org.key -out org.csr

Je moet nu een reeks vragen beantwoorden. Hieronder zie je een voorbeeld van hoe jij deze vragen kan invullen. Als het antwoord `<overslaan>` is dan kan je deze vraag overslaan door op enter te drukken.

- Country Name (2 letter code) []: NL
- State or Province Name (full name) []: Noord holland
- Locality Name (eg, city) []:  Haarlem
- Organization Name (eg, company) []: mijn-organisatie 
  (bewaar deze want die hebben we later nog nodig)
- Organizational Unit Name (eg, section) []: <overslaan>
- Common Name (eg, fully qualified host name) []: 
  (hostnaam waarop jouw inway bereikbaar is), bijvoorbeeld: 
  <voornaam>inway.nlx-enableu.commonground.nu
- Email Address []: <overslaan>
- A challenge password []: <overslaan>

Er is nu een CSR aangemaakt (Certificate signing request)
Controleer de inhoud met het volgende commando

openssl req -in org.csr -text

Het resultaat moet er soort gelijk uitzien.

Subject: C=NL, ST=Noord holland, L=Haarlem, O=mijn-organisatie, CN=inway.mijn.organisatie.nl

Print de inhoud van het CSR naar de terminal met onderstaande commando's op open deze vanuit de folder met kladbok :

cat org.csr

of voor windows gebruikers zonder powershell

type org.csr

Kopieer het CSR vanuit de terminal inclusief '-----BEGIN CERTIFICATE REQUEST-----' en '-----END CERTIFICATE REQUEST-----'

Open nu het [NLX Certificaat Portaal](https://certportal.demo.nlx.io/) en plak de inhoud van het CSR in het tekstveld. Klik in het portaal op `Request Certifcate` om jouw certificaat aan te vragen.

Als dit gelukt is zie je onder aan de pagina `Download certificate ` staan,

klik hier op en sla het certificaat op als **org.crt** jouw werkdirectory

Controleer `org.crt` is aangemaakt met:

ls

## Extern certificaat installeren
Maak vervolgens een Secret aan met:

kubectl create secret tls external-tls --cert=org.crt --key=org.key --namespace=<voornaam>-nlx --kubeconfig=kubeconfig.conf

Jouw certificaat bestaat nu als Secret in Kubernetes. Deze Secret gaan we later in deze handleiding gebruiken als we NLX management en de NLX inway gaan installeren. Plaats hem daarom in de zelfde map als je basis bestanden en kubeconfig.

## Intern certificaat installeren
Pas in het bestand internal-tls.yaml [namespace] aan door het te vervangen door onze eigen namespace `<voornaam>-nlx`

Voer het volgende commando uit om het interne certificaat voor NLX management te installeren op het Kubernetes cluster

kubectl -n <voornaam>-nlx apply -f management-internal-tls.yml --kubeconfig=kubeconfig.conf

# 4. NLX Management installeren

We gaan nu NLX management installeren. NLX management is een web interface waarmee een NLX installatie beheerd kan worden.

## NLX management chart

Als we het cluster openen, gaan we naar installations en klikken op "Add softare", vervolgens zoeken we op nlx-management.
Als we NLX Management gevonden hebben, openen we het venster ‘Install’ en passen het veld ‘namespace’ aan naar onze eigen namespace.

Vervolgens openen we het tabblad ‘Values’, en maken de volgende aanpassingen:
In de categorie tls moeten we de volgende velden aanpassen:
- tls.organization.existingSecret: external-tls
- tls.internal.existingSecret: <namespace>- nlx-internal-tls
- tls.organization.rootCertificatePEM: regel 2 van het bijgeleverde bestand roots.txt
- tls.internal.rootCertificatePEM: regel 5 van datzelfde bestand

In de categorie config moeten we de volgende velden aanpassen:
- config.directoryInspectionHostname: directory-inspection-api.demo.nlx.io
- config.directoryRegistrationHostname: directory-registration-api.demo.nlx.io

In de categorie postgresql passen we de volgende velden aan:
- postgresql.database: ‘nlx_management’
- postgresql.hostname: postgresql
- postgresql.sslMode: disable
- postgresql.username: postgres
- postgresql.password: het wachtwoord van postgres, op te vragen met het volgende commando: kubectl get secret --namespace <namespace> postgresql -o jsonpath="{.data.postgresql-password}" | base64 –decode

In de categorie ingress passen we de volgende velden aan:
- ingress.enabled: true
- ingress.class: nginx
Vervolgens moeten we onderaan de volgende velden toevoegen:
- config.enableBasicAuth: true
- ingress.annotations.cert-manager\.io/cluster-issuer: letsencrypt-prod
- ingress.hosts[0]: <voornaam>.nlx-enableu.commonground.nu
- ingress.tls[0].secretName: nlx-management-ingress.tls
- ingress.tls[0].hosts[0]: <voornaam>.nlx-enableu.commonground.nu

## NLX management administrator aanmaken

In plaats van het uitvoeren van de in de handleiding gevolgde procedure openen we nu in Dashkube de NLX management-installatie en klikken op 'Bash' in het menu. Er opent nu een bash scherm waarmee we commando's kunnen uitvoeren op de container. In het invoerveld voeren we dan het volgende commando in (waarin we de gegevens tussen <> aanpassen naar de gewenste gegevens):

nlx-management-api create-user --email <[e-mail]> --password <password> --role admin

Er is nu een administator account aangemaakt die je kan gebruiken om in te loggen in NLX management.

Open NLX management en log in met de volgende gegevens (danwel met de door jou aangepaste gegevens)

email: [e-mail]
password: password

# 5. NLX Inway installeren

## Intern certificaat installeren
We gaan de cert manager gebruiken die we eerder hebben geinstalleerd om een intern certificaat aan te maken.

Voer het volgende commando uit om het certificaat te installeren op het Kubernetes cluster

kubectl -n <voornaam>-</voornaam>nlx apply -f inway-internal-tls.yaml

## Inway chart installeren
Hier wijken we af van de gevolgde procedure door Dashkube te gebruiken in plaats van helm op onze eigen computer.
Als we het cluster openen, gaan we naar installations en klikken op "Add softare", vervolgens zoeken we op nlx-inway.
Als we NLX Inway gevonden hebben, openen we het venster ‘Install’ en passen het veld ‘namespace’ aan naar onze eigen namespace.
Vervolgens openen we het tabblad ‘Values’, en maken de volgende aanpassingen:

In de categorie TLS passen we de volgende velden aan:
- tls.internal.existingSecret: <namespace>- nlx-internal-tls
- tls.internal.rootCertificatePEM: regel 5 van het bijgeleverde bestand roots.txt
- tls.organization.existingSecret: external-tls
- tls.organization.rootCertificatePEM: regel 2 van het bijgeleverde bestand roots.txt

In de categorie config passen we de volgende velden aan:
- config.name: <naam>-inway
- config.selfAddress: het adres dat we in Extern certificaat aanmaken (hoofdstuk 2) als common name hebben gebruikt, aangevuld met :443
- config.managementAPI.address: nlx-management-api.<namespace>.svc.cluster.local:443
- config.directoryRegistrationHostname: directory-registration-api.demo.nlx.io

In de categorie transactionLog passen we het volgende veld aan:
- transactionLog.enabled: false

Controlleer via je overzichts dashboard of de inway goed geinstaleerd is en "up" is, ga vervolgens ter verificatie van de correcte werking van de Inway naar NLX management en kijk of daar jouw inway (met de naam die je inkozen had) in jouw lijst van inways staat.

## Domein koppelen aan jouw inway

Voer het volgende commando uit:

kubectl get -n <voornaam>-nlx svc

In het resultaat zie je een service staan voor de Inway genaamd `nlx-inway`. Kopieer de waarde die staat bij `EXTERNAL-IP` en koppel dit IP adres aan jouw inway domein. Als je deze training via conduction volgt geef het ip addres dan door aan de trainer.

Na het koppelen van je domein voor je het volgende comando uit:

nslookup <het domein adres van jouw inway>

In het resultaat met het address gelijk zijn als het `EXTERNAL-IP` van de service `nlx-inway`

*** let op het kan enige tijd duren voordat het domein gekoppeld is. Je kan gewoon verder gaan met deze handleiding, maar uiteindelijk moet het domein wel gekoppeld zijn voordat je service benaderd kan worden via de inway ***

## Organisatie inway instellen
Al het verkeer rondom toegangsverzoeken, opdrachten etc loopt via de organisatie inway. Die moet je instellen in de instellingen pagina in NLX management. Daar selecteer je jouw inway als organisatie inway en bewaar je de nieuwe instellingen.

# 6. NLX Outway installeren

## Intern certificaat installeren
We gaan de cert manager gebruiken die we eerder hebben geinstalleerd om een intern certificaat aan te maken.

Voer het volgende commando locaal uit om het certificaat te installeren op het Kubernetes cluster

kubectl -n nlx apply -f outway-internal-tls.yaml --kubeconfig=kubeconfig.conf

## Outway chart installeren
Als we het cluster openen, gaan we naar installations en klikken op "Add softare", vervolgens zoeken we op nlx-outway.
Als we NLX Inway gevonden hebben, openen we het venster ‘Install’ en passen het veld ‘namespace’ aan naar onze eigen namespace `<voornaam>-nlx`.

Vervolgens openen we het tabblad ‘Values’, en maken de volgende aanpassingen:

De volgende velden moeten we aanpassen in de categorie tls:
- tls.organization.existingSecret: external-tls
- tls.internal.existingSecret: <voornaam>-nlx- nlx-internal-tls
- tls.organization.rootCertificatePEM: regel 2 van het bijgeleverde bestand roots.txt
- tls.internal.rootCertificatePEM: regel 5 van datzelfde bestand

Het volgende veld moeten we aanpassen in de categorie https:
- https.enabled: false

De volgende velden moeten we aanpassen in de categorie config:
- config.managementAPI.address: nlx-management-api.<voornaam>-nlx.svc.cluster.local:443
- config.directoryInspectionHostname: directory-inspection-api.demo.nlx.io

Het volgende veld moeten we aanpassen in de categorie transactionLog
- transactionLog.enabled: false

# 7. Voorbeeld API installeren en aanbieden

We zijn nu zo ver dat we een service via de nieuwe NLX Inway aan kunnen bieden. We hebben hiervoor een voorbeeld API beschikbaar die we gaan downloaden en installeren: 'basisregister-fictieve-kentekens'.

Download en installeer de Helm chart van de Basisregister Fictieve Kentekens als volgt:

git clone https://gitlab.com/commonground/nlx/nlx.git helm/deploy/rvrd/charts/basisregister-fictieve-kentekens

helm -n nlx upgrade --install brfk helm/deploy/rvrd/charts/basisregister-fictieve-kentekens

Controleer middels `kubectl -n nlx get pods` of de Service pod healthy wordt.

Een vergelijkbare regel zou nu te zien moeten zijn:

brfk-basisregister-fictieve-kentekens-6854dd6f86-rlqgk   1/1     Running     0          49s

## Voorbeeld API beschikbaar maken met NLX
Nu openen we NLX Management en gaan naar de Services pagina. Hier voegen we een service toe met de gele 'Service toevoegen' knop te klikken. Vul de volgende waarden in en bewaar de service:

- Servicenaam: basisregister-fictieve-kentekens
- API endpoint URL: http://brfk-basisregister-fictieve-kentekens

- Deze URL is niet publiek beschikbaar, maar wel bereikbaar door jouw inway.

- Inways: Vink hier jouw Inway aan

Wacht nu een minuut en controleer of je deze service terug kunt vinden in de directory in je NLX management.

# 8. API benaderen via een client

## Port forwarding instellen

Je hebt zojuist de NLX outway geinstalleerd. De outway is alleen bereikbaar vanuit het cluster. Om een verzoek te kunnen doen aan onze API via de outway moet de outway bereikbaar zijn vanaf je lokale machine. Daarvoor maak je een port forward aan.

Voordat we een port forward kunnen aanmaken hebben de naam van de outway pod nodig. Die kan je vinden door het volgende commando uit te voeren:

kubectl -n nlx get pods --kubeconfig=kubeconfig.conf

Je ziet nu een lijstje met daarin een regel die begint met `outway-nlx-outway-xxxxxxxxxxxx`. Kopieer die hele naam.

Open nu een nieuwe terminal venster en voer daarin de volgende stap uit:
- Vervang in het onderstaande commando `<naam van jouw outway pod>` door de naam die je zojuist hebt gekopieerd en voer het commando uit

kubectl -n nlx port-forward pod/<naam van jouw outway pod> 8080:8080 --kubeconfig=kubeconfig.conf

## Toegang vragen tot de service

Om jouw service te kunnen benaderen moet je toegang krijgen tot die service. Je biedt de service immers aan via NLX en dus beheer de toegang tot de service ook via NLX.

Toegang vragen en krijgen via NLX is heel gemakkelijk:
- Open in NLX Management de directory
- Selecteer de service `basisregister-fictieve-kentekens`.
- In het detail scherm wat nu open schuift zie je de gele knop 'Toegang aanvragen', klik hierop.
- Wacht even en ververs nu je browser een paar keer tot dat je de tekst "toegang aangevraagd" ziet.
- Nu moet je het toegangsverzoek accepteren door de service pagina te openen en daar op `basisregister-fictieve-kentekens` te klikken
- In het detail scherm wat open schuift zie je 'Toegangsverzoeken' staan.
- Klik hier op om de toegangsverzoeken te zien. Als het goed is zie je die van jezelf staan. Zo niet, dan weer even een paar de browser verversen.
- Je ziet nu jouw toegangsverzoek staan. Accepteer deze door op het blauwe vinkje te klikken. Als dit gelukt is dan moet jouw organisatie zichtbaar zijn onder het kopje "Organisaties met toegang".

Je hebt nu toegang.

## API bevragen

Door de port forwarding is je outway nu benaderbaar vanaf jouw lokale machine.

Vervang in het onderstaande commando:
- `<naam organisatie>` voor de organisatienaam die je in je externe certificaat hebt ingevuld (en bewaard als het goed is).

curl http://localhost:8080/<naam organisatie>/basisregister-fictieve-kentekens/voertuigen

Voer nu het aangepaste commando uit om de API via de NLX Outway te bevragen.

Na het uitvoeren van het commando moet je het volgende resultaat zien:

{"aantal":6,"resultaten":[{"burgerservicenummer":"663678651","datum_tenaamstelling":"29-01-2018","eerste_kleur":"GRIJS","europese_voertuigcategorie":"M1","handelsbenaming":"MAZDA 3","kenteken":"RT774D","merk":"MAZDA","voertuigsoort":"Personenauto"},{"burgerservicenummer":"425749708","datum_tenaamstelling":"16-11-2016","eerste_kleur":"GRIJS","europese_voertuigcategorie":"M1","handelsbenaming":"TOYOTA YARIS HYBRID","kenteken":"KN958B","merk":"TOYOTA","voertuigsoort":"Personenauto"},{"burgerservicenummer":"248496086","datum_tenaamstelling":"17-04-2009","eerste_kleur":"GRIJS","europese_voertuigcategorie":"M1","handelsbenaming":"CORSA-C","kenteken":"81HZFB","merk":"OPEL","voertuigsoort":"Personenauto"},{"burgerservicenummer":"187788248","datum_tenaamstelling":"15-06-2015","eerste_kleur":"GRIJS","europese_voertuigcategorie":"M1","handelsbenaming":"HEARSE","kenteken":"GJ713R","merk":"CADILLAC","voertuigsoort":"Personenauto"},{"burgerservicenummer":"581536630","datum_tenaamstelling":"13-07-2017","eerste_kleur":"BLAUW","europese_voertuigcategorie":"M1","handelsbenaming":"AGILA","kenteken":"50HSZS","merk":"OPEL","voertuigsoort":"Personenauto"},{"burgerservicenummer":"750461986","datum_tenaamstelling":"06-11-2000","eerste_kleur":"BLAUW","europese_voertuigcategorie":"M1","handelsbenaming":"SOVEREIGN HE","kenteken":"KS98DN","merk":"JAGUAR","voertuigsoort":"Personenauto"}]}

## API opzoeken in de NLX directory

Nlx houdt op [directory.demo.nlx.io](https://directory.demo.nlx.io/) een directory bij van alle op nlx beschikbare API's

---
Suggesties verbeteringen:

- Vertalen naar het Engels
- [Initiële poging om NLX met Helm te installeren](https://hackmd.io/zy3Ye9ezS363KK0hdzPf4Q)