Tool Gateway agentgateway Operator

The Tool Gateway agentgateway Operator is a Kubernetes operator that manages ToolGateway instances based on agentgateway. It provides centralized gateway management for tool workloads within the Agentic Layer ecosystem.

Table of Contents

• Prerequisites
• Getting Started
• Development
• Configuration
• End-to-End (E2E) Testing
• Testing Tools and Configuration
• Sample Data
• Contribution

---

Prerequisites

Before working with this project, ensure you have the following tools installed on your system:

• Go: version 1.26.0 or higher
• Docker: version 20.10+ (or a compatible alternative like Podman)
• kubectl: The Kubernetes command-line tool
• kind: For running Kubernetes locally in Docker
• helm: Helm 3+ for installing agentgateway
• make: The build automation tool

---

Getting Started

Quick Start:

# Create local cluster
kind create cluster

# Install required dependencies (cert-manager, Gateway API CRDs, agentgateway, agent-runtime)
make install-deps

# Install the Tool Gateway operator
kubectl apply -f https://github.com/agentic-layer/tool-gateway-agentgateway/releases/latest/download/install.yaml

To remove all dependencies from the cluster again:

kubectl delete -f https://github.com/agentic-layer/tool-gateway-agentgateway/releases/latest/download/install.yaml
make uninstall-deps

How it Works

The Tool Gateway agentgateway Operator creates and manages Gateway API resources based on ToolGateway and ToolServer custom resources:

1. Gateway Creation: When a ToolGateway is created, the operator creates a dedicated Gateway with the same name in the same namespace as the ToolGateway with HTTP listener on port 80. Each ToolGateway has its own Gateway instance.

2. ToolServer Integration: For each ToolServer resource, the operator creates:

   • AgentgatewayBackend: Configures the MCP backend connection to the ToolServer
   • HTTPRoute: Routes traffic from the gateway to the AgentgatewayBackend using path-based matching

3. Automatic Updates: The operator watches for changes to ToolGateway and ToolServer resources and updates the corresponding Gateway API resources automatically.

Architecture

ToolGateway (CRD)
    |
Gateway (same name and namespace)
    |
HTTPRoute (Gateway API) -> AgentgatewayBackend -> ToolServer

Development

Follow the prerequisites above to set up your local environment. Then follow these steps to build and deploy the operator locally:

# Install CRDs into the cluster
make install
# Build docker image
make docker-build
# Load image into kind cluster (not needed if using local registry)
make kind-load
# Deploy the operator to the cluster
make deploy

After a successful start, you should see the controller manager pod running in the tool-gateway-agentgateway-system namespace.

kubectl get pods -n tool-gateway-agentgateway-system

Configuration

Prerequisites for ToolGateway

Before creating a ToolGateway, ensure you have:

1. Gateway API CRDs installed in your cluster
2. agentgateway support installed (see Getting Started)

ToolGateway Configuration

To create a agentgateway-based gateway for your tools, define a ToolGateway resource:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolGateway
metadata:
  name: my-tool-gateway
  namespace: my-namespace
spec:
  toolGatewayClassName: agentgateway  # Optional: uses default if not specified

This will create a my-tool-gateway Gateway in the my-namespace namespace.

OpenTelemetry (OTEL) Configuration

The operator automatically translates standard OpenTelemetry environment variables to agentgateway's telemetry configuration. This provides seamless observability integration without requiring manual configuration of agentgateway's config file.

Supported OTEL Environment Variables:

• OTEL_EXPORTER_OTLP_ENDPOINT - The OTLP exporter endpoint URL
• OTEL_EXPORTER_OTLP_PROTOCOL - The protocol to use (grpc or http)
• OTEL_EXPORTER_OTLP_HEADERS - Headers to send with telemetry data
• Signal-specific overrides:
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  • OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
  • OTEL_EXPORTER_OTLP_TRACES_HEADERS
  • (Similar for METRICS and LOGS)

Example:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolGateway
metadata:
  name: my-tool-gateway
  namespace: my-namespace
spec:
  toolGatewayClassName: agentgateway
  env:
    # OTEL configuration - automatically translated to agentgateway config
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: "http://otel-collector:4318"
    - name: OTEL_EXPORTER_OTLP_PROTOCOL
      value: "http/protobuf"
    - name: OTEL_EXPORTER_OTLP_HEADERS
      value: "api-key=secret123"
    
    # Other environment variables are passed through as-is
    - name: LOG_LEVEL
      value: "info"

The OTEL environment variables are translated to agentgateway's rawConfig.telemetry section and are not passed as environment variables to the agentgateway container. Other environment variables (like LOG_LEVEL above) are passed through unchanged.

See config/samples/toolgateway_v1alpha1_otel_example.yaml for complete examples.

ToolServer Configuration

Define ToolServer resources that the gateway will route to:

apiVersion: runtime.agentic-layer.ai/v1alpha1
kind: ToolServer
metadata:
  name: my-tool-server
  namespace: my-namespace
spec:
  protocol: mcp
  transportType: http
  image: my-tool-server:latest
  port: 8000
  path: /mcp
  replicas: 1

The operator will automatically create:

• An AgentgatewayBackend for the ToolServer
• An HTTPRoute connecting the Gateway to the backend

Accessing Your Tools

Once deployed, tools are accessible via the ToolGateway's Gateway:

# Get the Gateway service endpoint (example for 'my-tool-gateway')
kubectl get svc -n my-namespace | grep my-tool-gateway

# Access your tool via the gateway
curl http://<gateway-endpoint>/mcp

End-to-End (E2E) Testing

Prerequisites for E2E Tests

• kind must be installed and available in PATH
• Docker running and accessible
• kubectl configured and working

Running E2E Tests

The E2E tests automatically create an isolated Kind cluster, deploy the operator, run comprehensive tests, and clean up afterwards.

# Run complete E2E test suite
make test-e2e

Manual E2E Test Setup

If you need to run E2E tests manually or inspect the test environment:

# Set up test cluster
make setup-test-e2e

# Install required dependencies
make install-deps

# Run E2E tests against the existing cluster
KIND_CLUSTER=tool-gateway-agentgateway-test-e2e go test ./test/e2e/ -v -ginkgo.v

# Clean up test cluster when done
make cleanup-test-e2e

Testing Tools and Configuration

The project includes comprehensive test coverage:

• Unit Tests: Test suite for the controller
• E2E Tests: End-to-end tests in Kind cluster
• Ginkgo/Gomega: BDD-style testing framework
• EnvTest: Kubernetes API server testing environment

Run tests with:

# Run unit and integration tests
make test

# Run E2E tests in kind cluster
make test-e2e

Sample Data

The project includes sample manifests to help you get started.

• Where to find sample data? Sample manifests are located in the config/samples/ directory.

• How to deploy sample resources? You can deploy sample ToolGateway resources with:

  kubectl apply -k config/samples/

Contribution

See Contribution Guide for details on contribution, and the process for submitting pull requests.