Kuma

Kuma is an open-source control plane for service mesh and microservices management. The topic explains integrating Traceable'e tracing agent in Kuma deployment to secure and monitor services managed by Kuma. 

Traceable's tracing agent deployment consists of the following steps:

1. Setting up Kuma (optional)
2. Setting up Traceable services
3. Setting up Kuma traffic trace
4. Deploy Kuma proxy template

Traceable token

Before starting with installation, make sure that you have Traceable's agent token. Using your Traceable login credentials, log in to Traceable. Click on Settings()→ Account → Agent Token.

Setup Kuma 

This is an optional step. If you already have a Kuma set up, proceed to the next section.

Complete the following steps to set up Kuma:

1. Download Kuma. Enter the following command:

curl -L <https://kuma.io/installer.sh> | sh -

2. Add kumactl to your PATH, for example:

export PATH=/Users/A_User/Downloads/kuma-1.3.0/bin:$PATH

kumctl is the user CLI for interacting with Kuma and its data. 

3. Install the Kuma control plane. Enter the following command:

kumactl install control-plane | kubectl apply -f -

Setup Traceable services

Complete the following steps to install Traceable service:

1. Add traceableai helm repo. Traceable supports Helm 3 only.

helm repo add traceableai https://traceableai.github.io/charts && helm repo update

2. Create a values.yaml. Use the agent token from the Traceable token section. The environment is your deployment environment, for example, production, development, QA, and so on.

global:
  clusterName: <CLUSTER NAME>
  token: <contact Traceable Sales for token>
  environment: <ENV>

3. Install Traceable service:

helm install traceableai traceableai/traceableai -n traceableai --values values.yaml

Setup Kuma traffic trace

Traffic trace is a Kuma policy that allows trace logging for Traceable. Tracing is supported on any HTTP traffic in Mesh. Tracing will only work with data planes and services that have the kuma.io/protocol: http tag defined. 

Apply the following traffic trace file. This enables Traceable to report trace data to the Traceable service configured in step 3 of the previous section. 

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  tracing:
    defaultBackend: traceable-agent
    backends:
    - name: traceable-agent
      type: zipkin
      sampling: 100.0
      conf:
        url: http://agent.traceableai.svc.cluster.local:9411/api/v2/spans

---
apiVersion: kuma.io/v1alpha1
kind: TrafficTrace
mesh: default
metadata:
  name: trace-all-traffic
spec:
  selectors:
    - match:
        kuma.io/service: '*' # Note - the '*' here will match all services
  conf:
    backend: traceable-agent

Save the above sample snippet in a file, for example, traffic-trace.yml and then apply the file. Enter the following command:

kubectl apply -f traffic-trace.yaml

Deploy Kuma proxy template

The Kuma proxy template adds ext_authz and response capturing filters to the Kuma sidecar Envoy proxies. Complete the following steps to install a publicly available chart:

1. Make sure that chart is available in your helm repo:

helm search repo traceableai

NAME                         	CHART   VERSION	APP VERSION	DESCRIPTION                               
helm/traceableai             	1.0.118      	           	  Helm chart for all traceable.ai components
traceableai/traceableai-kuma	1.7.2        	           	  Helm chart for Traceable Kuma Dateplane module 

2. Install the chart.

You can override the chart options during install by creating and modifying the values.yaml Below are the default values:

# Maximum captured payload size
bodyCaptureSize: 131072

# When set to true, Kuma will accept client request even if the communication
# with the ext_cap (instrumentation) failed, or if the ext_cap service has returned a HTTP 5xx error.
allowFailureMode: true

# The namespace into which traceable-agent has been installed
traceableAgentNamespace: traceableai

# module extension ports:
# the module extension is deployed as a sidecar, therefore its ports can collide with the application ports.
moduleExtensionGRPCPort: 5441
moduleExtensionHTTPPort: 5442

# IP address of the module extension service
moduleExtensionIPAddress: 127.0.0.1

# Kuma service to add proxy-template to
kumaService: "*"

# Which mesh the proxy template will be used in
mesh: default

# We will capture response bodies whose content-type header is one of the below.
allowedContentTypes: |
  {'application/json', 'application/vnd.api+json', 'application/x-www-form-urlencoded', 'application/grpc', 'application/grpc+json', 'application/grpc+proto', 'application/grpc-web', 'application/grpc-web+json', 'application/grpc-web+proto', 'application/grpc-web-text', 'application/grpc-web-text+proto'}

Enter the following command:

helm install traceable-kuma traceableai/traceableai-kuma --values ./values.yaml   

3. Verify that the proxy template is successfully installed. Enter the following command:

kubectl get proxytemplates.kuma.io 

NAME             AGE
traceable-kuma   113m

Annotations

Make a note of the following important annotations for kuma.io:

Namespace annotation

Make sure that the namespace is annotated with the following:

kuma.io/sidecar-injection: enabled
kuma.io/mesh: default

Deployment annotation

Make sure that the deployment is annotated with the following:

kuma.io/sidecar-injection: enabled
kuma.io/protocol: http

 Service annotation

Make sure that the service is annotated with the following:

80.service.kuma.io/protocol: http # 80 here would be the port your service is exposed
kuma.io/service: <your-service>
kuma.io/mesh: default