Search…
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 theext_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:
    2.
    Unzip the Terraform file by entering the following command, for example:
1
tar -xzvf traceable-agent-tf-k8s-[version].tar.gz
Copied!
3. Change directory:
1
cd traceable-agent-tf-k8s-[version]
Copied!
4. Initialize Terraform working directory:
1
terraform init
Copied!
5. Install traceable-agent. Traceable-agent is a bundle of collector, OPA, and ext_authz service.
1
terraform apply -var token=<TOKEN>
Copied!
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 thetme.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.
Before you enable the authentication service, make sure that the authentication service is already running in Ambassador.
1
apiVersion: getambassador.io/v2
2
kind: TracingService
3
metadata:
4
name: ambassador-tracing
5
namespace: traceableai
6
spec:
7
service: "traceable-agent.traceableai:9411"
8
driver: zipkin
9
config: {}
10
---
11
apiVersion: getambassador.io/v2
12
kind: AuthService
13
metadata:
14
name: ambassador-auth
15
namespace: traceableai
16
spec:
17
auth_service: "localhost:5441"
18
proto: grpc
19
failure_mode_allow: true
20
include_body:
21
max_bytes: 131072
22
allow_partial: true
23
---
24
apiVersion: getambassador.io/v2
25
kind: Module
26
metadata:
27
name: ambassador
28
namespace: traceableai
29
spec:
30
config:
31
lua_scripts: |
32
function envoy_on_response(response_handle)
33
local response_body = response_handle:body(true)
34
local headers = {
35
[":method"] = "POST",
36
[":path"] = "/ext_cap/response",
37
[":authority"] = "lua_cluster",
38
}
39
for key, value in pairs(response_handle:headers()) do
40
headers["traceable-cap-" .. key] = value
41
end
42
local headers, body = response_handle:httpCall(
43
"cluster_tracing_traceable_agent_traceableai_9411_traceableai",
44
headers,
45
response_body:getBytes(0, response_body:length()),
46
5000, true)
47
end
Copied!
    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 theallow_partialparameter.
      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.
5. Apply the YAML file - Run the following command: kubectl apply -f traceableai.yaml
6. 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:
1
kubectl get pods -n ambassador
2
NAME READY STATUS RESTARTS AGE
3
ambassador-12345cb64-abcd 2/2 Running 0 77s
Copied!
In the above command, ambassador-*** is the pod name.
Last modified 2mo ago