Gloo Edge: Complete Setup and Configuration Guide

What is Gloo Edge?

Gloo Edge is a next-generation API gateway and ingress controller built on the Envoy proxy. It is designed for cloud-native environments, with a strong focus on Kubernetes but capable of operating in hybrid and multi-cloud setups. Unlike traditional API gateways that rely on a monolithic data plane, Gloo Edge leverages Envoy’s high-performance, extensible architecture to deliver advanced traffic management, security, and observability features.

At its core, Gloo Edge provides a declarative, Kubernetes-native configuration model using Custom Resource Definitions (CRDs) such as VirtualService, Upstream, and Gateway. This allows operators and developers to define routing, transformation, authentication, and rate limiting policies directly as code, without touching fragile configuration files or opaque admin consoles. The control plane translates these CRDs into Envoy’s xDS protocol, pushing dynamic configuration to Envoy proxies that handle all traffic.

Why Gloo Edge Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

In modern microservice architectures, an API gateway is no longer just a simple reverse proxy. It must handle east-west and north-south traffic, enforce security policies, support multiple protocols (HTTP, gRPC, WebSocket), and integrate with service meshes. Gloo Edge excels here because:

Envoy-based data plane: Leverages the most widely adopted L7 proxy, with support for advanced HTTP routing, gRPC, rate limiting, and WebAssembly filters.
Kubernetes-native CRDs: No extra database required. All configuration lives as Kubernetes objects, enabling GitOps workflows and seamless CI/CD integration.
Service mesh integration: Can function as a north-south gateway for Istio, Linkerd, or Consul Connect, or as a standalone API gateway in non-mesh clusters.
Extensible auth and transformation: Pluggable authentication (OAuth2, OpenID Connect, API keys, JWT) and request/response transformation via a simple configuration language.
Multi-cloud consistency: The same Gloo Edge configuration can be deployed across on-prem, AWS, GCP, Azure, ensuring uniform policy enforcement.

Architecture Overview

Gloo Edge consists of two main components:

Gloo Control Plane (gloo) – A Go application that watches Kubernetes CRDs, service discovery data, and user-defined configuration, then generates Envoy xDS snapshots. It also provides the glooctl CLI for debugging and management.
Envoy Data Plane (gateway-proxy) – Envoy instances deployed as a Kubernetes Deployment or DaemonSet, typically fronted by a LoadBalancer service. They handle all client traffic, executing the routing, filtering, and security rules pushed by the control plane.

Additionally, Gloo Edge optionally deploys a UI (Gloo Edge Portal) and integrates with external auth servers, rate limiting servers, and observability backends like Prometheus and Grafana.

Prerequisites and Installation

Before installing Gloo Edge, you need:

A Kubernetes cluster (version 1.21+ recommended).
kubectl configured to talk to your cluster.
helm (v3+) installed locally.
Basic understanding of Kubernetes namespaces and services.

Installing Gloo Edge with Helm

Add the Gloo Edge Helm repository and install the core chart. The following example installs Gloo Edge in the gloo-system namespace with the default settings, which includes the control plane and a gateway-proxy Envoy deployment.

# Add the Gloo Edge Helm repo
helm repo add gloo https://storage.googleapis.com/solo-public-helm

# Update repos
helm repo update

# Create the gloo-system namespace
kubectl create namespace gloo-system

# Install Gloo Edge with default values
helm install gloo gloo/gloo --namespace gloo-system \
  --set gatewayProxies.gatewayProxy.service.type=LoadBalancer

Verify the installation by checking the pods:

kubectl get pods -n gloo-system

# Expected output:
# NAME                                   READY   STATUS    RESTARTS   AGE
# gloo-xxxxxxxxxx-xxxxx                  1/1     Running   0          2m
# gateway-proxy-v2-xxxxxxxxxx-xxxxx      1/1     Running   0          2m
# discovery-xxxxxxxxxx-xxxxx             1/1     Running   0          2m

The discovery pod watches Kubernetes services and creates corresponding Upstream resources automatically. This is a key feature: any Kubernetes service becomes routable without manual upstream creation.

Core Configuration: Virtual Services and Routes

The fundamental building block in Gloo Edge is the VirtualService. It defines a set of routing rules for a specific domain (or set of domains), specifying how requests should be matched and forwarded to upstream backends. Each VirtualService contains one or more routes, each with matchers and a destination.

Defining Your First Virtual Service

