Envoy/Istio Helm Installation

Complete guide to installing the ASCEND Envoy external authorization service in your Kubernetes cluster with Istio.

Prerequisites

Kubernetes 1.21+
Helm 3.0+
Istio 1.17+ installed and running
ASCEND API key from the Console
kubectl configured to access your cluster

Verify Prerequisites

# Check Kubernetes version
kubectl version --short

# Check Helm version
helm version --short

# Check Istio installation
istioctl version
kubectl get pods -n istio-system

Quick Installation

Step 1: Create API Key Secret

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

Step 2: Install the Helm Chart

From ECR Public:

helm install ascend-authz oci://public.ecr.aws/w2q8a6d2/ascend-envoy-authz \
  --namespace istio-system \
  --set ascend.apiUrl=https://pilot.owkai.app \
  --set ascend.environment=production

Step 3: Verify Installation

# Check pods are running
kubectl get pods -n istio-system -l app.kubernetes.io/name=ascend-authz

# Check EnvoyFilter is created
kubectl get envoyfilter -n istio-system

# Check ServiceEntry is created
kubectl get serviceentry -n istio-system

Detailed Installation

Step 1: Add Helm Repository (Optional)

If using a local chart:

git clone https://github.com/owkai/ascend-envoy-authz.git
cd ascend-envoy-authz/helm

Step 2: Create Namespace (if needed)

kubectl create namespace istio-system 2>/dev/null || true

Step 3: Create API Key Secret

Using kubectl:

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

Or using a YAML manifest:

apiVersion: v1
kind: Secret
metadata:
  name: ascend-api-key
  namespace: istio-system
type: Opaque
stringData:
  api_key: owkai_prod_xxxxxxxxxxxx

kubectl apply -f ascend-api-key-secret.yaml

Step 4: Create Values File

Create values-production.yaml:

# ASCEND 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 - FAIL SECURE
behavior:
  failOpen: false
  blockOnPending: true
  environment: "production"
  dataSensitivity: "standard"

# Performance
performance:
  timeout: "5s"
  retryCount: 2
  retryDelay: "100ms"
  cacheTTL: "60s"

# Circuit Breaker
circuitBreaker:
  enabled: true
  threshold: 5
  resetTimeout: "30s"

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

# Path Exclusions
excludedPaths:
  - "/health"
  - "/ready"
  - "/metrics"
  - "/healthz"
  - "/readyz"
  - "/.well-known/*"

# High Availability
replicaCount: 3

# Resources
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

# Autoscaling
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

# Pod Disruption Budget
podDisruptionBudget:
  enabled: true
  minAvailable: 2

# Topology Spread
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app.kubernetes.io/name: ascend-authz

# Istio Integration
istio:
  extensionProvider:
    enabled: true
    name: "ascend-ext-authz"
    timeout: "5s"
    failOpen: false

# Prometheus Monitoring
serviceMonitor:
  enabled: true
  interval: 30s

Step 5: Install Chart

helm install ascend-authz ./ascend-authz \
  --namespace istio-system \
  --values values-production.yaml

Or from ECR Public:

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

Step 6: Verify Installation

# Check deployment status
kubectl get deployment ascend-authz -n istio-system

# Check pods are ready
kubectl get pods -n istio-system -l app.kubernetes.io/name=ascend-authz

# Check service
kubectl get svc ascend-authz -n istio-system

# Check EnvoyFilter
kubectl get envoyfilter -n istio-system

# Check ServiceEntry (allows outbound to ASCEND)
kubectl get serviceentry -n istio-system

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

Apply Governance to Workloads

Option 1: Label-Based Selection

Label workloads that should be governed:

kubectl label deployment my-ai-service ascend.io/governed=true -n default

Configure Helm values to select labeled workloads:

envoyFilter:
  workloadSelector:
    labels:
      ascend.io/governed: "true"

Option 2: Namespace-Wide Governance

Apply governance to entire namespaces:

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

Option 3: Custom EnvoyFilter

Create a custom EnvoyFilter for specific workloads:

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: ascend-authz-custom
  namespace: my-namespace
spec:
  workloadSelector:
    labels:
      app: my-ai-service
  configPatches:
    - applyTo: HTTP_FILTER
      match:
        context: SIDECAR_INBOUND
        listener:
          filterChain:
            filter:
              name: envoy.filters.network.http_connection_manager
              subFilter:
                name: envoy.filters.http.router
      patch:
        operation: INSERT_BEFORE
        value:
          name: envoy.filters.http.ext_authz
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
            grpc_service:
              envoy_grpc:
                cluster_name: ascend-authz-cluster
              timeout: 5s
            failure_mode_allow: false
            include_peer_certificate: false

Testing the Installation

Test with curl

# Get service ClusterIP
SERVICE_IP=$(kubectl get svc my-service -n default -o jsonpath='{.spec.clusterIP}')

# Test without agent header (should fail)
kubectl run test --rm -it --image=curlimages/curl -- \
  curl -v http://$SERVICE_IP/api/data

# Test with agent header (should succeed if policy allows)
kubectl run test --rm -it --image=curlimages/curl -- \
  curl -v http://$SERVICE_IP/api/data \
  -H "X-Ascend-Agent-Id: test-agent" \
  -H "X-Ascend-Environment: production"

