Minikube Installation
Minikube is a tool that makes it easy to run Kubernetes locally.
In this guide, you will install Yorkie cluster on minikube using Helm. Then, you will test Yorkie cluster with CodePair, a collaborative code editor.
Prerequities
This tutorial assumes that you are familiar with Kubernetes and kubectl
.
For this tutorial, you will need:
Setup minikube on your machine
First, you need to setup minikube on your machine to use Kubernetes locally and deploy Yorkie cluster.
Start Minikube with the following command:
$ minikube start
After Minikube is started, you will see the following output:
...๐ Verifying Kubernetes components...๐ Enabled addons: default-storageclass, storage-provisioner๐ Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
Then, you need to enable ingress addons to expose Yorkie cluster with nginx ingress controller.
Enable ingress addons with the following command:
$ minikube addons enable ingress
After ingress addons is enabled, you will see the following output:
...๐ Verifying ingress addon...๐ The 'ingress' addon is enabled
Install Istio with istioctl
After Minikube is configured, you need to install Istio for Yorkie cluster. Yorkie cluster uses Istio for L7 load balancing and traffic management.
Install Istio with the following command:
$ istioctl install -f <(curl -s https://raw.githubusercontent.com/yorkie-team/yorkie/main/build/charts/yorkie-cluster/istio-operator.yaml)
This will install Istio with Istio Operator configuration file. You can find the configuration file here.
When installing Istio, you will see the following output:
This will install the Istio 1.17.1 default profile with ["Istio core" "Istiod" "Ingress gateways"] components into the cluster. Proceed? (y/N)
Type y
and press Enter
to continue.
After Istio is installed, you will see the following output:
โ Istio core installedโ Istiod installedโ Ingress gateways installedโ Installation completeMaking this installation the default for injection and validation.Thank you for installing Istio 1.17. Please take a few minutes to tell us about your install/upgrade experience! https://forms.gle/hMHGiwZHPU7UQRWe9
Add yorkie-team Helm chart in your local repository
After Istio is installed, yuo need to add yorkie-team Helm chart repository in your local repository to install Yorkie cluster.
Add yorkie-team Helm chart repository in your local repository with the following command:
$ helm repo add yorkie-team https://yorkie-team.github.io/yorkie/helm-charts
Then, update your local repository with the following command:
$ helm repo update
Install Yorkie cluster with Helm chart
Now you have added yorkie-team Helm chart repository in your local repository, you can install Yorkie cluster with Helm chart.
Install Yorkie cluster with the following command:
$ helm install yorkie-cluster yorkie-team/yorkie-cluster
This will install yorkie-cluster
release in minikube cluster.
After Yorkie cluster is installed, you will see the following output:
NAME: yorkie-clusterLAST DEPLOYED: Thu Apr 27 21:49:06 2023NAMESPACE: defaultSTATUS: deployedREVISION: 1TEST SUITE: NoneNOTES:--- Install Complete ---yorkie-cluster successfully installed!For next steps, follow:$ curl https://github.com/yorkie-team/yorkie/tree/main/charts/yorkie-clusterTo learn more about the release, try:$ helm status yorkie-cluster$ helm get all yorkie-cluster
Now you have Yorkie cluster installed in your local machine.
It will take a few minutes for pods to be ready, so wait until all pods are ready. You can check the status of pods with the following command:
$ kubectl get pods -n yorkie --watch
After all pods are ready, you will see the following output:
NAME READY STATUS RESTARTS AGEmongodb-0 1/1 Running 0 76syorkie-74969cc796-46s47 1/1 Running 2 (54s ago) 76syorkie-74969cc796-c8zpt 1/1 Running 2 (50s ago) 76syorkie-74969cc796-n9jtr 1/1 Running 2 (52s ago) 76s
Expose Yorkie cluster with Minikube tunnel
After you have installed Yorkie cluster, you need to expose Yorkie cluster with Minikube tunnel to access Yorkie cluster from your local machine.
Expose Yorkie cluster with Minikube tunnel with the following command:
$ minikube tunnel
When Minikube tunnel is started, you will see the following output:
โ Tunnel successfully started๐ NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...โ The service/ingress yorkie requires privileged ports to be exposed: [80 443]๐ sudo permission will be asked for it.๐ Starting tunnel for service yorkie.Password:
Enter your password and press Enter
to continue.
This will expose Yorkie cluster via minikube cluster's IP address. You can check the IP address with the following command:
$ minikube ip
Test Yorkie cluster
Now that you have Yorkie cluster installed and exposed, you can test Yorkie cluster with CodePair, a collaborative editing tool powered by Yorkie.
Clone CodePair repository with the following command:
$ git clone https://github.com/yorkie-team/codepair
Then, change directory to codepiar folder and install dependencies with the following command:
$ cd codepair$ npm install
After dependencies are installed, change VITE_APP_YORKIE_RPC_ADDR
in .env.development
file to your minikube IP address.
$ vi .env.developmentVITE_APP_YORKIE_RPC_ADDR=http://<minikube-ip># If you are using macOS, you should set VITE_APP_YORKIE_RPC_ADDR to localhost instead of minikube-ip.# VITE_APP_YORKIE_RPC_ADDR=http://localhost
VITE_APP_YORKIE_RPC_ADDR
to localhost
instead of minikube ip
.Then, start CodePair with the following command:
$ npm run dev> codepair@1.0.0 dev> vite --config ./config/vite.config.development.tsVITE v4.3.0 ready in 257 msโ Local: http://localhost:3000/โ Network: use --host to exposeโ press h to show help
You can open several web browsers and access http://localhost:3000
to test collaborative editing with CodePair.
Clean up Yorkie cluster
You have now installed Yorkie cluster in your local machine, and tested collaborative editing with CodePair.
First, stop CodePair and remove repository folder with the following command:
Use Ctrl + C
to stop CodePair.
VITE v4.3.0 ready in 257 msโ Local: http://localhost:3000/โ Network: use --host to exposeโ press h to show help# Stop CodePair$ ^C# Remove repository folder$ cd ..$ rm -rf codepair
Then, stop minikube tunnel in running terminal.
Use Ctrl + C
to stop minikube tunnel.
๐ Starting tunnel for service yorkie.Password:# Stop minikube tunnel$โ Stopped tunnel for service yorkie.
Then, uninstall Yorkie cluster with the following command:
$ helm uninstall yorkie-clusterrelease "yorkie-cluster" uninstalled
Then, uninstall Istio with the following command:
$ istioctl uninstall --purgeAll Istio resources will be pruned from the clusterProceed? (y/N) y...โ Uninstall complete# (Optional) Remove istio-system namespace$ kubectl delete namespace istio-system
After that, you can stop minikube with the following command:
$ minikube stopโ Stopping node "minikube" ...๐ Powering off "minikube" via SSH ...๐ 1 node stopped.
You can delete minikube cluster with the following command:
$ minikube delete๐ฅ Deleting "minikube" in docker ...๐ฅ Deleting container "minikube" ...๐ฅ Removing /Users/yorkie/.minikube/machines/minikube ...๐ Removed all traces of the "minikube" cluster.
Next Steps
You can also install Yorkie cluster addons to monitor metrics and perform GitOps on Yorkie cluster.
- For more information, see Self-Hosting Guide: Cluster Addons Installation.
- For more information about Yorkie cluster design, follow: Yorkie Cluster Design