Ambassador

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.

 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 https://downloads.traceable.ai/#install/traceable-agent/terraform/kubernetes/ 
2. Unzip the Terraform file by entering the following command, for example:

tar -xzvf traceable-agent-tf-k8s-[version].tar.gz

3. Change directory:

cd traceable-agent-tf-k8s-[version]

4. Initialize Terraform working directory:

terraform init

5. 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 tme.traceable.ai/inject: true annotation to the pod in which Ambassador is running. 
4. Configure the YAML file - Save the following to the traceableai.yml file.

apiVersion: getambassador.io/v2
kind: TracingService
metadata:
  name: ambassador-tracing
  namespace: traceableai
spec:
  service: "traceable-agent.traceableai:9411"
  driver: zipkin
  config: {}
---
apiVersion: getambassador.io/v2
kind: AuthService
metadata:
  name: ambassador-auth
  namespace: traceableai
spec:
  auth_service: "localhost:5441"
  proto: grpc
  failure_mode_allow: true
  include_body:
    max_bytes:  131072
    allow_partial: true
---
apiVersion: getambassador.io/v2
kind:  Module
metadata:
  name:  ambassador
  namespace: traceableai
spec:
  config:
    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
        end
        local headers, body = response_handle:httpCall(
          "cluster_tracing_traceable_agent_traceableai_9411_traceableai",
          headers,
          response_body:getBytes(0, response_body:length()),
          5000, true)
      end

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

•  Module - Defines system-wide configuration for ambassador. Used to enable the traceable lua filter which is used for response capture.

5. Apply the YAML file - Run the following command: kubectl apply -f traceableai.yaml
6. Restart the Ambassador pod.

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.