Upstreams can be compared to a cluster in Envoy terminology. Each Upstream must define a type. Supported types include static and kubernetes. Each type is handled by a different plugin in Gloo Gateway. For more information, see Types.

Upstreams allow you to add additional configuration to instruct Gloo Gateway how to handle the request to the backing destination. For example, you can define that the destination requires the requests to be sent with the HTTP/2 protocol or that you want requests to be load balanced by using a specific load balancing algorithm. To route to an Upstream resource, you reference the Upstream in the backendRefs section of your HTTPRoute, just like you do when routing to a Kubernetes service directly. For more information, see Routing.

You can manually create Upstreams or enable Upstream discovery in Gloo Gateway to automatically create Upstreams for any Kubernetes service that is created and discovered in the cluster.

For more information, see the Upstream proto definition.


You can create Upstreams of type static or kubernetes.


Gloo Gateway comes with a built-in service discovery feature that can scan the Kubernetes services in your cluster and automatically create Gloo Gateway Upstream resources for them. To have more control over the services you want to create Upstreams for, you can disable service discovery and instead create Upstreams manually.

Check out the following guides for examples of discovered vs. manual Upstream resources:

To enable service discovery:

  1. Get the current values for your Helm chart.

      helm get values gloo-gateway -n gloo-system -o yaml > gloo-gateway.yaml
    open gloo-gateway.yaml
  2. In your Helm values file, enable service discovery.

        enabled: true
  3. Upgrade your Gloo Gateway installation to enable service discovery.

      helm upgrade -n gloo-system gloo-gateway glooe/gloo-ee \
    --values gloo-gateway.yaml \
    --version 1.17.0-rc5 
  4. Review the Upstream resources that are automatically created for the Kubernetes services that you have in your cluster.

      kubectl get upstreams -n gloo-system


You can route to an Upstream by simply referencing that Upstream in the backendRefs section of your HTTPRoute resource as shown in the following example. Note that if your Upstream and HTTPRoute resources exist in different namespaces, you must create a Kubernetes ReferenceGrant resource to allow the HTTPRoute to access the Upstream.

kind: HTTPRoute
  name: static-upstream
  namespace: default
  - name: http
    namespace: gloo-system
    - static.example
    - backendRefs:
      - name: json-upstream
        kind: Upstream
      - type: ExtensionRef
          kind: RouteOption
          name: rewrite

For an example, see the Static Upstream guide.