About Upstreams

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.

Types link

You can create Upstreams of type static or kubernetes.

Discovery link

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:

• Discovered Upstreams:
  • HTTP/2
• Manual Upstreams:
  • Static
  • Kubernetes service

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.

     
   gloo:
     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-beta2 
     

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
     

Routing link

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.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: static-upstream
  namespace: default
spec:
  parentRefs:
  - name: http
    namespace: gloo-system
  hostnames:
    - static.example
  rules:
    - backendRefs:
      - name: json-upstream
        kind: Upstream
        group: gloo.solo.io
      filters:
      - type: ExtensionRef
        extensionRef:
          group: gateway.solo.io
          kind: RouteOption
          name: rewrite

For an example, see the Static Upstream guide.