Installation

To install Maesh, the installation method is quite simple:

  1. helm repo add maesh https://containous.github.io/maesh/charts
  2. helm repo update

Install Maesh Helm Chart:

  1. helm install maesh maesh/maesh

Install from source

Supported Installations

Please be aware that the supported installation method is via Helm, using official releases. If you want to build/install/run Maesh from source, we may not be able to provide support. Installing from source is intended for development/contributing.

To build the image locally, run:

  1. make

You will then be able to use the tagged image as your image in your values.yaml file.

Deploy Helm Chart

To deploy the Helm Chart, run:

  1. helm install maesh helm/chart/maesh --set image.pullPolicy=IfNotPresent --set image.tag=latest

KubeDNS support

Maesh supports KubeDNS:

  1. helm install maesh maesh/maesh --set kubedns=true

With the kubedns parameter Maesh will install CoreDNS and patch KubeDNS to use it as a stubDomain.

Custom cluster domain

If you use a cluster domain other than cluster.local set it by using the clusterDomain parameter:

  1. helm install maesh maesh/maesh --set clusterDomain=my.custom.domain.com

Access Control List

By default, Maesh does not restrict traffic between pods and services. However, some scenarios require more control over the rules for internal communication. The Access Control List mode (ACL) requires a set of rules to explicitly allow traffic between different resources.

To enable ACL, install Maesh in ACL mode by setting the acl Helm Chart option to true.

  1. helm install maesh --namespace=maesh maesh/maesh --set acl=true

Maesh supports the SMI specification which defines a set of custom resources to provide a fine-grained control over instrumentation, routing and access control of east-west communications.

CRDs

Helm v3 will install automatically the CRDs in the /crds directory. If you are (re)installing into a cluster with the CRDs already present, Helm may print a warning. If you do not want to install them, or want to avoid the warning, use the new --skip-crds flag. More information can be found in the Helm documentation.

Platform recommendations

Maesh works on Kubernetes environments that conforms to the global Kubernetes specification. That being said, we have had users encounter issues when using variants such as minikube, microk8s, and other development distributions.

Maesh runs without issue on most public clouds (AWS, GKE, Azure, DigitalOcean, and more). If you want to run Maesh in development, we would recommend using k3s, as it is fully conformant. We use k3s in Maesh’s integration tests, so you can be sure that it works properly.

If you encounter issues on variants such as minikube or microk8s, please try and reproduce the issue on k3s. If you are unable to reproduce, it may be an issue with the distribution behaving differently than official Kubernetes.

Verify your installation

You can check that Maesh has been installed properly by running the following command:

Command

  1. kubectl get all -n maesh

Expected Output

  2. NAME                                    READY   STATUS    RESTARTS   AGE
  3. pod/maesh-controller-676fb86b89-pj8ph   1/1     Running   0          11s
  4. pod/maesh-mesh-w62z5                    1/1     Running   0          11s
  5. pod/maesh-mesh-zjlpf                    1/1     Running   0          11s
  7. NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
  8. service/maesh-mesh-api   ClusterIP   100.69.177.254   <none>        8080/TCP   29s
  10. NAME                        DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
  11. daemonset.apps/maesh-mesh   2         2         0       2            0           <none>          29s
  13. NAME                               DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  14. deployment.apps/maesh-controller   1         1         1            0           28s
  16. NAME                                          DESIRED   CURRENT   READY   AGE
  17. replicaset.apps/maesh-controller-676fb86b89   1         1         0       28s

Usage

To use Maesh, instead of referencing services via their normal <servicename>.<namespace>, instead use <servicename>.<namespace>.maesh. This will access the Maesh service mesh, and will allow you to route requests through Maesh.

By default, Maesh is opt-in, meaning you have to use the Maesh service names to access the mesh, so you can have some services running through the mesh, and some services not.