Check Metrics

# Port-forward to metrics endpoint
kubectl port-forward svc/ascend-authz 8080:8080 -n istio-system &

# Check metrics
curl http://localhost:8080/metrics | grep ascend

Check Logs

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

# Search for decisions
kubectl logs -l app.kubernetes.io/name=ascend-authz -n istio-system | grep decision

Configuration Reference

Complete Values

# Replicas
replicaCount: 3

# Image
image:
  repository: owkai/ascend-envoy-authz
  tag: "1.0.0"
  pullPolicy: IfNotPresent

# ASCEND Platform
ascend:
  apiUrl: "https://pilot.owkai.app"
  apiKey: ""  # Not recommended - use secret
  existingSecret: "ascend-api-key"
  existingSecretKey: "api_key"

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

# Behavior
behavior:
  failOpen: false
  blockOnPending: true
  environment: "production"
  dataSensitivity: "standard"

# Performance
performance:
  timeout: "5s"
  retryCount: 2
  retryDelay: "100ms"
  cacheTTL: "60s"

# Circuit Breaker
circuitBreaker:
  enabled: true
  threshold: 5
  resetTimeout: "30s"

# Logging
logging:
  level: "info"  # debug, info, warn, error
  format: "json"
  logDecisions: true

# Excluded Paths
excludedPaths:
  - "/health"
  - "/ready"
  - "/metrics"

# Service
service:
  type: ClusterIP
  port: 50051
  metricsPort: 8080

# Resources
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

# Autoscaling
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

# Security Context
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  runAsGroup: 1000
  fsGroup: 1000

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

# Service Account
serviceAccount:
  create: true
  name: ""
  annotations: {}

# Pod Disruption Budget
podDisruptionBudget:
  enabled: true
  minAvailable: 2

# Node Selector
nodeSelector: {}

# Tolerations
tolerations: []

# Affinity
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: ascend-authz
          topologyKey: kubernetes.io/hostname

# Topology Spread
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway

# Istio
istio:
  extensionProvider:
    enabled: true
    name: "ascend-ext-authz"
    timeout: "5s"
    failOpen: false

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

# Prometheus
serviceMonitor:
  enabled: false
  interval: 30s
  scrapeTimeout: 10s
  labels: {}

Upgrading

Upgrade Chart

# Update values
vim values-production.yaml

# Upgrade
helm upgrade ascend-authz oci://public.ecr.aws/w2q8a6d2/ascend-envoy-authz \
  --namespace istio-system \
  --values values-production.yaml

Rollback

# List releases
helm history ascend-authz -n istio-system

# Rollback to previous
helm rollback ascend-authz 1 -n istio-system

Uninstallation

# Uninstall chart
helm uninstall ascend-authz -n istio-system

# Remove secret
kubectl delete secret ascend-api-key -n istio-system

# Verify cleanup
kubectl get all -n istio-system -l app.kubernetes.io/name=ascend-authz
kubectl get envoyfilter -n istio-system
kubectl get serviceentry -n istio-system

Troubleshooting

Pod Not Starting

# Check pod status
kubectl describe pod -l app.kubernetes.io/name=ascend-authz -n istio-system

# Check events
kubectl get events -n istio-system --sort-by='.lastTimestamp'

403 on All Requests

Check API key is correct:

kubectl get secret ascend-api-key -n istio-system -o jsonpath='{.data.api_key}' | base64 -d

Check ServiceEntry allows ASCEND API access:

kubectl get serviceentry -n istio-system -o yaml

Check ext_authz service logs:

kubectl logs -l app.kubernetes.io/name=ascend-authz -n istio-system | grep -i error

High Latency

Check ext_authz service metrics:

kubectl port-forward svc/ascend-authz 8080:8080 -n istio-system &
curl http://localhost:8080/metrics | grep latency

Verify HPA is scaling:

kubectl get hpa ascend-authz -n istio-system

Check network connectivity to ASCEND:

kubectl exec -it deploy/ascend-authz -n istio-system -- \
  wget -O- https://pilot.owkai.app/health

Next Steps

Overview - Architecture and concepts
Lambda Authorizer - AWS API Gateway
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

Prerequisites​

Verify Prerequisites​

Quick Installation​

Step 1: Create API Key Secret​

Step 2: Install the Helm Chart​

Step 3: Verify Installation​

Detailed Installation​

Step 1: Add Helm Repository (Optional)​

Step 2: Create Namespace (if needed)​

Step 3: Create API Key Secret​

Step 4: Create Values File​

Step 5: Install Chart​

Step 6: Verify Installation​

Apply Governance to Workloads​

Option 1: Label-Based Selection​

Option 2: Namespace-Wide Governance​

Option 3: Custom EnvoyFilter​

Testing the Installation​

Test with curl​

Check Metrics​

Check Logs​

Configuration Reference​

Complete Values​

Upgrading​

Upgrade Chart​

Rollback​

Uninstallation​

Troubleshooting​

Pod Not Starting​

403 on All Requests​

High Latency​

Next Steps​

Support​