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-adminClusterRoleBinding, adding the following to the subjects section:

  1. - kind:ServiceAccount
  2. name:default
  3. namespace: kube-system

Installing Maesh

Command

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

Expected output

  1. [...]
  2. NOTES:
  3. Thank you for installing maesh.
  4. Your release is named maesh.
  5. To learn more about the release,try:
  6. $ helm status maesh
  7. $ helm get maesh

Using Maesh

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

server.yaml

  1. ---
  2. apiVersion: apps/v1
  3. kind:Deployment
  4. metadata:
  5. name: server
  6. namespace: maesh-test
  7. labels:
  8. app: server
  9. spec:
  10. replicas:2
  11. selector:
  12. matchLabels:
  13. app: server
  14. template:
  15. metadata:
  16. labels:
  17. app: server
  18. spec:
  19. containers:
  20. - name: server
  21. image: containous/whoami:v1.4.0
  22. ports:
  23. - containerPort:80
  24. ---
  25. kind:Service
  26. apiVersion: v1
  27. metadata:
  28. name: server
  29. namespace: maesh-test
  30. spec:
  31. selector:
  32. app: server
  33. ports:
  34. - name: web
  35. protocol: TCP
  36. port:80
  37. targetPort:80

client.yaml

  1. ---
  2. apiVersion: apps/v1
  3. kind:Deployment
  4. metadata:
  5. name: client
  6. namespace: maesh-test
  7. labels:
  8. app: client
  9. spec:
  10. replicas:1
  11. selector:
  12. matchLabels:
  13. app: client
  14. template:
  15. metadata:
  16. labels:
  17. app: client
  18. spec:
  19. containers:
  20. - name: client
  21. image: giantswarm/tiny-tools:3.9
  22. imagePullPolicy:IfNotPresent
  23. command:
  24. -"sleep"
  25. -"infinity"

Create the namespace then deploy those two applications:

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

You should now see the following output:

Command

  1. kubectl get all -n maesh-test

Expected output

  1. NAME READY STATUS RESTARTS AGE
  2. pod/client-7446fdf848-x96fq 1/1Running079s
  3. pod/server-7c8fd58db5-rchg8 1/1Running077s
  4. pod/server-7c8fd58db5-sd4f9 1/1Running077s
  5. NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
  6. service/server ClusterIP10.43.17.247<none>80/TCP 77s
  7. NAME READY UP-TO-DATE AVAILABLE AGE
  8. deployment.apps/client 1/11179s
  9. deployment.apps/server 2/22277s
  10. NAME DESIRED CURRENT READY AGE
  11. replicaset.apps/client-7446fdf84811179s
  12. replicaset.apps/server-7c8fd58db522277s

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.

  1. 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.

Command

  1. curl server.maesh-test.svc.cluster.local

Expected Output

  1. Hostname: server-7c8fd58db5-sd4f9
  2. IP:127.0.0.1
  3. IP:::1
  4. IP:10.42.2.10
  5. IP: fe80::a4ec:77ff:fe37:1cdd
  6. RemoteAddr:10.42.2.9:46078
  7. GET / HTTP/1.1
  8. Host: server.maesh-test.svc.cluster.local
  9. User-Agent: curl/7.64.0
  10. 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!

Command

  1. curl server.maesh-test.maesh

Expected Output

  1. Hostname: server-7c8fd58db5-rchg8
  2. IP:127.0.0.1
  3. IP:::1
  4. IP:10.42.1.7
  5. IP: fe80::601d:7cff:fe26:c8c6
  6. RemoteAddr:10.42.1.5:59478
  7. GET / HTTP/1.1
  8. Host: server.maesh-test.maesh
  9. User-Agent: curl/7.64.0
  10. Accept:*/*
  11. Accept-Encoding: gzip
  12. Uber-Trace-Id: 3f9e7129a059f70:7e889a1ebcb147ac:3f9e7129a059f70:1
  13. X-Forwarded-For: 10.42.2.9
  14. X-Forwarded-Host: server.maesh-test.maesh
  15. X-Forwarded-Port: 80
  16. X-Forwarded-Proto: http
  17. X-Forwarded-Server: maesh-mesh-w95q2
  18. 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.