Project: EaseMesh (Orchestration & Management / Service Mesh)
File: install.md

- - - - - - - - This document gives the instructions to install all infrastructure components (except K8s) required by the EaseMesh. The dependencies of the EaseMesh are the Easegress, EaseAgent, and EaseMesh Operators. Easegress EaseAgent EaseMesh Operator The EaseMesh severely depends on the K8s, all dependencies must be packaged as images, so you need to prepare all three docker images. The Easegress plays multiple roles in the EaseMesh, including: Control plane manages services' registry, configurations for the Mesh. Sidecar takes over all traffic in and out of the application container. Ingress takes over all traffic entered the cluster of the K8s. You can found Easegress from . The latest image has been uploaded by us. You can download it by `docker pull`. ```bash docker pull megaease/easegress ``` If you want to build Easegress from scratch, you cant refer to The EaseAgent is a JavaAgent whose responsibility is collecting metrics and tracing information. It provides observability for services in the Java ecosystems. In a typical scenario, the EaseAgent is a jar package, you can download it from . As the EaseMesh relies on the K8s, we provide a dedicated image for automatically injecting the EaseAgent Jar file from the docker image. The latest image has been uploaded by us. You can download it by `docker pull`. ```bash docker pull megaease/easeagent-initializer ``` EaseMesh Operator is the CRD Operator whose responsibility is when a MeshDeployment (custom resource) is deployed, it renders a deployment spec from the custom resource and injects JavaAgent to service application and a sidecar container to take over all traffics. EaseMesh Operator follow the . EaseMesh Operator implements a control loop that repeatedly compares the desired state (deployment resources which are injected with a sidecar container) of the cluster to its actual state. For convenience, we provide the EaseMesh Operator docker image in docker hub. you can download image via `docker pull`. ```bash docker pull megaease/easemesh-operator ``` You can build easemesh operator image from scratch, please refer Ensuring you have all three images (accessing docker hub without any problems), we will begin our journey. The `emctl` can be built from source code, you may follow this guide to build it. The emctl is implemented in Golang language, you need prepare golang (1.16+) dev environment in advance clone source code ```bash git clone https://github.com/megaease/easemesh ``` build emctl executables ```bash cd easemesh/emctl && make ``` If no errors occurred, the target was built in `bin/` directory, named with `emctl` EaseMesh severely depends on the K8s, in order to install the EaseMesh, you must confirm you have a healthy K8s cluster and sufficient resources (at least three work nodes by default). The installation of the EaseMesh needs admin privilege of K8s cluster, the `emctl` looks for a file named config in the $HOME/.kube directory. The emctl use it to communicate with K8s API server of a cluster. By default, The control plane of the EaseMesh exposes its service via K8s' , so you should ensure that the node running `emctl` can access nodes of the K8s cluster We deploy the control plane of the EaseMesh in a K8s cluster, as the control plane needs to persistent configuration, the persistent volume resource needs to be introduced. The default replicas of the control plane are three, so three PVs are

The capacity of each PV must greater than 3Gi by default. We provide a template spec of PV here for your referring: ```yaml apiVersion: v1 kind: PersistentVolume metadata: name: easemesh-storage-pv-1 spec: capacity: storage: 4Gi volumeMode: Filesystem accessModes: ReadWriteOnce persistentVolumeReclaimPolicy: Delete storageClassName: easemesh-storage local: path: {{specificpathyouneedto_substituted}} nodeAffinity: required: nodeSelectorTerms: matchExpressions: key: kubernetes.io/hostname operator: In values: {{nodenamewithspecificpath}} apiVersion: v1 kind: PersistentVolume metadata: name: easemesh-storage-pv-2 spec: capacity: storage: 4Gi volumeMode: Filesystem accessModes: ReadWriteOnce persistentVolumeReclaimPolicy: Delete storageClassName: easemesh-storage local: path: {{specificpathyouneedto_substituted}} nodeAffinity: required: nodeSelectorTerms: matchExpressions: key: kubernetes.io/hostname operator: In values: {{nodenamewithspecificpath}} apiVersion: v1 kind: PersistentVolume metadata: name: easemesh-storage-pv-3 spec: capacity: storage: 4Gi volumeMode: Filesystem accessModes: ReadWriteOnce persistentVolumeReclaimPolicy: Delete storageClassName: easemesh-storage local: path: {{specificpathyouneedto_substituted}} nodeAffinity: required: nodeSelectorTerms: matchExpressions: key: kubernetes.io/hostname operator: In values: {{nodenamewithspecificpath}} apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: easemesh-storage provisioner: kubernetes.io/no-provisioner reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer ``` Changing contents according to your environment, provisioning it to your K8s cluster. You must ensure all PVs are created normally. We leverage to persistent control plane data. If all prerequisites are fulfilled properly, we can begin to install the EaseMesh. Although there are servals steps that setups required components, it can be done by one command. Steps are: Setup the control plane of the EaseMesh: EaseMesh leverage the Easegress implementing control plane, the installation will deploy Easegress as `statefulset` resource of the K8s Provision mesh controller: Mesh controller is implemented in the Easegress, but it is disabled by default. Installation needs to apply a configuration to enable the Mesh controller. Create the `Custom Resource Definition`: EaseMesh leverages custom resource definition to manage an application. Installation needs to create it in advance. Provision the Operator: The Operator is used to reconciling custom resources to deployment resources. Provision Mesh ingress: Mesh ingress is used to take over traffics entering in K8s cluster The installation will run all steps one by one. Install command is: ```bash emctl install ``` If you want to speed up your installation, you can tag all three images and uploaded them into your local private docker registry. Specific private docker registry to install, just simply add an extra argument. ```bash emctl install --image-registry-url {yourprivatedockerregistryaddress} ``` more arguments can be discovered via: ```bash emctl install --help ``` Add-on features could be installed at the same time of EaseMesh installation with an additional command line flag `--add-ons={addon1,addon2,...}`. For example, to install the shadow service feature: ```bash emctl install -add-ons=ShadowService ``` If EaseMesh infrastructure has already been installed, the add-on features could installed by the `--only-add-on` flag in the `emctl install` command line: ```bash emctl install --only-add-on --add-ons=ShadowService ``` NOTICE: Installing EaseMesh didacated CoreDNS will cover original CoreDNS spec and config in kube-system. If you want to support pure spring-boot (without spring-cloud suite) application or non-Java languages, installing EaseMesh dedicated CoreDNS is a must. It's very easy to do it: ```bash emctl install coredns --replicas 1 ``` more arguments can be discovered via: ```bash emctl install coredns --help ``` If you want to remove the EaseMesh, just run the command: ```bash emctl reset ``` PVC and PV resources will not be reclaimed by default. you need to delete them manually. To only uninstall an add-on, run the command: ```bash emctl reset --only-add-on --add-ons={addon1,addon2,...} ``` There are a known issue, during the EaseMesh installation, the embed `etcd` of the Easegress can't be setup correctly. If you encounter this situation, just delete all persistent contents in nodes