agentgateway quickstart: your first POC

kubectl create namespace keycloak

# realm imported from a ConfigMap (Keycloak reads /opt/keycloak/data/import on first boot)
kubectl -n keycloak create configmap keycloak-realm-import \
  --from-file=realm.json=yaml/keycloak/realm.json --dry-run=client -o yaml | kubectl apply -f -

kubectl -n keycloak apply -f yaml/keycloak/keycloak.yaml
kubectl -n keycloak rollout status statefulset/keycloak --timeout=300s

kubectl -n keycloak port-forward svc/keycloak 8081:80 &
for _ in $(seq 1 30); do curl -sf -o /dev/null localhost:8081/realms/solo 2>/dev/null && break; sleep 1; done  # wait for the tunnel

curl -s localhost:8081/realms/solo/.well-known/openid-configuration | jq .issuer
# -> "http://keycloak.keycloak.svc.cluster.local/realms/solo"

curl -s -X POST localhost:8081/realms/solo/protocol/openid-connect/token \
  -d grant_type=password -d client_id=kagent -d username=alice -d password=alice | jq -r .access_token
# -> a JWT. Enforce it on the gateway with the same policy shown in the BYO tab.

# A backend for the IdP host (external HTTPS provider), so the gateway can fetch JWKS.
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayBackend
metadata: { name: idp, namespace: agentgateway-system }
spec:
  static:
    host: your-tenant.okta.com     # your IdP host
    port: 443
---
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: jwt-auth, namespace: agentgateway-system }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agw                      # the Gateway from step 3
  traffic:
    jwtAuthentication:
      mode: Strict                   # Strict = require a valid token; Permissive = allow anonymous
      providers:
        - issuer: "https://your-tenant.okta.com/oauth2/default"
          audiences: ["<your-client-id>"]
          jwks:
            remote:
              jwksPath: "/oauth2/default/v1/keys"   # the jwks_uri path from discovery
              cacheDuration: "5m"
              backendRef:
                group: enterpriseagentgateway.solo.io
                kind: EnterpriseAgentgatewayBackend
                name: idp
                port: 443

apiVersion: v1
kind: Namespace
metadata: { name: demo }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: httpbin, namespace: demo, labels: { app: httpbin } }
spec:
  replicas: 1
  selector: { matchLabels: { app: httpbin } }
  template:
    metadata: { labels: { app: httpbin } }
    spec:
      containers:
        - name: httpbin
          image: mccutchen/go-httpbin:v2.15.0
          ports: [{ containerPort: 8080 }]
---
apiVersion: v1
kind: Service
metadata: { name: httpbin, namespace: demo }
spec:
  selector: { app: httpbin }
  ports: [{ port: 8000, targetPort: 8080 }]
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata: { name: agw, namespace: demo }
spec:
  gatewayClassName: enterprise-agentgateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes: { namespaces: { from: Same } }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: httpbin, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - backendRefs: [{ name: httpbin, port: 8000 }]

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Namespace
metadata: { name: demo }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: httpbin, namespace: demo, labels: { app: httpbin } }
spec:
  replicas: 1
  selector: { matchLabels: { app: httpbin } }
  template:
    metadata: { labels: { app: httpbin } }
    spec:
      containers:
        - name: httpbin
          image: mccutchen/go-httpbin:v2.15.0
          ports: [{ containerPort: 8080 }]
---
apiVersion: v1
kind: Service
metadata: { name: httpbin, namespace: demo }
spec:
  selector: { app: httpbin }
  ports: [{ port: 8000, targetPort: 8080 }]
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata: { name: agw, namespace: demo }
spec:
  gatewayClassName: enterprise-agentgateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes: { namespaces: { from: Same } }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: httpbin, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - backendRefs: [{ name: httpbin, port: 8000 }]
EOF

# the Gateway reports Programmed before its proxy pod is Ready, so wait on the proxy too
kubectl -n demo wait gateway/agw --for=condition=Programmed --timeout=120s
kubectl -n demo rollout status deploy/agw --timeout=120s

apiVersion: apps/v1
kind: Deployment
metadata: { name: mcp-everything, namespace: demo, labels: { app: mcp-everything } }
spec:
  replicas: 1
  selector: { matchLabels: { app: mcp-everything } }
  template:
    metadata: { labels: { app: mcp-everything } }
    spec:
      containers:
        - name: everything
          image: node:22-alpine
          command: ["npx"]
          args: ["-y", "@modelcontextprotocol/server-everything", "streamableHttp"]
          ports: [{ containerPort: 3001 }]
---
apiVersion: v1
kind: Service
metadata: { name: mcp-everything, namespace: demo }
spec:
  selector: { app: mcp-everything }
  ports: [{ port: 80, targetPort: 3001 }]
---
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayBackend
metadata: { name: mcp-backend, namespace: demo }
spec:
  mcp:
    targets:
      - name: everything
        static:
          backendRef: { name: mcp-everything }
          port: 80
          protocol: StreamableHTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: mcp, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - matches: [{ path: { type: PathPrefix, value: /mcp } }]
      backendRefs:
        - name: mcp-backend
          group: enterpriseagentgateway.solo.io
          kind: EnterpriseAgentgatewayBackend

kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata: { name: mcp-everything, namespace: demo, labels: { app: mcp-everything } }
spec:
  replicas: 1
  selector: { matchLabels: { app: mcp-everything } }
  template:
    metadata: { labels: { app: mcp-everything } }
    spec:
      containers:
        - name: everything
          image: node:22-alpine
          command: ["npx"]
          args: ["-y", "@modelcontextprotocol/server-everything", "streamableHttp"]
          ports: [{ containerPort: 3001 }]
---
apiVersion: v1
kind: Service
metadata: { name: mcp-everything, namespace: demo }
spec:
  selector: { app: mcp-everything }
  ports: [{ port: 80, targetPort: 3001 }]
---
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayBackend
metadata: { name: mcp-backend, namespace: demo }
spec:
  mcp:
    targets:
      - name: everything
        static:
          backendRef: { name: mcp-everything }
          port: 80
          protocol: StreamableHTTP
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: mcp, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - matches: [{ path: { type: PathPrefix, value: /mcp } }]
      backendRefs:
        - name: mcp-backend
          group: enterpriseagentgateway.solo.io
          kind: EnterpriseAgentgatewayBackend
EOF

# first boot pulls the npm package, so allow a little longer
kubectl -n demo rollout status deploy/mcp-everything --timeout=240s

# 1. Require a valid Keycloak JWT on the /mcp route (no token -> 401)
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: mcp-jwt, namespace: demo }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: mcp
  traffic:
    jwtAuthentication:
      mode: Strict
      providers:
        - issuer: "http://keycloak.keycloak.svc.cluster.local/realms/solo"
          jwks:
            remote:
              jwksPath: "/realms/solo/protocol/openid-connect/certs"
              backendRef: { kind: Service, name: keycloak, namespace: keycloak, port: 80 }
---
# 2. Per-tool authorization on the MCP backend: alice may only call get-sum
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: mcp-authz, namespace: demo }
spec:
  targetRefs:
    - group: enterpriseagentgateway.solo.io
      kind: EnterpriseAgentgatewayBackend
      name: mcp-backend
  backend:
    mcp:
      authorization:
        action: Allow          # a tool matching no rule is hidden + denied
        policy:
          matchExpressions:
            - 'jwt.email == "alice@example.com" && mcp.tool.name == "get-sum"'
            - 'jwt.email != "alice@example.com"'     # everyone else keeps full access

kubectl apply -f - <<'EOF'
# 1. Require a valid Keycloak JWT on the /mcp route (no token -> 401)
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: mcp-jwt, namespace: demo }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: mcp
  traffic:
    jwtAuthentication:
      mode: Strict
      providers:
        - issuer: "http://keycloak.keycloak.svc.cluster.local/realms/solo"
          jwks:
            remote:
              jwksPath: "/realms/solo/protocol/openid-connect/certs"
              backendRef: { kind: Service, name: keycloak, namespace: keycloak, port: 80 }
---
# 2. Per-tool authorization on the MCP backend: alice may only call get-sum
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: mcp-authz, namespace: demo }
spec:
  targetRefs:
    - group: enterpriseagentgateway.solo.io
      kind: EnterpriseAgentgatewayBackend
      name: mcp-backend
  backend:
    mcp:
      authorization:
        action: Allow          # a tool matching no rule is hidden + denied
        policy:
          matchExpressions:
            - 'jwt.email == "alice@example.com" && mcp.tool.name == "get-sum"'
            - 'jwt.email != "alice@example.com"'     # everyone else keeps full access
EOF

kubectl -n demo create secret generic openai-secret \
  --from-literal=Authorization="$OPENAI_API_KEY"

kubectl apply -f - <<'EOF'
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayBackend
metadata: { name: openai, namespace: demo }
spec:
  ai:
    groups:
      - providers:
          - name: openai
            openai:
              model: gpt-4o-mini
            policies:
              auth:
                secretRef: { name: openai-secret }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: openai, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - matches: [{ path: { type: PathPrefix, value: /openai } }]
      backendRefs:
        - name: openai
          group: enterpriseagentgateway.solo.io
          kind: EnterpriseAgentgatewayBackend
EOF

kubectl -n demo port-forward svc/agw 8080:80 &
for _ in $(seq 1 30); do curl -sf -o /dev/null localhost:8080/get 2>/dev/null && break; sleep 1; done  # wait for the tunnel

# OpenAI-format request; model:"" uses the backend's configured model
curl -s localhost:8080/openai -H 'content-type: application/json' \
  -d '{"model":"","messages":[{"role":"user","content":"Write a haiku about AI gateways."}]}' \
  | jq -r '.choices[0].message.content'
# -> a three-line haiku about AI gateways

kubectl -n demo create secret generic anthropic-secret \
  --from-literal=Authorization="$ANTHROPIC_API_KEY"

