Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore(localdev): add windows/wsl2 specific documentation #409

Merged
merged 4 commits into from
Aug 14, 2024
Merged

chore(localdev): add windows/wsl2 specific documentation #409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3559928
chore(localdev): enable tls and add windows specific documentation
ntruchsess Aug 9, 2024
a34a687
docs: change readme
evegufy Aug 13, 2024
a554c1b
chore: revert tls change
evegufy Aug 13, 2024
73ba347
chore: update readme
evegufy Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 158 additions & 35 deletions charts/localdev/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,32 @@ For detailed information about the default configuration values, please have a l

- [Usage](#usage)
- [Cluster setup](#cluster-setup)
- [Prepare network setup](#prepare-network-setup)
- [Linux and Mac](#cluster-setup-linux-and-mac)
- [Cluster Setup Windows](#cluster-setup-windows)
- [Minikube](#minikube)
- [Docker Desktop integrated Kubernetes](#docker-desktop-integrated-kubernetes)
- [Network Setup](#network-setup)
- [Minikube Addons](#minikube-addons)
- [Docker Desktop integrated Kubernetes Ingress Controller](#docker-desktop-integrated-kubernetes-ingress-controller)
- [Linux and Mac](#network-setup-on-linux-and-mac)
- [Additional Network Setup for Mac](#additional-network-setup-for-mac)
- [Windows/wsl2 with NTLM-proxy](#network-setup-on-windowswsl2-with-ntlm-proxy)
- [px-proxy](#px-proxy)
- [DNS-resolution in Windows](#dns-resolution-in-windows)
- [DNS-resolution in wsl2](#dns-resolution-in-wsl2)
- [Proxy-setup in wsl2](#proxy-setup-in-wsl2)
- [Install](#install)
- [Use released chart](#use-released-chart)
- [Use local repository](#use-local-repository)
- [Perform first login](#perform-first-login)
- [Database Access](#database-access)
- [Keycloak Admin Console](#keycloak-admin-console)
- [Uninstall](#uninstall)
- [Prepare self-signed TLS setup (Optional)](#1-prepare-self-signed-tls-setup-optional)
- [Prepare self-signed TLS setup (Optional)](#prepare-self-signed-tls-setup-optional)

## Usage

The following steps describe how to setup the umbrella chart into the namespace 'umbrella' of your started [**Minikube**](https://minikube.sigs.k8s.io/docs/start) cluster.
The following steps describe how to setup the umbrella chart into the namespace 'umbrella' of your started [**Minikube**](https://minikube.sigs.k8s.io/docs/start) or *Docker Desktop* integrated Kubernetes cluster.

> **Note**
>
Expand All @@ -49,32 +62,52 @@ The following steps describe how to setup the umbrella chart into the namespace

## Cluster Setup

### Linux & Mac
### Cluster Setup Linux and Mac

```bash
minikube start --cpus=4 --memory 6gb
```

### Windows
### Cluster Setup Windows

#### Minikube

For DNS resolution to work you need to either use `--driver=hyperv` option which requires administrator privileges:

```bash
minikube start --cpus=4 --memory 6gb --driver=hyperv
```

or use the native Kubernetes Cluster in *Docker Desktop* as well with a manual ingress setup:
#### Docker Desktop integrated Kubernetes

```bash
# 1. Enable Kubernetes under Settings > Kubernetes > Enable Kubernetes
# 2. Install an NGINX Ingress Controller
helm upgrade --install ingress-nginx ingress-nginx --repo https://kubernetes.github.io/ingress-nginx --namespace ingress-nginx --create-namespace
# 3. Skip the minikube addons and assume 127.0.0.1 for Cluster IP
*Docker Desktop* recommends the use of *wsl2* as backend:

- Settings > 'General'
- enable 'Use the WSL 2 based engine'
- enable 'Add the *.docker.internal names to the host's /etc/hosts file'
- Settings > 'Resources' > 'WSL integration'
- enable 'Enable integration with my default WSL distro'

recommended wsl2-settings:

c:\Users\\<username\>\\.wslconfig (for details see <https://learn.microsoft.com/en-us/windows/wsl/wsl-config>)

```text
[wsl2]
memory=10GB # Limits VM memory in WSL 2
processors=4 # Limits the number of virtual processors
swap=16GB # Sets the swap size
[experimental]
autoMemoryReclaim = gradual
```

> :warning: The rest of the tutorial assumes a minikube cluster, however.
- Enable Kubernetes under Settings > Kubernetes > Enable Kubernetes

- Skip the minikube addons

## Network Setup

## Prepare network setup
### Minikube Addons

In order to enable the local access via **ingress**, use the according addon for Minikube:

Expand All @@ -87,14 +120,26 @@ Make sure that the **DNS** resolution for the hostnames is in place:
```bash
minikube addons enable ingress-dns
```
And execute installation step [3 Add the `minikube ip` as a DNS server](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns) for your OS:

### Docker Desktop integrated Kubernetes Ingress Controller

- Install an NGINX Ingress Controller

```bash
helm upgrade --install ingress-nginx ingress-nginx --repo https://kubernetes.github.io/ingress-nginx --namespace ingress-nginx --create-namespace
```

### Network Setup on Linux and Mac

And execute installation step [3 Add the `minikube ip` as a DNS server](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns) for your OS:

```text
domain tx.test
nameserver 192.168.49.2
search_order 1
timeout 5
```

Replace 192.168.49.2 with your minikube ip.

To find out the IP address of your Minikube:
Expand All @@ -103,19 +148,19 @@ To find out the IP address of your Minikube:
minikube ip
```

If while [performing the first login](#perform-first-login) your still facing DNS issues, add the following to your /etc/hosts file:
when facing DNS-issues while [performing the first login](#perform-first-login), add the following to your /etc/hosts file

```
```text
192.168.49.2 centralidp.tx.test
192.168.49.2 sharedidp.tx.test
192.168.49.2 portal.tx.test
192.168.49.2 portal-backend.tx.test
192.168.49.2 pgadmin4.tx.test
```

Replace 192.168.49.2 with your minikube ip.
Replace 192.168.49.2 with your minikube ip

**Additional network setup** (for Mac only)
#### Additional Network Setup for Mac

Install and start [Docker Mac Net Connect](https://github.com/chipmk/docker-mac-net-connect#installation).

Expand All @@ -125,6 +170,82 @@ If you're having issues with getting 'Docker Mac Net Connect' to work, we recomm

The tool is necessary due to [#7332](https://github.com/kubernetes/minikube/issues/7332).

### Network Setup on Windows/wsl2 with NTLM-proxy

Configure wsl networking, assign additional fixed IP addresses to both wsl2 and windows, the wsl2-ip-address will then be used as cluster-ip-address. Do **not** use 127.0.0.1 as Cluster IP, as this causes issues when services try to access other services via the ingress from within the cluster.

In this tutorial we use:

- windows additional host ip 169.254.254.1
- wsl2 ip 169.254.254.2

#### px-proxy

Install px-proxy version v0.9.2 (or later) from <https://github.com/genotrance/px/releases> (minimum version is v0.9.0)

px.ini

```text
[proxy]
pac = http://proxypac.bmwgroup.net/proxy.pac
noproxy = 127.0.0.1,169.254.254.1,169.254.254.2,wsl,wsl.host,*.tx.test,localhost
```

In powershell set proxy environment variables:

```powershell
[Environment]::SetEnvironmentVariable('http_proxy','http://localhost:3128','User')
[Environment]::SetEnvironmentVariable('HTTP_PROXY','http://localhost:3128','User')
[Environment]::SetEnvironmentVariable('https_proxy','http://localhost:3128','User')
[Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://localhost:3128','User')
[Environment]::SetEnvironmentVariable('no_proxy','localhost,127.0.0.1,wsl,wsl.host,169.254.254.1,169.254.254.2,*.tx.test,.tx.test,tx.test','User')
[Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1,wsl,wsl.host,169.254.254.1,169.254.254.2,*.tx.test,.tx.test,tx.test','User')
```

In Firefox change the proxy to manual proxy configuration, <http://localhost:3128>

Chrome and Edge use the system proxy settings. Change those to 'manual', <http://localhost:3128> (both for http and https)
remark: on corporate managed windows the system proxy settings will eventually be overridden by the BMW system-management software and need to be re-configured whenever this happens.

#### DNS-resolution in Windows

c:\Windows\System32\drivers\etc\hosts

```text
169.254.254.2 wsl
169.254.254.2 centralidp.tx.test
169.254.254.2 sharedidp.tx.test
169.254.254.2 portal.tx.test
169.254.254.2 portal-backend.tx.test
169.254.254.2 pgadmin4.tx.test
```

#### DNS-resolution in wsl2

/etc/hosts

```text
169.254.254.1 wsl.host
169.254.254.2 centralidp.tx.test
169.254.254.2 sharedidp.tx.test
169.254.254.2 portal.tx.test
169.254.254.2 portal-backend.tx.test
169.254.254.2 pgadmin4.tx.test
```

#### Proxy-setup in wsl2

.profile

```bash
https_proxy=http://169.254.254.1:3128/
HTTPS_PROXY=http://169.254.254.1:3128/
http_proxy=http://169.254.254.1:3128/
HTTP_PROXY=http://169.254.254.1:3128/
no_proxy="localhost,127.0.0.1,wsl,wsl.host,169.254.254.1,169.254.254.2,docker.internal,tx.test"
NO_PROXY="localhost,127.0.0.1,wsl,wsl.host,169.254.254.1,169.254.254.2,docker.internal,tx.test"
```

## Install

### Use released chart
Expand Down Expand Up @@ -254,25 +375,25 @@ Address: [pgadmin4.tx.test](http://pgadmin4.tx.test)

Credentials to login into pgadmin4:

```
```text
[email protected]
```

```
```text
tractusxpgdamin4
```

**The database server connections need to be added manually to pgadmin4.**

Default username for all connections:

```
```text
postgres
```

Default port for all connections:

```
```text
5432
```

Expand All @@ -282,80 +403,80 @@ In the following some of the available connections:

Host:

```
```text
local-portal-backend-postgresql
```

Password:

```
```text
dbpasswordportal
```

- centralidp db

Host:

```
```text
local-centralidp-postgresql
```

Password:

```
```text
dbpasswordcentralidp
```

- sharedidp db

Host:

```
```text
local-sharedidp-postgresql
```

Password:

```
```text
dbpasswordsharedidp
```

- additional portal db

Host:

```
```text
local-portal-postgresql
```

Password:

```
```text
dbpasswordadditional
```

## Keycloak Admin Console

Access to admin consoles:

- http://centralidp.tx.test/auth/
- http://sharedidp.tx.test/auth/
- <http://centralidp.tx.test/auth/>
- <http://sharedidp.tx.test/auth/>

Default username for centralidp and sharedidp:

```
```text
admin
```

Password centralidp:

```
```text
adminconsolepwcentralidp
```

Password sharedidp:

```
```text
adminconsolepwsharedidp
```

Expand Down Expand Up @@ -384,6 +505,7 @@ Install cert-manager chart in the same namespace where the localdev chart will b
helm repo add jetstack https://charts.jetstack.io
helm repo update
```

```bash
helm install \
cert-manager jetstack/cert-manager \
Expand Down Expand Up @@ -435,6 +557,7 @@ spec:
secretName: root-secret
EOF
```

See [cert-manager self-signed](https://cert-manager.io/docs/configuration/selfsigned) for reference.

## Requirements
Expand Down
Loading