Ambassador

Traceable integrates with Ambassador Edge Stack to provide visibility into the traffic coming into your environment. At its core, Ambassador Edge Stack is an API gateway that serves as the entry point for all incoming traffic to a Kubernetes cluster. It acts as a reverse proxy that routes requests to the appropriate microservice and performs various functions such as load balancing, traffic management, and authentication.

In addition to the API gateway, Ambassador Edge Stack also includes a set of modules that extend its capabilities, such as rate limiting, circuit breaking, and observability. These modules can be configured and deployed alongside the API gateway to provide additional functionality. Ambassador Edge Stack 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.

The following is a high-level deployment diagram. Ambassador tracing service, module and AuthService along with Traceable module extension are deployed or injected by Traceable.

Before you begin

Make a note of the following points before starting the configuration:

• Make sure that you have a working Ambassador Edge Stack setup.
• Version 2.5.1 of Edge Stack is supported.
• Make sure that Traceable Platform agent 1.29.2 or later is installed. You can use Terraform or Helm installation. It is recommended to use Helm chart to install Traceable Platform agent, since Ambassador Edge Stack uses Helm. For more information on Traceable Platform agent Helm installation, see Helm.
• Important ports:
  • OTLP - 4317
  • ZIPKIN - 9411
  • Traceable agent configuration - 5441

Instrument Ambassador

Makes sure that you have installed Traceable's public repo when you installed Traceable Platform in the Before you begin section. Complete the following steps to instrument Ambassador. The steps are:

1. Labeling the namespace
2. Patching the deployment
3. Installing Traceable's Ambassador Helm chart
4. Rollout

Steps

1. Label the Ambassador namespace with the injection label for tme (Traceable module extension). Enter the following command:
   ActionScriptActionScript

   kubectl label ns ambassador traceableai-inject-tme=enabled

2. Patch the edge-stack deployment with the injection annotation:
   ActionScriptActionScript

   kubectl patch deployment.apps/edge-stack -p '{"spec": {"template": {"metadata": {"annotations": {"tme.traceable.ai/inject": "true"}}}}}' -n ambassador

   This is a command to patch the Kubernetes deployment named “edge-stack” in the “ambassador” namespace using the “kubectl” command-line tool. Specifically, it is adding an annotation to the deployment's pod template metadata to enable the injection of a sidecar container from Traceable's image repository.

   Here's a breakdown of the command:

   • kubectl: The command-line tool for interacting with Kubernetes clusters
   • patch deployment.apps/edge-stack: The object to patch is a deployment named “edge-stack” in the “deployment.apps” API group.
   • -p: Specifies the patch to apply in JSON format.
   • '{"spec": {"template": {"metadata": {"annotations": {"tme.traceable.ai/inject": "true"}}}}}': the JSON patch itself, which adds an annotation to the pod template metadata
   • -n ambassador: The namespace in which to apply the patch is “ambassador”

   The added annotation “tme.traceable.ai/inject” with a value of “true” is used by Traceable's Platform to inject a sidecar container that monitors and protects the microservices running in the Kubernetes cluster. 

3. Install Traceable's Ambassador Helm chart, which contains the following:
   1. Ambassador's TracingService: Enables Tracing in Ambassador. This allows Traceable to correlate the transactions through the HTTP request journey. Traceable uses the open source Zipkin driver running on the default port 9411.
   2. Ambassador's AuthService: Enables the Ambassador authentication plugin, which is used by traceable for request capture and blocking.
   3. Module Kubernestes resources: Captures the data.

      Enter the following command:

      ActionScriptActionScript

      helm install traceableai-ambassador traceableai/traceableai-ambassador -n traceableai

      Here is a breakdown of the command:
      • helm install: The command to install a chart using the Helm package manager
      • traceableai-ambassador: The name to give to the Helm release
      • traceableai/traceableai-ambassador: The name of the chart to install, in the format of repository/chart-name. In this case, the chart is named “traceableai-ambassador”.
      • -n traceableai: The namespace in which to install the chart is “traceableai”

        The traceableai-ambassador Helm chart is used to deploy the Traceable as a sidecar container to the Ambassador Edge Stack. The Helm chart handles the installation and configuration of the traceableai-ambassador container, making it easier to integrate Traceable's security features into a Kubernetes environment.

