• 01 Dec 2021
  • 3 Minutes to read
  • PDF


  • PDF

This guide illustrates the integration of Traceable with Ambassador Edge Stack, a cloud-native API gateway and ingress controller for Kubernetes, built upon Envoy proxy.

Traceable uses Terraform to install traceable-agent for Ambassador. The traceable-agent is a bundle of collector and Open Policy Agent (OPA) rules. The agent also hosts the ext_authz service. Ambassador API gateway communicates with the traceable-agent that captures the request and response data. The captured data is sent to the Traceable platform for further processing. The traceable-agent also blocks the requests based on OPA rules.

Ambassador uses B3 propagation format. If you wish to correlate traces of other services, they must also use the B3 propagation format.

 Traceable's tracing agent (or tracing agent) for Ambassador installation process is divided into the following:

  1. Download Terraform file.
  2. Install Traceable agent for Ambassador.
  3. Enable tracing in Ambassador.
  4. Enable authentication service in Ambassador

Install Ambassador agent

Complete the following steps to download and configure Traceable's Ambassador agent:

  1. Download the Terraform file from 
  2. Unzip the Terraform file by entering the following command, for example:
tar -xzvf traceable-agent-tf-k8s-[version].tar.gz
  1. Change directory:
cd traceable-agent-tf-k8s-[version]
  1. Initialize Terraform working directory:
terraform init
  1. Install traceable-agent. Traceable-agent is a bundle of collector, OPA, and ext_authz service.
terraform apply -var token=<TOKEN>

The above command installs traceable-agent using Terraform in each node or machine. To generate the<TOKEN>, login to Traceable and click on Onboarding.

Copy the access token from the Onboarding page.

Enable tracing, authentication service, and response capturing

You need to enable few Ambassador resources for Traceable to capture tracing information. The following resources have to be enabled:

Complete the following steps to enable tracing, authentication service, and response capturing:

  1. Sidecar injection - Ensure that the latest traceable-agent service is running.
  2. Add a label - Add the traceableai-inject-tme=enabled label to the namespace in which Ambassador is running. For example, kubectl label ns ambassador traceableai-inject-tme=enabled
  3. Add an annotation - Add the true annotation to the pod in which Ambassador is running. 
  4. Configure the YAML file - Save the following to the traceableai.yml file.
Before you enable the authentication service, make sure that the authentication service is already running in Ambassador.
kind: TracingService
  name: ambassador-tracing
  namespace: traceableai
  service: "traceable-agent.traceableai:9411"
  driver: zipkin
  config: {}
kind: AuthService
  name: ambassador-auth
  namespace: traceableai
  auth_service: "localhost:5441"
  proto: grpc
  failure_mode_allow: true
    max_bytes:  131072
    allow_partial: true
kind:  Module
  name:  ambassador
  namespace: traceableai
    lua_scripts: |
      function envoy_on_response(response_handle)
        local response_body = response_handle:body(true)
        local headers = {
            [":method"] = "POST",
            [":path"] = "/ext_cap/response",
            [":authority"] = "lua_cluster",
        for key, value in pairs(response_handle:headers()) do
          headers["traceable-cap-" ..  key] = value
        local headers, body = response_handle:httpCall(
          response_body:getBytes(0, response_body:length()),
          5000, true)
  • TracingService - Enables Tracing in Ambassador. This allows Traceable to correlate the transactions through the http request journey. Traceable uses the opensource Zipkin driver running on the default port 9411. 
  • AuthService - Enables the ambassador authentication plugin which is used by traceable for request capture and blocking. 
    • max_byte - This is a mandatory parameter. It controls the maximum number of bytes that are sent to the authentication service. 
    • allow_partial - This is a mandatory parameter. It controls what happens when the request body is of a size larger than max_bytes. The possible values are true and false. When set to true, Ambassador sends the first max_bytes of body to the authentication service. 
    • It is recommended to not change the default value of the allow_partial parameter.
    • failure_mode_allow is optional. When you set it to true, the request is sent to the backend service if the authentication service is not available for some reason.
Make sure that only one authentication service is used when Traceable is deployed. However, you can use filters with an authentication service. For more information on Ambassador filters, see Filter Type.
  •  Module - Defines system-wide configuration for ambassador. Used to enable the traceable lua filter which is used for response capture.
Traceable requires Lua module to capture responses. Make sure that the Lua module is installed before proceeding.
  1. Apply the YAML file - Run the following command: kubectl apply -f traceableai.yaml
  2. Restart the Ambassador pod.
The examples for enabling tracing and authentication assumes that traceable-agent is installed in traceableai namespace. If you are installing the agent in a different namespace, change the service name accordingly.

Verify sidecar injection

To verify that the sidecar injection is successful, run the following command:

kubectl get pods -n ambassador
NAME                          READY   STATUS    RESTARTS   AGE
ambassador-12345cb64-abcd     2/2     Running   0          77s

 In the above command, ambassador-*** is the pod name.

Was this article helpful?