Quickstart

Maesh can be installed in your cluster without affecting any running services. It can safely be installed using the Helm Chart.

Prerequisites

RBAC

Depending on the tool you used to deploy your cluster you might need to tweak RBAC permissions.

kubeadm

If you used kubeadm to deploy your cluster, a fast way to allow the helm installation to perform all steps it needs is to edit the cluster-admin ClusterRoleBinding, adding the following to the subjects section:

- kind: ServiceAccount
  name: default
  namespace: kube-system

Installing Maesh

helm repo add maesh https://containous.github.io/maesh/charts
helm repo update
helm install maesh maesh/maesh
[...]

NOTES:
Thank you for installing maesh.

Your release is named maesh.

To learn more about the release, try:

  $ helm status maesh
  $ helm get maesh

Using Maesh

As an example, let's deploy a server application and a client application under the maesh-test namespace.

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: server
  namespace: maesh-test
  labels:
    app: server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: server
  template:
    metadata:
      labels:
        app: server
    spec:
      containers:
        - name: server
          image: containous/whoami:v1.4.0
          ports:
            - containerPort: 80
---
kind: Service
apiVersion: v1
metadata:
  name: server
  namespace: maesh-test
spec:
  selector:
    app: server
  ports:
    - name: web
      protocol: TCP
      port: 80
      targetPort: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: client
  namespace: maesh-test
  labels:
    app: client
spec:
  replicas: 1
  selector:
    matchLabels:
      app: client
  template:
    metadata:
      labels:
        app: client
    spec:
      containers:
        - name: client
          image: giantswarm/tiny-tools:3.9
          imagePullPolicy: IfNotPresent
          command:
            - "sleep"
            - "infinity"

Create the namespace then deploy those two applications:

kubectl create namespace maesh-test
kubectl apply -f server.yaml
kubectl apply -f client.yaml

You should now see the following output:

kubectl get all -n maesh-test
NAME                          READY     STATUS    RESTARTS   AGE
pod/client-7446fdf848-x96fq   1/1       Running   0          79s
pod/server-7c8fd58db5-rchg8   1/1       Running   0          77s
pod/server-7c8fd58db5-sd4f9   1/1       Running   0          77s

NAME             TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
service/server   ClusterIP   10.43.17.247   <none>        80/TCP    77s

NAME                     READY     UP-TO-DATE   AVAILABLE   AGE
deployment.apps/client   1/1       1            1           79s
deployment.apps/server   2/2       2            2           77s

NAME                                DESIRED   CURRENT   READY     AGE
replicaset.apps/client-7446fdf848   1         1         1         79s
replicaset.apps/server-7c8fd58db5   2         2         2         77s

Take note of the client app pod name (here it's client-7446fdf848-x96fq) and open a new terminal session inside this pod using kubectl exec.

kubectl -n maesh-test exec -ti client-7446fdf848-x96fq ash

From inside the client container, make sure your server is reachable using the Kubernetes DNS service discovery.

curl server.maesh-test.svc.cluster.local
Hostname: server-7c8fd58db5-sd4f9
IP: 127.0.0.1
IP: ::1
IP: 10.42.2.10
IP: fe80::a4ec:77ff:fe37:1cdd
RemoteAddr: 10.42.2.9:46078
GET / HTTP/1.1
Host: server.maesh-test.svc.cluster.local
User-Agent: curl/7.64.0
Accept: */*

You can note that all this server application is doing is to respond with the content of the request it receives.

Now replace the svc.cluster.local suffix by maesh, and tada: you are now using Maesh to reach your server!

curl server.maesh-test.maesh
Hostname: server-7c8fd58db5-rchg8
IP: 127.0.0.1
IP: ::1
IP: 10.42.1.7
IP: fe80::601d:7cff:fe26:c8c6
RemoteAddr: 10.42.1.5:59478
GET / HTTP/1.1
Host: server.maesh-test.maesh
User-Agent: curl/7.64.0
Accept: */*
Accept-Encoding: gzip
Uber-Trace-Id: 3f9e7129a059f70:7e889a1ebcb147ac:3f9e7129a059f70:1
X-Forwarded-For: 10.42.2.9
X-Forwarded-Host: server.maesh-test.maesh
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: maesh-mesh-w95q2
X-Real-Ip: 10.42.2.9

Note the presence of X-Forwarded headers as well as other instrumentation headers like Uber-Trace-Id, indicating than your request has been processed and instrumented by Maesh.

What's next

See the examples page to see a more advanced example, or dive into the configuration to discover all Maesh capabilities.