Yorkie

AWS EKS Installation

AWS's Elastic Kubernetes Service (EKS) is a managed service that lets you deploy, manage, and scale containerized applications on Kubernetes.

In this guide, you will install Yorkie cluster on AWS EKS using Helm. Then, you will test Yorkie cluster with Quill Example to see how collaborative editing works with Yorkie.

AWS EKS clusters cost $0.10 per hour, so you may incur charges by running this tutorial. The cost should be a few dollars at most, but be sure to delete your infrastructure promptly to avoid additional charges. We are not responsible for any charges you may incur.

Prerequisites

This tutorial assumes that you are familiar with Kubernetes and kubectl.

For this tutorial, you will need:

Setup AWS EKS cluster

First, you need to setup AWS EKS cluster and addons to deploy Yorkie cluster.

Below are the list of resources you need to provision:

  1. AWS EKS cluster to provision Kubernetes cluster.
  2. EBS CSI driver to provision EBS volumes attached to Kubernetes volumes.
  3. ALB ingress controller to provision ALB ingress controller.
  4. Domain Name to access Yorkie cluster with domain name.
  5. Certificate to access Yorkie cluster with HTTPS.

If you did not provision resources above in your AWS account, follow the links above to provision them.

After provisioning AWS EKS cluster, verify that the cluster is ready:

$ kubectl cluster-info
Kubernetes control plane is running at https://12341234123412341234.gr7.ap-northeast-2.eks.amazonaws.com
CoreDNS is running at https://12341234123412341234.gr7.ap-northeast-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy


To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Install Istio with istioctl

After AWS EKS 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 complete                                                                                             
Making 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, you 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 \
	--set ingress.ingressClassName=alb \
	--set ingress.hosts.enabled=true \
    --set ingress.hosts.apiHost={YOUR_API_DOMAIN_NAME} \
    --set ingress.awsAlb.enabled=true \
    --set ingress.awsAlb.certArn={YOUR_CERTIFICATE_ARN}


# For example, for domain name `yorkie.dev` and certificate ARN 
# `arn:aws:acm:ap-northeast-2:123412341234:certificate/12341234-1234-1234-1234-123412341234`, run the following command:
$ helm install yorkie-cluster yorkie-team/yorkie-cluster \
	--set ingress.ingressClassName=alb \
	--set ingress.hosts.enabled=true \
    --set ingress.hosts.apiHost=api.yorkie.dev \
    --set ingress.awsAlb.enabled=true \
    --set ingress.awsAlb.certArn=arn:aws:acm:ap-northeast-2:123412341234:certificate/12341234-1234-1234-1234-123412341234

Replace {YOUR_API_DOMAIN_NAME} with your domain name. Also, replace {YOUR_CERTIFICATE_ARN} with your certificate ARN.

This will install yorkie-cluster release in AWS EKS, which can be publicly accessible via {YOUR_API_DOMAIN_NAME} with HTTPS by provisioning external AWS ALB in front of Yorkie cluster.

You can also set other Helm chart configuration options. For more information about Helm chart configuration, see Yorkie Cluster Helm Chart Configuration.

After Yorkie cluster is installed, you will see the following output:

NAME: yorkie-cluster
LAST DEPLOYED: Thu Apr 27 21:49:06 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
--- Install Complete ---
yorkie-cluster successfully installed!


For next steps, follow:
  $ curl https://github.com/yorkie-team/yorkie/tree/main/charts/yorkie-cluster


To learn more about the release, try:
  $ helm status yorkie-cluster
  $ helm get all yorkie-cluster

Now you have Yorkie cluster installed in AWS EKS. 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   AGE
yorkie-f595554db-48s9c           1/1     Running   0          8m18s
yorkie-f595554db-nggr9           1/1     Running   0          8m18s
yorkie-f595554db-z5jgs           1/1     Running   0          8m18s
yorkie-gateway-844d8c87d-fqpsk   1/1     Running   0          9m55s

Test Yorkie cluster

Now that you have Yorkie cluster installed and exposed, you can test Yorkie cluster with yorkie-js-sdk, a JavaScript SDK for Yorkie.

Clone yorkie-js-sdk repository with the following command:

$ git clone https://github.com/yorkie-team/yorkie-js-sdk

Then, change directory to yorkie-js-sdk folder and install dependencies with the following command:

$ cd yorkie-js-sdk
$ pnpm i

After dependencies are installed, you need to set VITE_YORKIE_API_ADDR in the .env file to your AWS api domain name or IP address with the following command:

$ cd examples/vanilla-quill
$ vi .env


VITE_YORKIE_API_ADDR=http://<YOUR_API_DOMAIN_NAME or IP_ADDRESS>

Then, start Quill Example with the following command:

$ cd ../..
$ pnpm vanilla-quill dev


> yorkie-js@0.0.0 vanilla-quill /yorkie-js-sdk
> pnpm --filter=vanilla-quill "dev"




> vanilla-quill@0.0.0 dev /yorkie-js-sdk/examples/vanilla-quill
> vite




  VITE v5.3.5  ready in 178 ms


  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

You can open several web browsers and access http://localhost:5173 to test collaborative editing with Quill.

For more examples of collaborative tools developed with Yorkie, including Quill, take a look at yorkie-js-sdk examples.

Clean up Yorkie cluster

You have now installed Yorkie cluster in AWS EKS, and tested collaborative editing with Quill.

To learn about how to configure Yorkie Cluster in Helm Chart, see Yorkie Cluster Helm Chart Repository.

First, uninstall Yorkie cluster with the following command:

$ helm uninstall yorkie-cluster
release "yorkie-cluster" uninstalled

Then Uninstall Istio with the following command:

$ istioctl uninstall --purge
All Istio resources will be pruned from the cluster
Proceed? (y/N) y
...
✔ Uninstall complete


# (Optional) Remove istio-system namespace
$ kubectl delete namespace istio-system

(Optional) Then, delete EKS cluster via AWS Console or AWS CLI.

# AWS Console
$ https://{YOUR_REGION}.console.aws.amazon.com/eks/home?region={YOUR_REGION}/clusters


# AWS CLI
$ aws eks delete-cluster --name {YOUR_CLUSTER_NAME}

Next Steps

You can also install Yorkie Cluster addons to monitor metrics and perform GitOps on Yorkie cluster.