- 01 Dec 2021
- 3 Minutes to read
-
PDF
Ambassador
- Updated on 01 Dec 2021
- 3 Minutes to read
-
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.
Traceable's tracing agent (or tracing agent) for Ambassador installation process is divided into the following:
- Download Terraform file.
- Install Traceable agent for Ambassador.
- Enable tracing in Ambassador.
- Enable authentication service in Ambassador
Install Ambassador agent
Complete the following steps to download and configure Traceable's Ambassador agent:
- Download the Terraform file from https://downloads.traceable.ai/#install/traceable-agent/terraform/kubernetes/
- Unzip the Terraform file by entering the following command, for example:
tar -xzvf traceable-agent-tf-k8s-[version].tar.gz
- Change directory:
cd traceable-agent-tf-k8s-[version]
- Initialize Terraform working directory:
terraform init
- 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:
- Sidecar injection - Ensure that the latest traceable-agent service is running.
- 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
- Add an annotation - Add the
tme.traceable.ai/inject: true
annotation to the pod in which Ambassador is running. - 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 totrue
, Ambassador sends the firstmax_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 totrue
, 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.
- Apply the YAML file - Run the following command:
kubectl apply -f traceableai.yaml
- Restart the Ambassador pod.
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.