Quickstart

    • Kubernetes 1.11+
    • CoreDNS installed as (versions 1.3+ supported)
    • Helm v3

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

    kubeadm

    If you used 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:

    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. [...]
    3. NOTES:
    4. Thank you for installing maesh.
    6. Your release is named maesh.
    8. To learn more about the release, try:
    10.   $ helm status maesh
    11.   $ helm get 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.     app: server
    8. spec:
    9.   replicas: 2
    10.   selector:
    11.     matchLabels:
    13.   template:
    14.     metadata:
    15.       labels:
    16.         app: server
    17.     spec:
    18.       containers:
    19.         - name: server
    20.           image: containous/whoami:v1.4.0
    21.           ports:
    22.             - containerPort: 80
    23. ---
    24. kind: Service
    25. apiVersion: v1
    26. metadata:
    27.   name: server
    28.   namespace: maesh-test
    29. spec:
    30.   selector:
    31.     app: server
    32.   ports:
    33.     - name: web
    34.       protocol: TCP
    35.       port: 80

    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/1       Running   0          79s
    4. pod/server-7c8fd58db5-sd4f9   1/1       Running   0          77s
    6. NAME             TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
    7. service/server   ClusterIP   10.43.17.247   <none>        80/TCP    77s
    9. NAME                     READY     UP-TO-DATE   AVAILABLE   AGE
    10. deployment.apps/client   1/1       1            1           79s
    11. deployment.apps/server   2/2       2            2           77s
    13. NAME                                DESIRED   CURRENT   READY     AGE
    14. replicaset.apps/client-7446fdf848   1         1         1         79s
    15. 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.

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

    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

    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

    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.