Imagine you have a Kubernetes service named productpage in the default namespace, exposed on port 9080. You want to route external traffic arriving at api.example.com to this service. First, ensure the discovery component has picked up the service (check for an Upstream named default-productpage-9080). Then create a VirtualService like this:

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: productpage-vs
  namespace: gloo-system
spec:
  virtualHost:
    domains:
      - 'api.example.com'
    routes:
      - matchers:
          - prefix: /
        routeAction:
          single:
            upstream:
              name: default-productpage-9080
              namespace: gloo-system

Apply it:

kubectl apply -f virtualservice-productpage.yaml

Now any request to http://api.example.com/ (assuming the LoadBalancer IP is pointed to by DNS) will be forwarded to the productpage service. Note that the Upstream resource resides in the gloo-system namespace by default, even though the service is in default. Gloo Edge automatically discovers services across all namespaces and creates upstreams in its own namespace.

Route Matching Options

Gloo Edge supports three primary matcher types:

prefix – Matches if the path starts with the given string.
exact – Matches only if the entire path equals the string.
regex – Matches against a regular expression (uses Envoy’s regex engine).

Example of a route with multiple matchers and a rewrite:

routes:
  - matchers:
      - prefix: /v1/api
    routeAction:
      single:
        upstream:
          name: default-productpage-9080
          namespace: gloo-system
    options:
      prefixRewrite: /api
  - matchers:
      - exact: /health
    routeAction:
      single:
        upstream:
          name: default-healthcheck-8080
          namespace: gloo-system

Upstreams: Connecting to Backends

An Upstream in Gloo Edge represents a destination backend. It contains connection settings, health check configuration, load balancing policies, and SSL parameters. While Kubernetes service discovery automatically creates upstreams, you can also define custom upstreams for non-Kubernetes backends like AWS Lambda, external REST APIs, or gRPC services running outside the cluster.

Static Upstream for External Service

apiVersion: gateway.solo.io/v1
kind: Upstream
metadata:
  name: external-api-upstream
  namespace: gloo-system
spec:
  static:
    hosts:
      - addr: httpbin.org
        port: 443
    healthCheck:
      path: /get
      interval: 10s
      unhealthyThreshold: 3
  sslConfig:
    sniDomains:
      - httpbin.org

This creates an upstream pointing to httpbin.org:443 with TLS SNI set appropriately. You can then route to it from a VirtualService using upstream.name: external-api-upstream.

Service Discovery Integration

Gloo Edge’s discovery component not only watches Kubernetes services but also integrates with Consul and AWS/Google Cloud functions. To enable Consul discovery, provide the Consul address in the Helm values during installation:

helm install gloo gloo/gloo --namespace gloo-system \
  --set discovery.consul.enabled=true \
  --set discovery.consul.serverAddr=consul-server.consul:8500

After enabling, services registered in Consul appear as Upstream resources automatically.

Traffic Management and Load Balancing

Gloo Edge offers sophisticated traffic control, including weighted routing, canary deployments, blue/green releases, and active/ passive health checking.

Weighted Routing (Canary Releases)

To split traffic between two versions of a service, define a route with multiple weightedDestinations:

routes:
  - matchers:
      - prefix: /
    routeAction:
      multi:
        destinations:
          - destination:
              upstream:
                name: default-productpage-v1-9080
                namespace: gloo-system
            weight: 90
          - destination:
              upstream:
                name: default-productpage-v2-9080
                namespace: gloo-system
            weight: 10

This sends 90% of requests to v1 and 10% to v2, enabling gradual migration or A/B testing. Weights must sum to 100.

Active Health Checking

Gloo Edge can actively probe upstream endpoints and eject unhealthy ones. Configure the upstream:

spec:
  healthCheck:
    path: /healthz
    interval: 5s
    unhealthyThreshold: 2
    healthyThreshold: 1

When combined with Envoy's circuit breaking, you get a robust resilience layer.

Security: Authentication and Authorization

Securing APIs is critical. Gloo Edge integrates with external authentication servers (Ext Auth) and supports API key validation, JWT verification, and OAuth2/OpenID Connect flows out of the box.

Ext Auth with OAuth2/OpenID Connect

Gloo Edge can delegate authentication to an external service that implements the Envoy External Authorization protocol. A common choice is an OAuth2 proxy or a custom auth service. To configure, reference the Ext Auth service in the VirtualService:

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: secured-vs
  namespace: gloo-system
spec:
  virtualHost:
    domains:
      - 'secure.example.com'
    routes:
      - matchers:
          - prefix: /
        routeAction:
          single:
            upstream:
              name: default-backend-8080
              namespace: gloo-system
    virtualHostPlugins:
      extauth:
        configRef:
          name: my-oauth2-auth
          namespace: gloo-system

