Envoy/Istio Integration Overview

Integrate ASCEND governance into your Kubernetes service mesh using Envoy's external authorization filter.

What is the ASCEND Envoy Integration?

The ASCEND Envoy integration provides real-time AI governance for service mesh traffic. Every request passing through Envoy sidecars is evaluated against your organization's policies before being allowed or denied.

Architecture

                                         ASCEND Platform
                                               |
                                       (authorization)
                                               |
┌──────────┐    ┌─────────────────────────────────────────────────┐
│ AI Agent │───>│ Istio Service Mesh                              │
│          │    │  ┌─────────┐    ┌─────────┐    ┌─────────────┐ │
└──────────┘    │  │ Ingress │───>│ Envoy   │───>│ Your        │ │
                │  │ Gateway │    │ Sidecar │    │ Service     │ │
                │  └─────────┘    │(ext_authz)   └─────────────┘ │
                │                 └─────────┘                     │
                └─────────────────────────────────────────────────┘
                                         │
                                  ASCEND ext_authz
                                  gRPC Service

How It Works

1. AI agent makes request to service via Istio ingress
2. Envoy sidecar intercepts request and invokes ext_authz filter
3. ASCEND ext_authz service extracts agent info and calls ASCEND Platform
4. ASCEND Platform evaluates against policies and returns decision
5. Envoy allows or denies request based on decision
6. Service receives request (if allowed) with ASCEND context headers

Key Features

Zero-Code Integration

Deploy as a Helm chart - no modifications to existing services required.

helm install ascend-authz oci://public.ecr.aws/w2q8a6d2/ascend-envoy-authz \
  --namespace istio-system

Fail-Secure Design

By default, all requests are denied when ASCEND is unreachable.

# Helm values
behavior:
  failOpen: false  # FAIL SECURE (recommended)

Path-Based Exclusions

Bypass governance for health checks and metrics:

excludedPaths:
  - "/health"
  - "/ready"
  - "/metrics"
  - "/healthz"
  - "/readyz"

Circuit Breaker

Built-in circuit breaker prevents cascading failures:

circuitBreaker:
  enabled: true
  threshold: 5
  resetTimeout: "30s"

Request Headers

AI agents must include these headers:

Header	Required	Description
X-Ascend-Agent-Id	Yes	Unique agent identifier
X-Ascend-Environment	No	Environment (production/staging/dev)
X-Ascend-Data-Sensitivity	No	Data sensitivity level
X-Ascend-Target-System	No	Target resource identifier

Example Request

curl -X POST http://my-service.default.svc.cluster.local/api/data \
  -H "X-Ascend-Agent-Id: my-ai-agent" \
  -H "X-Ascend-Environment: production" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM customers"}'

Response Headers

ASCEND adds context headers to allowed requests:

Header	Description
X-Ascend-Action-Id	Unique action identifier
X-Ascend-Risk-Score	Risk score (0-100)
X-Ascend-Risk-Level	Risk level (low/medium/high/critical)
X-Ascend-Decision	Decision (approved/denied)

Your services can use these headers for additional processing.

Authorization Flow

┌──────────┐     ┌─────────────┐     ┌────────────────┐     ┌───────────┐
│  Client  │────>│ Envoy Proxy │────>│ ASCEND ext_authz│────>│  ASCEND   │
│          │     │ (sidecar)   │     │  gRPC Service   │     │ Platform  │
└──────────┘     └─────────────┘     └────────────────┘     └───────────┘
                       │                     │                     │
                       │    CheckRequest     │                     │
                       │ ─────────────────> │                     │
                       │                     │    EvaluateAction   │
                       │                     │ ─────────────────> │
                       │                     │                     │
                       │                     │   Decision (allow)  │
                       │                     │ <───────────────── │
                       │   CheckResponse     │                     │
                       │ <───────────────── │                     │
                       │                     │                     │
                       │  (request allowed)  │                     │
                       └───────────────────>│                     │
                              Backend        │                     │

Helm Chart Values

Key configuration options:

# ASCEND Platform Configuration
ascend:
  apiUrl: "https://pilot.owkai.app"
  existingSecret: "ascend-api-key"
  existingSecretKey: "api_key"

# Agent ID Configuration
agentId:
  header: "x-ascend-agent-id"
  required: true

