{"id":18499639,"url":"https://github.com/asimmon/local-kubernetes-setup","last_synced_at":"2025-04-09T01:31:41.278Z","repository":{"id":134550169,"uuid":"571267830","full_name":"asimmon/local-kubernetes-setup","owner":"asimmon","description":"Setup a local Kubernetes cluster on any OS with TLS support and nginx as an ingress controller to deploy services on local trusted domains.","archived":false,"fork":false,"pushed_at":"2022-12-07T01:10:45.000Z","size":42,"stargazers_count":88,"open_issues_count":0,"forks_count":10,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-23T20:11:17.227Z","etag":null,"topics":["helm","kubernetes","localhost"],"latest_commit_sha":null,"homepage":"","language":"Smarty","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asimmon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-27T17:36:47.000Z","updated_at":"2025-01-19T12:13:28.000Z","dependencies_parsed_at":"2023-04-26T00:47:02.470Z","dependency_job_id":null,"html_url":"https://github.com/asimmon/local-kubernetes-setup","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimmon%2Flocal-kubernetes-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimmon%2Flocal-kubernetes-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimmon%2Flocal-kubernetes-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asimmon%2Flocal-kubernetes-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asimmon","download_url":"https://codeload.github.com/asimmon/local-kubernetes-setup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247956563,"owners_count":21024571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helm","kubernetes","localhost"],"created_at":"2024-11-06T13:46:46.532Z","updated_at":"2025-04-09T01:31:41.273Z","avatar_url":"https://github.com/asimmon.png","language":"Smarty","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\n# Local Kubernetes setup\n\n\u003e 👋 This guide is mostly intented for Windows users. However, Linux and macOS users can easily skip or execute the equivalent steps to get the same result.\n\nThis repository contains the instructions and code to setup a local Kubernetes cluster. At the end, you'll get:\n\n* A local Kubernetes cluster with TLS support for your services on local domains (such as `myapi.example.local`)\n* Command-line tools and completion for your terminal\n* A configured nginx ingress controller with compression, web application firewall and extra security settings enabled\n* A self-signed root certificate authority trusted by your OS, the cluster and your browsers\n* Upgradeable Helm charts to easily customize this setup\n\n**Table of contents**\n\n- [🔧 Required setup](#-required-setup)\n  - [Install WSL 2, Docker Desktop and Kubernetes](#install-wsl-2-docker-desktop-and-kubernetes)\n  - [Install PowerShell Core 7](#install-powershell-core-7)\n  - [Install Kubectl and Helm](#install-kubectl-and-helm)\n  - [Install mkcert](#install-mkcert)\n  - [Switch your kubectl context to docker-desktop](#switch-your-kubectl-context-to-docker-desktop)\n- [✨ Recommended additional setup](#-recommended-additional-setup)\n  - [Install Windows Terminal or Oh My Zsh](#install-windows-terminal-or-oh-my-zsh)\n  - [Install PowerShell intellisense completion](#install-powershell-intellisense-completion)\n  - [Install Powershell completion for Kubectl and Helm](#install-powershell-completion-for-kubectl-and-helm)\n  - [Install k9s dashboard](#install-k9s-dashboard)\n  - [Configure your WSL 2 memory and CPU settings](#configure-your-wsl-2-memory-and-cpu-settings)\n- [🔥 Getting started](#-getting-started)\n- [☁ Install nginx ingress controller](#-install-nginx-ingress-controller)\n- [🔑 Install cert-manager to manage TLS certificates](#-install-cert-manager-to-manage-tls-certificates)\n- [🚀 Deploy an ASP.NET Core example service](#-deploy-an-aspnet-core-example-service)\n  - [Install a trusted self-signed TLS certificate for your ingress](#install-a-trusted-self-signed-tls-certificate-for-your-ingress)\n  - [Deploy the service](#deploy-the-service)\n- [🧷 Install Kubernetes dashboard](#-install-kubernetes-dashboard)\n\n\n## 🔧 Required setup\n\n### Install WSL 2, Docker Desktop and Kubernetes\n\n\u003e Installing [WSL 2 and an Ubuntu Linux distribution](https://learn.microsoft.com/en-us/windows/wsl/install) is only required on Windows.\n\nInstall Docker Desktop:\n* Windows: https://docs.docker.com/desktop/install/windows-install/\n* Linux: https://docs.docker.com/desktop/install/linux-install/\n* macOS: https://docs.docker.com/desktop/install/mac-install/\n\nThen, go to *Docker Desktop settings \u003e Kubernetes* and check the *Enable Kubernetes*.\n\n### Install PowerShell Core 7\n\n[PowerShell Core 7](https://github.com/PowerShell/PowerShell#get-powershell) is cross-platform and only required on your OS and WSL 2 for one particular steps of this guide, which is coping the mkcert root certificate authority into the chart directory.\n\n\u003e You may look at the [content the script](https://github.com/asimmon/local-kubernetes-setup/blob/main/mkcert-local-setup/mkcert/Copy-Certificates.ps1) and do the equivalent on your own, without installing PowerShell Core.\n\n### Install Kubectl and Helm\n\n\u003e https://kubernetes.io/docs/tasks/tools/\n\n\u003e https://helm.sh/docs/intro/install/\n\n*On Windows, installing using Chocolatey is preferred.*\n\n### Install mkcert\n\n[mkcert](https://github.com/FiloSottile/mkcert) *(38k+⭐)* is a simple tool for making locally-trusted development certificates. It will be used here to allow Kubernetes to issue self-signed certificates that are trusted by your browser and Windows / WSL 2, using a root certificate authority (CA). Execute `mkcert -install` once installed.\n\n**Reuse mkcert CA on WSL 2**\n\n* Execute `mkcert -CAROOT` on both Windows and WSL 2 to print the directory of the root certificate authority files\n* Copy the files from Windows to WSL 2\n* Execute once again `mkcert -install` on WSL 2\n\n\u003e From Ubuntu, you can access Windows `C:\\` drive using this mount `/mnt/c/`\n\u003e\n\u003e From Windows, you can access Ubuntu files using this mount `\\\\wsl$\\Ubuntu\\`\n\n![image](https://user-images.githubusercontent.com/14242083/204668221-5a049d08-5e11-4b59-9b83-d0f3235057be.png)\n\n### Switch your kubectl context to docker-desktop\n\nThis step changes the cluster targeted by commands such as `kubectl`, `helm`, `k9s`, etc. by modifying your [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/). This file is located:\n* On Windows: `%userprofile%\\.kube\\config`\n* On Linux and macOS: `~/.kube/config`\n\nRun this command to target your local cluster:\n```\nkubectl config use-context docker-desktop\n```\n\n\u003e On Windows, you can also right click on Docker Desktop tray icon, then on Kubernetes and you should have access to a dropdown.\n\u003e\n\u003e If you also installed `kubectl` and on your WSL 2 distribution, then both Windows and WSL 2 will use different kubeconfig files.\n\u003e You can force WSL 2 to use Windows' kubeconfig file by editing your `~/.bashrc` and `~/.zshrc` (if applicable) and adding the following line at the end (insert your Windows username):\n\u003e `export KUBECONFIG=/mnt/c/Users/\u003cWINDOWS-USERNAME\u003e/.kube/config`.\n\n\n## ✨ Recommended additional setup\n\n\u003e These steps will mostly enhance your tooling and development experience.\n\n### Install Windows Terminal or Oh My Zsh\n\n* Windows: https://aka.ms/terminal\n* Linux and macOS: https://ohmyz.sh and https://github.com/romkatv/powerlevel10k\n\n![image](https://user-images.githubusercontent.com/14242083/204665666-06edce76-6ffe-476b-986c-a4f5dfaf823b.png)\n\n### Install PowerShell intellisense completion\n\n\u003e https://github.com/PowerShell/PSReadLine\n\nAfter installing the module **as an administrator**, open a normal terminal and edit your [profile](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.3) (`notepad $PROFILE`) to enable smart auto-complete by adding these lines:\n\n```ps1\nImport-Module PSReadLine\n\nSet-PSReadLineOption -PredictionSource History\nSet-PSReadLineOption -PredictionViewStyle ListView\nSet-PSReadlineOption -BellStyle None\n```\n\n### Install Powershell completion for Kubectl and Helm\n\nEdit your [profile](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.3) (`notepad $PROFILE`) and add the following lines:\n\n```ps1\nkubectl completion powershell | Out-String | Invoke-Expression\nhelm completion powershell | Out-String | Invoke-Expression\n```\n\n\u003e Follow [these](https://kubernetes.io/docs/tasks/tools/included/) and [these steps](https://helm.sh/docs/helm/helm_completion/) for Linux and macOS.\n\n### Install k9s dashboard\n\n\u003e https://k9scli.io/topics/install/\n\n*\"K9s is a terminal based UI to interact with your Kubernetes clusters. The aim of this project is to make it easier to navigate, observe and manage your deployed applications in the wild. K9s continually watches Kubernetes for changes and offers subsequent commands to interact with your observed resources.\"*\n\n![image](https://user-images.githubusercontent.com/14242083/204668596-29b17fa5-4f8e-49ab-bdb5-aeb0725386b7.png)\n\n### Configure your WSL 2 memory and CPU settings\n\nModify the maximum CPU and memory used by WSL 2 by following [these steps](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig).\n\n## 🔥 Getting started\n\n* Clone this git repository\n* Open a terminal into the cloned repository\n\n* Then, copy mkcert's root certificate authority (CA) into the `mkcert-local-setup` chart directory:\n```\npwsh ./mkcert-local-setup/mkcert/Copy-Certificates.ps1\n```\n\n\n## ☁ Install nginx ingress controller\n\n\u003e [Nginx ingress controller](https://kubernetes.github.io/ingress-nginx/) is used to route the incoming traffic of your browser/tools to the services inside the cluster. By default it uses the ports `80` and `433` so make sure you don't already have something using these ports, or edit the `values.yaml` file.\n\nFirst, have a look at `.\\nginx-ingress-setup\\Chart.yaml` and `.\\nginx-ingress-setup\\values.yaml`. You'll see that we install `nginx-ingress` as a [chart dependency](https://helm.sh/docs/helm/helm_dependency/), which pins a specific version and makes it easy to upgrade. The `values.yaml` enables:\n\n* Brotli and gzip compression\n* Modsecurity web application firewall\n* HSTS and secure headers\n\nNow, run this command anytime you want to install or update the nginx ingress controller:\n\n```\nhelm upgrade --install --wait --debug --dependency-update --namespace nginx-ingress --create-namespace nginx-ingress ./nginx-ingress-setup\n```\n\n\n## 🔑 Install cert-manager to manage TLS certificates\n\n\u003e [Cert-manager](https://cert-manager.io/) is used to automatically issue certificates for the hostnames used by your services using mkcert's root certificate authority.\n\nFirst, have a look at `.\\cert-manager-setup\\Chart.yaml` and `.\\cert-manager-setup\\values.yaml`. It's installed as a chart dependency too.\n\n```\nhelm upgrade --install --wait --debug --dependency-update --namespace cert-manager --create-namespace cert-manager ./cert-manager-setup\n```\n\n## 🚀 Deploy an ASP.NET Core example service\n\nWe'll deploy the service in a dedicated [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). It's a way to group Kubernetes objects in logical units. In this example, we will create and use a namespace named `demo`.\n\nWe'll also deploy the service to the domain `aspnetcore.example.local`. Two things:\n* Make sure to add this custom local domain to your hosts files ([instructions for Windows](https://www.wikihow.com/Edit-the-Hosts-File-on-Windows))\n* `*.example.local` TLS support is pre-configured in the file `.\\mkcert-local-setup\\values.yaml`, so if you want to use another local domain please update this file too\n\n### Install a trusted self-signed TLS certificate for your ingress\n\nIssue a TLS certificate for `*.example.local` in the `demo` namespace by installing a release of this chart:\n```\nhelm upgrade --install --wait --dependency-update --namespace demo --create-namespace demo-mkcert ./mkcert-local-setup\n```\n\nThis will issue a TLS certificate stored in a secret named `\u003chelm-release-name\u003e-tls-secret`. In this case the release name was `demo-mkcert`, so created TLS secret is named `demo-mkcert-tls-secret`. This secret name is very important because it will be referenced by your ingress.\n\n### Deploy the service\n\nThe chart `aspnetcore-service` exposes the [Microsoft ASP.NET Core sample Docker application](https://hub.docker.com/_/microsoft-dotnet-samples/). The `.\\aspnetcore-service\\values.yaml` ingress values are already configured to support the domain `aspnetcore.example.local` and the TLS secret created in the previous step:\n\n```yaml\ningress:\n  className: nginx\n  hostname: aspnetcore.example.local # \u003c-- Local domain covered by the TLS certificate\n  # [...]\n  tls:\n    enabled: true # \u003c-- Don't want HTTPS? Set this to false\n    secretName: demo-mkcert-tls-secret # \u003c-- Secret created in the previous step\n```\n\nNow, deploy the ASP.NET Core app to the `demo` namespace, next to the TLS secret:\n\n```\nhelm upgrade --install --wait --debug --dependency-update --namespace demo --create-namespace demo-aspnetcore ./aspnetcore-service\n```\nThe service should now be accessible at https://aspnetcore.example.local/\n\n![image](https://user-images.githubusercontent.com/14242083/204666433-bc8d18ee-348b-4695-8d95-6624d444cbb9.png)\n\n\n## 🧷 Install Kubernetes dashboard\n\n[Kubernetes dashboard](https://github.com/kubernetes/dashboard) is similar to k9s. It's a web-based UI to manage your cluster.\n\n* We'll deploy it in a new namespace `kubernetes-dashboard`\n* It will be accessible at the URL https://kubernetes-dashboard.example.local, so modify your [hosts](https://www.wikihow.com/Edit-the-Hosts-File-on-Windows) file accordingly\n\nSame as for the ASP.NET Core app, we first need a TLS certificate:\n\n```\nhelm upgrade --install --wait --dependency-update --namespace kubernetes-dashboard --create-namespace kubernetes-dashboard-mkcert ./mkcert-local-setup\n```\n\nThe `kubernetes-dashboard-setup` chart uses the [kubernetes-dashboard](https://artifacthub.io/packages/helm/k8s-dashboard/kubernetes-dashboard) subchart and is already configured for our custom domain and TLS certificate secret name.\n\n```\nhelm upgrade --install --wait --debug --dependency-update --namespace kubernetes-dashboard --create-namespace kubernetes-dashboard ./kubernetes-dashboard-setup\n```\nThe service should now be accessible at https://kubernetes-dashboard.example.local. Press the \"Skip\" button to sign-in, anonymous access should be enabled.\n\n![image](https://user-images.githubusercontent.com/14242083/204666532-465ca73a-e939-4158-b992-7faf16110204.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimmon%2Flocal-kubernetes-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasimmon%2Flocal-kubernetes-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasimmon%2Flocal-kubernetes-setup/lists"}