-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(localdev): add windows/wsl2 specific documentation #409
- Loading branch information
1 parent
a4352bb
commit b20b4ff
Showing
2 changed files
with
316 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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** | ||
| > | ||
|
|
@@ -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: | ||
|
|
||
|
|
@@ -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: | ||
|
|
@@ -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). | ||
|
|
||
|
|
@@ -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 | ||
|
|
@@ -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 | ||
| ``` | ||
|
|
||
|
|
@@ -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 | ||
| ``` | ||
|
|
||
|
|
@@ -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 \ | ||
|
|
@@ -435,6 +557,7 @@ spec: | |
| secretName: root-secret | ||
| EOF | ||
| ``` | ||
|
|
||
| See [cert-manager self-signed](https://cert-manager.io/docs/configuration/selfsigned) for reference. | ||
|
|
||
| ## Requirements | ||
|
|
||
Oops, something went wrong.