About Upstreams
Use Upstream resources to define a backing destination for a route that you want Gloo Gateway to route to.
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
You can create Upstreams of type static
, kube
, aws
, and gcp
.
Upstreams of type azure
, consul
, grpc
, rest
, or awsEc2
are not supported in Gloo Gateway when using the Kubernetes Gateway API. You can use these types of Upstreams when using a gateway proxy that is configured for the Gloo Edge API. For more information, see Destination types in the Gloo Gateway (Gloo Edge API) documentation.
Check out the following guides for examples on how to use Upstreams with Gloo Gateway:
Discovery
Gloo Gateway comes with a built-in service discovery feature that can scan the Kubernetes services and Functions in your cluster and automatically create Gloo Gateway Upstream resources for them to facilitate routing and self-service. To have more control over the services you want to create Upstreams for, you can disable service discovery and instead create Upstreams manually.
The following resources can be discovered automatically:
- Kubernetes Services
- AWS Lambda Functions
- Google Cloud Functions
- OpenAPI-based Functions
To enable service discovery:
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
In your Helm values file, enable service discovery.
gloo: discovery: enabled: true
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.18.0-beta1
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
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.
spec.backendRefs.port
field when referencing your Upstream. The port is defined in your Upstream resource and ignored if set on the HTTPRoute resource.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.