doc on Installation

docs/install/eks.md

@@ -0,0 +1,93 @@
+---
+title: AWS Elastic Kubernetes Service
+---
+
+This guide demonstrates how to create an Amazon EKS cluster using either the AWS Command Line Interface (CLI) or with Terraform. The resulting cluster generated from this guide will be ready to install Kalm.
+
+## Prerequisites
+
+Before following either guide below
+
+- Install the [Amazon CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
+- Create and configure an AWS Service Account. Configure the [service credentials](https://console.aws.amazon.com/iam/home?#/security_credentials), then configure the AWS CLI with:
+
+```
+aws configure
+```
+
+The Access key ID and secret for this service account will need to be provided.
+
+## Creating an EKS Cluster using The AWS CLI
+
+In addition to the AWS CLI, this guide uses [eksctl](https://eksctl.io/) - a simple CLI tool for creating clusters on EKS.
+
+**Install eksctl**
+
+Follow Amazon's detailed [eksctl installation instructions](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html#installing-eksctl) for linux, mac, and windows.
+
+**Create an EKS Cluster**
+
+Before running the command below, specify <company-name\>, <cluster-name\>, and modify the region if needed. Once modified, run the command to create an EKS cluster.
+
+```bash
+# create key
+aws ec2 create-key-pair --region us-east-2 --key-name keypair-for-<company-name>
+
+# create eks cluster, for details, see: https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html
+eksctl create cluster \
+--name <cluster-name> \
+--region us-east-2 \
+--with-oidc \
+--ssh-access \
+--ssh-public-key keypair-for-<company-name> \
+--managed
+```
+
+The creation process typically takes between 15 and 30 minutes. Once it completes, the `kubectl` config file will automatically update to use the newly created cluster as the current cluster. To double-check this, run `kubectl config get-context`. The new cluster should be marked with a `*` in the output.
+
+## Creating an EKS Cluster with Terraform
+
+Alternatively, the EKS Cluster can be created using Terraform. To use Terraform, first:
+
+- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- Install [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
+
+Next, clone the git repository below and `cd` into the eks directory (script included below for convenience):
+
+```
+git clone https://github.com/kalmhq/tf-scripts
+cd tf-scripts/eks
+```
+
+Create the cluster by running the following commands:
+
+```
+terraform init
+terraform apply
+```
+
+Type `yes` to confirm.
+
+This process should take around 5-10 minutes.
+
+Once it finishes, view the newly created cluster with:
+
+```
+aws eks list-clusters
+```
+
+The following command configures kubectl to use the new cluster.
+
+```
+aws eks --region us-west-2 update-kubeconfig --name NAME_OF_YOUR_CLUSTER
+```
+
+Verify the cluster is properly setup and accessible.
+
+```
+kubectl get nodes
+```
+
+## Next Step
+
+To install Kalm onto the cluster, see [Install Kalm Cloud](install-kalm-cloud).

docs/install/gke.md

@@ -0,0 +1,152 @@
+---
+title: Google Kubernetes Engine
+---
+
+This guide demonstrates how to create a GKE cluster using any of the following options:
+
+- The Google Cloud Console (web interface at https://console.cloud.google.com/)
+- The gcloud command-line tool
+- Terraform
+
+## Create a GKE Cluster using The Google Cloud Console
+
+The simplest way to create a GKE cluster is by using the Google Cloud Console, which acts as a web interface for GCP. Use the following steps to create a GKE cluster:
+
+- Go to [https://console.cloud.google.com/kubernetes/list](https://console.cloud.google.com/kubernetes/list)
+- Click **CREATE CLUSTER**
+    - Select a cluster name, and customize any other fields as needed (default options will work)
+- Click **CREATE**
+    - The cluster creation process typically takes 5-10 minutes
+
+Once the cluster is created:
+- Go to [https://console.cloud.google.com/kubernetes/list](https://console.cloud.google.com/kubernetes/list), click the 3 dots to the right of the newly created cluster, and select Connect
+    - Enable the Kubernetes API if not already enabled
+- Copy the command-line access command and run it on a local terminal. This command will configure `kubectl config` to access the newly created cluster.
+
+## Create a GKE Cluster using The Gcloud Command-Line Tool
+
+GKE Clusters can also be created using Google's gcloud CLI. The gcloud CLI is included in their SDK, which can be installed by following instructions in [Google's SDK installation docs](https://cloud.google.com/sdk/docs).
+
+GKE clusters are organized within [Google Cloud Projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). The project name is used in several spots, so for the sake of simplicity this demo sets a PROJECT_ID variable to the name of the project used.
+
+```
+export PROJECT_ID=hello-kalm
+```
+
+This can be either an existing project or a new one. To create a new project, run the command below (the project name is set to "hello-kalm" in this example):
+
+```
+gcloud projects create $PROJECT_ID
+```
+
+In order to create a Kubernetes cluster on GCP [billing must be enabled](https://cloud.google.com/billing/docs/how-to/modify-project##confirm_billing_is_enabled_on_a_project) for that project. By default, new projects will **not** have billing enabled.
+
+Additionally, projects need to specifically enable the Kubernetes Engine API, which can be done using the command below:
+
+```
+gcloud services enable container.googleapis.com
+```
+
+With billing and engine API enabled, the following commands will provision a cluster with 4 nodes (modify the zone as needed):
+
+```
+export M_TYPE=n1-standard-2 && \
+export ZONE=us-west2-a && \
+export CLUSTER_NAME=${PROJECT_ID}-${RANDOM} && \
+gcloud container clusters create $CLUSTER_NAME \
+  --cluster-version latest \
+  --machine-type=$M_TYPE \
+  --num-nodes 4 \
+  --zone $ZONE \
+  --project $PROJECT_ID
+```
+
+It will take a few minutes to create the cluster. Once complete, configure kubectl to use the new cluster:
+
+```
+gcloud container clusters get-credentials $CLUSTER_NAME \
+  --zone $ZONE \
+  --project $PROJECT_ID
+```
+
+Verify the cluster is properly setup and accessible.
+
+```
+kubectl cluster-info
+```
+
+## Terraform
+
+Alternatively, the GKE Cluster can be created using Terraform. To use Terraform, first:
+
+- Install [The gcloud CLI](https://cloud.google.com/sdk/docs).
+- Install [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/gcp-get-started).
+- Install [kubectl](https://kubernetes.io/docs/tasks/tools/included/install-kubectl-gcloud/)
+
+GKE clusters are organized within [Google Cloud Projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). A new project can be created with:
+
+```
+gcloud projects create PROJECT-NAME-HERE
+```
+
+Use the `gcloud init` command and select the new (or existing) project ([usage details here](https://cloud.google.com/sdk/gcloud/reference/init)).
+
+Terraform also requires access to the Application Default Credentials (ADC), which can be granted using the following command:
+
+```
+gcloud auth application-default login
+```
+
+The Kubernetes Engine API will need to be enabled for the project as well, which can be done using the following command:
+
+```
+gcloud services enable container.googleapis.com
+```
+
+Clone the repository below to download Kalm's installation scripts for Terraform.
+
+```
+git clone https://github.com/kalmhq/tf-scripts
+cd tf-scripts/gke
+```
+
+Open 'terraform.tfvars' in a text editor and specify the ID of the current Google Cloud project. The region can be specified as well.
+
+```
+# terraform.tfvars
+project_id = "REPLACE_ME"
+region     = "us-west2"
+```
+
+With these settings configured, create the cluster by using the following commands:
+
+```
+terraform init
+terraform apply
+```
+
+Type `yes` to confirm the installation.
+
+The process should take around 5-10 minutes. Once complete, retrieve the name of the newly created cluster.
+
+```
+terraform output
+```
+
+Configure kubectl to use the new cluster.
+
+```
+gcloud container clusters get-credentials NAME_OF_YOUR_CLUSTER --zone ZONE_OF_CLUSTER
+```
+
+- *Note - identify the project's zone either on [gcloud console](https://console.cloud.google.com/) or using the CLI by entering: `gcloud info | grep "zone"`*
+
+Verify the cluster is properly setup and accessible.
+
+```
+kubectl cluster-info
+```
+
+## Next Step
+
+To install Kalm onto the cluster, see [Install Kalm Cloud](install-kalm-cloud).

docs/install/install-kalm-cloud.md

@@ -0,0 +1,126 @@
+---
+title: How To Install Kalm Cloud
+---
+
+Kalm installs smoothly into almost any existing Kubernetes cluster.
+
+1. Go to [http://kalm.dev/signin](http://kalm.dev/signin)
+
+Signing in can be done with either Github or Google OAuth, which effectively creates a Kalm account.
+
+2. After signing in, click the **INSTALL NEW CLUSTER** button in the upper right corner:
+
+    ![How%20To%20Install%20Kalm%20Cloud%202efc1e7deda144498352c5303d983da0/Untitled.png](../assets/kalm-cloud-1-new-cluster.png)
+
+3. Choose a name for your cluster
+
+![How%20To%20Install%20Kalm%20Cloud%202efc1e7deda144498352c5303d983da0/Untitled%201.png](../assets/kalm-cloud-2-cluster-name.png)
+
+4. Before running the installation script, double check to make sure `kubectl` is pointing at the desired cluster. Running `kubectl config get-context` will mark a new cluster with a `*` in the output.
+
+5.  Run the install script:
+
+![How%20To%20Install%20Kalm%20Cloud%202efc1e7deda144498352c5303d983da0/Untitled%202.png](../assets/kalm-cloud-3-install-script.png)
+
+The installation process will continuously update while it runs:
+
+![How%20To%20Install%20Kalm%20Cloud%202efc1e7deda144498352c5303d983da0/Untitled%203.png](../assets/kalm-cloud-4-installing.png)
+
+Typically, the installation takes around 15-30 minutes to complete.
+
+6. Once done, click the **GO TO DASHBOARD** button to start using Kalm.
+
+![How%20To%20Install%20Kalm%20Cloud%202efc1e7deda144498352c5303d983da0/Untitled%204.png](../assets/kalm-cloud-5-install-succeed.png)
+
+# Troubleshooting (WORK IN PROGRESS)
+
+While installing Kalm is designed to be as smooth as possible, we have provided some additional information here to help with troubleshooting just in case something goes wrong during the process. The troubleshooting guides below are categorized by which step of the installation path fails.
+
+Possible issues for each install step:
+
+- INSTALL_CERT_MANAGER: Kalm is installing Cert-Manager. If this step is stuck, the cluster is likely having problems installing the pods. Run `kubectl get pods -n cert-manager` to see if anything is going wrong. Most normal clusters should return something similiar to:
+
+    ```bash
+    ➜  kubectl get pods -n cert-manager
+    NAME                                       READY   STATUS    RESTARTS   AGE
+    cert-manager-7cb75cf6b4-48jvk              1/1     Running   0          29d
+    cert-manager-cainjector-759496659c-7smnl   1/1     Running   0          29d
+    cert-manager-webhook-7c75b89bf6-p9lwx      1/1     Running   0          29d
+    ```
+
+- INSTALL_ISTIO: Kalm is installing Istio. If this step is stuck, the cluster is (perhaps obviously) likely having problems installing Istio, run `kubectl get pods -n istio-operator` and `kubectl get pods -n istio-system` to see if anything is going wrong, a normal running cluster should return something similar as:
+
+    ```bash
+    ➜  kubectl get pods -n istio-operator
+    NAME                              READY   STATUS    RESTARTS   AGE
+    istio-operator-7654b568b7-nqclz   1/1     Running   0          16d
+
+    ➜  kubectl get pods -n istio-system
+    NAME                                   READY   STATUS    RESTARTS   AGE
+    istio-ingressgateway-59cf75bf7-hqpkd   1/1     Running   0          16d
+    istiod-59cc49f5d9-cmzwb                1/1     Running   0          16d
+    prometheus-6c77954d87-wmrpn            1/1     Running   0          16d
+    ```
+
+- INSTALL_KALM_CONTROLLER: Kalm is installing kalm-controller, if this step stuck, very likely the cluster is having problems installing the pods, run `kubectl get pods -n kalm-system -l control-plane=controller` to see if anything is going wrong, a normal running cluster should return something similar as:
+
+    ```bash
+    ➜  kubectl get pods -n kalm-system -l control-plane=controller
+    NAME                               READY   STATUS    RESTARTS   AGE
+    kalm-controller-758c5498c9-6vtp7   3/3     Running   0          110m
+    ```
+
+- INSTALL_KALM_DASHBOARD: Kalm is installing the Kalm dashboard, if this step stuck, very likely the cluster is having problems installing the pods, run `kubectl get pods -n kalm-system -l kalm-component=kalm` to see if anything is going wrong, a normal running cluster should return something similar as:
+
+    ```bash
+    ➜  kubectl get pods -n kalm-system -l kalm-component=kalm
+    NAME                    READY   STATUS    RESTARTS   AGE
+    kalm-6654df4b5c-w88cv   2/2     Running   0          121m
+    ```
+
+- INSTALL_ACME_SERVER: Kalm is installing the ACME DNS server, if this step stuck, very likely the cluster is having problems installing the pods, run `kubectl get pods -n kalm-system -l kalm-component=acme-server` to see if anything is going wrong, a normal running cluster should return something similar as:
+
+    ```bash
+    ➜  kubectl get pods -n kalm-system -l kalm-component=acme-server
+    NAME                           READY   STATUS    RESTARTS   AGE
+    acme-server-5f9f786f58-89tgl   2/2     Running   0          125m
+    ```
+
+- CONFIGURE_KALM_DASHBOARD_ACCESS: Kalm is waiting for Cloud Provider to assign a public Load Balancer for our Kalm dashboard, use `kubectl describe services -n istio-system istio-ingressgateway` to check the details of our service for the dashboard. Normally the cloud provider will assign a public IP or domain for our service. run `kubectl get services -n istio-system istio-ingressgateway -ojsonpath='{.status}'` to check out the info.
+
+    ```bash
+    ➜  kalm-cloud git:(main) kubectl get services -n istio-system istio-ingressgateway -ojsonpath='{.status}'
+    {"loadBalancer":{"ingress":[{"hostname":"a8298a1a1a8ee473cbb923fa5de3576c-60911533.ap-northeast-1.elb.amazonaws.com"}]}}
+    ```
+
+    if the return result is empty, run `kubectl describe services -n istio-system istio-ingressgateway` to get related events of the service.
+
+    ```bash
+    ➜  kubectl describe services -n istio-system istio-ingressgateway
+    Name:                     istio-ingressgateway
+    Namespace:                istio-system
+    ...
+    Session Affinity:         None
+    External Traffic Policy:  Cluster
+    Events:                   ...
+    ```
+
+    The last section of the output: **Events** may show some related info about the reason why the assignment is not working, there are several possible reasons for the failure: wrong tags of the AWS VPC subnets, number of load balancers is out of quota, etc(see [https://aws.amazon.com/premiumsupport/knowledge-center/eks-load-balancers-troubleshooting/](https://aws.amazon.com/premiumsupport/knowledge-center/eks-load-balancers-troubleshooting/) for more details). It can also happen that the assignment silently fails without any warning events, in this case, it will be really hard to debug, and this is why we strongly suggest you to setup the EKS cluster using our recommend ways here: [https://www.notion.so/kalmhq/TODO-Install-on-EKS-60883f76fc8846babb6a1ccf2c6149df#d8127a07b43448c9af107693b20165c5](https://www.notion.so/kalmhq/TODO-Install-on-EKS-60883f76fc8846babb6a1ccf2c6149df#d8127a07b43448c9af107693b20165c5).
+
+- CONFIGURE_ACME_SERVER_ACCESS: similar to CONFIGURE_KALM_DASHBOARD_ACCESS, this is Kalm waiting for Cloud Provider to assign a public Load Balancer for our ACME DNS server, use `kubectl get service -n kalm-system lb-svc-acme-server  -ojsonpath='{.status}'` and `kubectl describe service -n kalm-system lb-svc-acme-server` to see details of the service.
+
+    ```bash
+    ➜  kubectl get service -n kalm-system lb-svc-acme-server  -ojsonpath='{.status}'
+    {"loadBalancer":{"ingress":[{"hostname":"xxx.elb.ap-northeast-1.amazonaws.com"}]}
+
+    ➜ kubectl describe service -n kalm-system lb-svc-acme-server
+    Name:                     lb-svc-acme-server
+    Namespace:                kalm-system
+    ...
+    Session Affinity:         None
+    External Traffic Policy:  Cluster
+    Events:                   <none>
+    ```
+
+- REPORT_CLUSTER_INFO: Kalm is reporting cluster info like the public IPs and Domains the Cloud Provider just assigned to our to Kalm Cloud.
+- CLUSTER_FULLY_SETUP: Kalm is waiting for the final setup of the cluster, the most time-consuming process is the issuance of the HTTPS certificate of our Kalm dashboard, which can take 10 - 15 minutes.