kubectl apply -f - <<'EOF'
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayBackend
metadata: { name: anthropic, namespace: demo }
spec:
  ai:
    groups:
      - providers:
          - name: anthropic
            anthropic:
              model: claude-haiku-4-5-20251001
            policies:
              auth:
                secretRef: { name: anthropic-secret }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata: { name: anthropic, namespace: demo }
spec:
  parentRefs: [{ name: agw }]
  rules:
    - matches: [{ path: { type: PathPrefix, value: /anthropic } }]
      backendRefs:
        - name: anthropic
          group: enterpriseagentgateway.solo.io
          kind: EnterpriseAgentgatewayBackend
EOF

kubectl -n demo port-forward svc/agw 8080:80 &
for _ in $(seq 1 30); do curl -sf -o /dev/null localhost:8080/get 2>/dev/null && break; sleep 1; done  # wait for the tunnel

# still OpenAI-format in and out; the gateway translates to Anthropic and back
curl -s localhost:8080/anthropic -H 'content-type: application/json' \
  -d '{"model":"","messages":[{"role":"user","content":"Write a haiku about AI gateways."}]}' \
  | jq -r '.choices[0].message.content'
# -> a three-line haiku about AI gateways

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: tracing, namespace: demo }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agw
  frontend:
    tracing:
      backendRef:
        name: solo-enterprise-telemetry-collector
        namespace: agentgateway-system
        port: 4317
      protocol: GRPC
      randomSampling: "true"      # sample every request (fine for a demo)

kubectl apply -f - <<'EOF'
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: tracing, namespace: demo }
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: agw
  frontend:
    tracing:
      backendRef:
        name: solo-enterprise-telemetry-collector
        namespace: agentgateway-system
        port: 4317
      protocol: GRPC
      randomSampling: "true"      # sample every request (fine for a demo)
EOF

budgetDimensions:
  config:
    hierarchy:                 # ordered scopes
      - { id: group, expression: 'coalesce(jwt.group, apiKey.group)', displayName: Group }
      - { id: user,  expression: 'coalesce(apiKey.user, apiKey.name, apiKey.owner, jwt.sub, jwt.email, basicAuth.username, source.identity.namespace + "/" + source.identity.serviceAccount, source.subjectCn)', displayName: User }
      - { id: team,  expression: 'request.headers["x-team"]', displayName: Team }
    attributes:                # flat attributes
      - { id: virtualKey, expression: apiKey.id, displayName: Virtual Key }

helm upgrade enterprise-agentgateway \
  oci://us-docker.pkg.dev/solo-public/enterprise-agentgateway/charts/enterprise-agentgateway \
  --namespace agentgateway-system --version v2026.7.0 --reuse-values -f - <<'EOF'
budgetDimensions:
  config:
    hierarchy:
      - { id: group, expression: 'coalesce(jwt.group, apiKey.group)', displayName: Group }
      - { id: user,  expression: 'coalesce(apiKey.user, apiKey.name, apiKey.owner, jwt.sub, jwt.email, basicAuth.username, source.identity.namespace + "/" + source.identity.serviceAccount, source.subjectCn)', displayName: User }
      - { id: team,  expression: 'request.headers["x-team"]', displayName: Team }
    attributes:
      - { id: virtualKey, expression: apiKey.id, displayName: Virtual Key }
EOF

kubectl -n demo rollout restart deploy/agw
kubectl -n demo rollout status deploy/agw --timeout=90s

apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: prompt-guard, namespace: demo }
spec:
  targetRefs:                    # one policy, every LLM route you made in step 7
    - { group: gateway.networking.k8s.io, kind: HTTPRoute, name: openai }
    - { group: gateway.networking.k8s.io, kind: HTTPRoute, name: anthropic }
  backend:
    ai:
      promptGuard:
        request:
          - regex:
              action: Reject               # Reject or Mask
              builtins: ["Ssn", "CreditCard"]
              # matches: ["(?i)api[_-]?key"]   # add your own regex too
            response:
              statusCode: 403
              message: "Blocked: the request contained sensitive data (PII)."
        response:
          - regex:
              action: Mask                  # mask PII the model returns
              builtins: ["Ssn", "CreditCard", "Email"]

kubectl apply -f - <<'EOF'
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata: { name: prompt-guard, namespace: demo }
spec:
  targetRefs:                    # one policy, every LLM route you made in step 7
    - { group: gateway.networking.k8s.io, kind: HTTPRoute, name: openai }
    - { group: gateway.networking.k8s.io, kind: HTTPRoute, name: anthropic }
  backend:
    ai:
      promptGuard:
        request:
          - regex:
              action: Reject               # Reject or Mask
              builtins: ["Ssn", "CreditCard"]
              # matches: ["(?i)api[_-]?key"]   # add your own regex too
            response:
              statusCode: 403
              message: "Blocked: the request contained sensitive data (PII)."
        response:
          - regex:
              action: Mask                  # mask PII the model returns
              builtins: ["Ssn", "CreditCard", "Email"]
EOF