Platform agent to Traceable Platform via HTTP/1.1

If your proxy does not support HTTP/2, it can be challenging for the Traceable Platform Agent (TPA) to communicate with the Traceable platform. By default, communication between the TPA and the platform happens over gRPC, which relies on HTTP/2. To solve this, you can deploy an optional Envoy sidecar proxy. This proxy converts gRPC to HTTP/1.1 and forwards the traffic through your proxy, ensuring seamless communication even when HTTP/2 is unavailable.

The following diagram illustrates the data flow using the Envoy sidecar to convert gRPC messages sent over HTTP/2 to HTTP/1.1. This setup is useful when your proxy only supports HTTP/1.1, ensuring that communication between the Traceable Platform Agent (TPA) and the Traceable Platform remains functional.

Data flow

Following is an explanation of data from the Platform agent to the Traceable Platform through Envoy Sidecar:

1. Platform Agent

The data flow starts with the Platform Agent (TPA), which initiates communication with the Traceable platform using gRPC messages over HTTP/2. By default, gRPC uses HTTP/2 to send messages, which is the preferred communication protocol for TPA.

2. Envoy Sidecar

When the TPA is deployed in an environment where the user’s proxy does not support HTTP/2, an Envoy sidecar is deployed alongside the agent. The Envoy sidecar is responsible for:

• Converting gRPC (HTTP/2) to HTTP/1.1: Since the proxy only supports HTTP/1.1, Envoy translates the gRPC messages that TPA sends using HTTP/2 into standard HTTP/1.1 messages.

• Managing Proxy Connections: Envoy handles the connection to the user’s proxy, ensuring that the translated HTTP/1.1 messages can be forwarded through the proxy seamlessly.

3. User Proxy (HTTP/1.1 Support)

The user’s proxy only supports HTTP/1.1. Once the messages are converted by the Envoy sidecar, they are sent via HTTP/1.1 to the proxy. The proxy acts as an intermediary between the Envoy sidecar and the Traceable platform.

4. Traceable Platform (SaaS)

After passing through the proxy, the converted HTTP/1.1 messages reach the Traceable Platform.

This topic outlines the steps and configurations to set up the Platform agent to communicate with the Traceable Platform via HTTP/1.1 using the Envoy proxy.

Before you begin

Make a note of the following points:

• Linux Environment: This setup is only supported on Linux. The features required for the Envoy proxy conversion are dependent on Linux capabilities.

• Platform Details: You need the Platform's endpoint and port (default is 443).

• Proxy Configuration: You must have the details of your proxy, including IP address, port, and Base64-encoded credentials for authentication.

• Configuration Tools: Helm, Terraform, or install.sh can be used to configure this setup.

Configuration

Complete the following steps to deploy the Envoy proxy:

Step 1 — Modify values.yam file (Helm)

The following is an example of the values.yaml file for configuring the Platform agent to communicate with the Platform through an Envoy sidecar, converting gRPC to HTTP/1.1:

endpoint: 127.0.0.1 # This is where TPA will send messages, in this case to Envoy sidecar
endpointPort: 9090  # Port where Envoy listens
secure: false       # Envoy does not have certs by default, but will upgrade requests to HTTPS

grpcToHttp:
  enabled: true               # Enable the Envoy sidecar for gRPC to HTTP conversion
  port: 9090                  # Port where Envoy listens for gRPC requests
  image: envoyproxy/envoy:v1.30.2  # Envoy image version
  platformHost: api.traceable.ai  # Traceable platform HTTP endpoint
  platformPort: 443                # Port of the platform (likely 443 unless on-prem)
  proxyHost: 3.90.35.167           # IP address of the user’s proxy
  proxyPort: 8080                  # Proxy port
  proxyCredentialsEncoded: b64encoded_user:password # Base64-encoded credentials

Following is an explanation of the above YAML:

Step 2 — Installing the Envoy sidecar (VM)

If you deploy the Platform agent on a virtual machine, the Envoy sidecar can be installed alongside TPA using the install.sh script. Here is an example command:

sudo ./install.sh tpa-only -e myEnvironment -s myService -t \
--with-grpc-to-http-proxy \
--platform-host api2.traceable.ai \
--platform-port 443 \
--port 80 \
--proxy-host 3.90.35.167 \
--proxy-port 8080 \
--proxy-credentials-encoded

Following is an explanation of the command:

• The -e and -s flags specify the environment and service for TPA.

• The --with-grpc-to-http-proxy flag enables the Envoy sidecar.

• The --platform-host and --platform-port flags provide the Traceable platform host and port.

• The --proxy-host and --proxy-port flags provide the user’s proxy details.

• The --proxy-credentials-encoded flag prompts you to enter the Base64-encoded credentials when you run the install.sh script. The password is not entered on the command line.

Optional: Configuring with Terraform

If you manage your infrastructure using Terraform, you can configure the Envoy sidecar using the Terraform script. This configuration mirrors the Helm configuration but allows for automation and management through infrastructure as code.

Note

This step is optional for users utilizing Terraform for infrastructure management. If you are using Helm or the install.sh script, you can skip this step.

endpoint       = "127.0.0.1"
endpoint_port  = 9090
secure         = false
token          = ""
grpc_to_http = {
  image                     = "envoyproxy/envoy:v1.30.2"
  platform_host             = "api2.traceable.ai"
  platform_port             = 443
  enabled                   = true
  port                      = 9090
  proxy_host                = "3.90.35.167"
  proxy_port                = 8080
  proxy_credentials_encoded = "b64encoded_user:password"
}

After configuring the Terraform template, apply the changes with terraform apply command.