Then define the AuthConfig (or use an AuthConfig CRD) that specifies the OAuth2 provider details:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: my-oauth2-auth
  namespace: gloo-system
spec:
  configs:
    - oauth2:
        clientId: myclientid
        clientSecretRef:
          name: oauth2-secret
          namespace: gloo-system
        callbackPath: /callback
        authEndpoint: https://auth.example.com/authorize
        tokenEndpoint: https://auth.example.com/oauth/token
        appUrl: https://secure.example.com

With this setup, unauthenticated requests are redirected to the OAuth2 provider, and only authenticated users reach the backend.

API Keys and JWT

Gloo Edge can also validate API keys and JWTs directly without an external auth server. You configure an AuthConfig with apiKey or jwt rules. Example for JWT:

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: jwt-auth
  namespace: gloo-system
spec:
  configs:
    - jwt:
        jwksUrl: https://auth.example.com/.well-known/jwks.json
        audiences:
          - my-api

Then reference this in the VirtualService’s virtualHostPlugins.extauth. Requests must include a valid JWT token in the Authorization header; otherwise they receive a 401 response.

Rate Limiting and Circuit Breaking

Gloo Edge supports rate limiting via an external rate limit server (typically the Solo.io rate limit service based on Envoy’s rate limit design). You define rate limit descriptors in the VirtualService route options:

routes:
  - matchers:
      - prefix: /api
    routeAction:
      single:
        upstream:
          name: default-backend-8080
          namespace: gloo-system
    options:
      rateLimit:
        descriptorKey: 
          - key: "header"
            value: "x-api-key"
        rateLimitServerConfig:
          name: rl-config
          namespace: gloo-system

Circuit breaking is configured on the Upstream or via Envoy’s outlier detection. For example, to limit connections and pending requests:

spec:
  circuitBreakers:
    maxConnections: 100
    maxPendingRequests: 50
    maxRequests: 200
    maxRetries: 3

Observability and Logging

Gloo Edge exposes Envoy’s native metrics in Prometheus format. The gateway-proxy pods expose a metrics endpoint on port 8081 by default. You can scrape them with Prometheus and visualize with Grafana using prebuilt dashboards.

To enable access logs with detailed request information, set the accessLog configuration on the gateway proxy via Helm values or by editing the Gateway CRD. Example Helm value:

gatewayProxies:
  gatewayProxy:
    envoyDeployment:
      accessLogging:
        fileSink:
          path: /dev/stdout
          jsonFormat: |
            {"timestamp":"%START_TIME%","method":"%REQ(:METHOD)%","path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","status":%RESPONSE_CODE%}

This emits structured JSON logs to stdout, easily collected by any log aggregation system.

Best Practices

Use GitOps for configuration: Store all VirtualService, Upstream, and AuthConfig definitions in a Git repository and apply them via Flux or ArgoCD. This ensures audit trails and easy rollbacks.
Namespace isolation: Place Gloo Edge control plane components in gloo-system, but keep workload-specific resources (like VirtualServices) in the application namespace. Gloo Edge supports watching multiple namespaces.
Leverage auto-discovery: Avoid manual upstream creation for Kubernetes services unless you need custom settings. The discovery component reduces configuration drift.
Secure the gateway proxy: Always expose the gateway-proxy service via an internal LoadBalancer or Ingress, and use TLS with cert-manager for HTTPS termination.
Test routing with glooctl: Use glooctl check and glooctl proxy served-by-route to verify configurations before applying to production.
Start with minimal auth, then layer: Begin with simple API key validation, then add OAuth2/OIDC as needed. Avoid complex auth flows until they are proven necessary.
Monitor Envoy metrics: Set up alerts on upstream failures, high latency, and 5xx errors. Envoy’s stats are detailed and actionable.
Use canary deployments: For any backend update, use weighted routing to gradually shift traffic, combined with health checks to automatically roll back if errors spike.

Conclusion

Gloo Edge provides a powerful, Envoy-based API gateway that feels native to Kubernetes. Its declarative CRD model, automatic service discovery, and robust security features make it an excellent choice for teams adopting microservices and service mesh architectures. By following the setup and configuration patterns outlined in this guide, you can deploy a production-ready gateway that handles routing, authentication, rate limiting, and observability with minimal operational overhead. As your platform evolves, Gloo Edge’s extensibility and multi-cloud support ensure it will adapt seamlessly, letting you focus on delivering value rather than wrestling with gateway infrastructure.