# Behavior Configuration
behavior:
  failOpen: false          # FAIL SECURE
  blockOnPending: true     # Block pending approvals
  environment: "production"

# Performance Configuration
performance:
  timeout: "5s"
  retryCount: 2
  cacheTTL: "60s"

# Path Exclusions
excludedPaths:
  - "/health"
  - "/ready"
  - "/metrics"

# High Availability
replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

Istio AuthorizationPolicy

The Helm chart can create Istio AuthorizationPolicy resources:

istio:
  authorizationPolicy:
    enabled: true
    namespaces:
      - default
      - production
    selector:
      ascend.io/governed: "true"
    paths: ["/*"]
    notPaths: ["/health", "/ready"]

This selects pods with the ascend.io/governed: "true" label for governance.

Workload Selection

Label-Based Selection

Apply governance to specific workloads:

# Helm values
envoyFilter:
  workloadSelector:
    labels:
      app: my-ai-service
      ascend.io/governed: "true"

Namespace-Based Selection

Apply to entire namespaces:

istio:
  authorizationPolicy:
    enabled: true
    namespaces:
      - ai-agents
      - ml-services

Performance

The ext_authz service is optimized for low latency:

Metric	Target	Typical
gRPC latency	< 10ms	~5ms
ASCEND call	< 50ms	~30ms
Total overhead	< 100ms	~50ms
Cache hit	< 5ms	~2ms

Optimization Tips

1. Use response caching - Reduce ASCEND API calls
2. Deploy in same cluster - Minimize network latency
3. Use pod anti-affinity - Distribute for resilience
4. Enable HPA - Scale with traffic

Observability

Prometheus Metrics

The service exports Prometheus metrics:

serviceMonitor:
  enabled: true
  interval: 30s

Available metrics:

• ascend_authz_requests_total
• ascend_authz_latency_seconds
• ascend_authz_decisions_total
• ascend_authz_errors_total
• ascend_authz_cache_hits_total

Logging

Structured JSON logging:

logging:
  level: "info"
  format: "json"
  logDecisions: true

Tracing

Distributed tracing with Jaeger:

tracing:
  enabled: true
  jaegerEndpoint: "http://jaeger-collector:14268/api/traces"

Security

API Key Storage

Store API keys in Kubernetes secrets:

kubectl create secret generic ascend-api-key \
  --from-literal=api_key=owkai_prod_xxxx \
  --namespace istio-system

Network Policies

Restrict ext_authz service traffic:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: ascend-authz-egress
  namespace: istio-system
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: ascend-authz
  policyTypes:
    - Egress
  egress:
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
      ports:
        - port: 443
          protocol: TCP

Pod Security

The Helm chart enforces security best practices:

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

securityContext:
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

Compliance

Standard	Control	Implementation
SOC 2	CC6.1	All requests logged and audited
HIPAA	164.312(d)	Access control enforcement
PCI-DSS	7.1	Least privilege authorization
NIST	AC-3	Access enforcement at network layer

Troubleshooting

Check EnvoyFilter

kubectl get envoyfilter -n istio-system
kubectl describe envoyfilter ascend-ext-authz -n istio-system

View ext_authz Logs

kubectl logs -l app.kubernetes.io/name=ascend-authz -n istio-system -f

Debug Envoy Configuration

# Check if ext_authz is configured
istioctl proxy-config listener POD_NAME -n NAMESPACE -o json | \
  grep -A 50 ext_authz

# Check Envoy stats
kubectl exec POD_NAME -c istio-proxy -- \
  curl localhost:15000/stats | grep ext_authz

Common Issues

403 on all requests:

1. Check API key secret exists and is correct
2. Verify ServiceEntry allows ASCEND API access
3. Check ext_authz service logs

High latency:

1. Enable response caching
2. Check network connectivity
3. Verify HPA is scaling correctly

ext_authz not invoked:

1. Check EnvoyFilter is in correct namespace
2. Verify workloadSelector matches pods
3. Restart pods to pick up configuration

Next Steps

• Helm Installation Guide - Detailed installation steps
• Lambda Authorizer - AWS API Gateway integration
• Python SDK - Client-side integration

Support

• Documentation: https://docs.owkai.app
• Support: support@owkai.app
• GitHub Issues: https://github.com/owkai/ascend-envoy-authz/issues