4. Rollout restart the edge-stack deployment. Enter the following command:
   ActionScriptActionScript

   kubectl rollout restart deployment edge-stack -n ambassador

   Here is a breakdown of the command:

   • kubectl: the command-line tool for interacting with Kubernetes clusters
   • rollout restart deployment edge-stack: the command to restart the pods of the deployment named “edge-stack”
   • -n ambassador: the namespace in which the deployment is located is “ambassador”
     The rolling update strategy used by Kubernetes ensures that the deployment is updated with zero downtime by gradually replacing the old pods with new ones. This ensures that the application remains available and responsive during the update process. When the rolling update is initiated, Kubernetes creates a new set of pods with the updated deployment configuration and gradually replaces the old pods with the new ones. Once all the new pods are running and healthy, Kubernetes removes the old pods and completes the update process. By default, Kubernetes replaces one pod at a time to minimize the impact on the application's availability.

Verification

To verify a successful instrumentation, check that each edge-stack has two containers running it. The additional container is the injected tme (Traceable module extension). Note that it may take a few minutes for the injected pods to be available. 

Enter the following command to verify:

traceabluser@traceableai ambassador-test-app-yaml % kubectl get pods -n ambassador

The output:

NAME                               READY   STATUS    RESTARTS   AGE
edge-stack-6c97db5c79-89c9s        2/2     Running   0          92s
edge-stack-6c97db5c79-bgbxq        2/2     Running   0          59s
edge-stack-6c97db5c79-htbcn        1/2     Running   0          26s
edge-stack-agent-b576745c9-bfsv8   1/1     Running   0          46m
edge-stack-cdf8f8dfc-zrcvd         1/1     Running   0          46m
edge-stack-redis-f54fd4585-mdjs5   1/1     Running   0          46m

For example, you can send a curl request and verify that the request is visible in Traceable Platform. This would be different for your environment. Enter the following command:

curl -Lki https://$LB_ENDPOINT/backend/

Here is a breakdown of the command:

• curl: The command-line tool used to send the HTTP request
• -Lki: Specifies that curl should follow redirects (-L) and return the response headers (-i) and response body (-k) of the HTTP request. The “-k” flag also indicates that curl should ignore SSL certificate validation.
• https://$LB_ENDPOINT/backend/: The URL to which the HTTP GET request is sent. The “$LB_ENDPOINT” variable represents the endpoint of the load balancer, and “/backend/“ is the endpoint path of the application running behind the load balancer.

Remove instrumentation

To remove Ambassador instrumentation, complete the following steps:

1. Uninstall traceableai-ambassador helm chart installation. Enter the following command:
   ActionScriptActionScript

   helm uninstall traceableai-ambassador -n traceableai

2. Undo the patch of edge-stack deployment. Enter the following command:
   ActionScriptActionScript

   kubectl patch deployment.apps/edge-stack --type=json -p '[{"op":"remove","path":"/spec/template/metadata/annotations/tme.traceable.ai~1inject"}]' -n ambassador

   Here is a breakdown of the command:

   • kubectl: The command-line tool for interacting with Kubernetes clusters
   • patch deployment.apps/edge-stack: The object to patch is a deployment named “edge-stack” in the “deployment.apps” API group
   • --type=json: specifies that the patch is in JSON format
   • -p: specifies the patch to apply
   • '[ {"op":"remove","path":"/spec/template/metadata/annotations/tme.traceable.ai~1inject"} ]': the JSON patch itself, which removes the “tme.traceable.ai/inject” annotation from the pod template metadata
   • -n ambassador: the namespace in which to apply the patch is “ambassador”
3. Remove the label of the ambassador namespace. Enter the following command:
   ActionScriptActionScript

   kubectl label ns ambassador traceableai-inject-tme-

4. (Optional) If you wish, remove the Traceable Platform agent. Enter the following command:
   ActionScriptActionScript

   helm uninstall traceable-agent -n traceableai

5. (Optional) If you wish, delete the traceableai namespace. Enter the following command:
   ActionScriptActionScript

   kubectl delete namespace traceableai