Upstreams

Use Upstream resources to define a backing destination for a route that you want K8sGateway 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 K8sGateway. For more information, see Types.

Upstreams allow you to add additional configuration to instruct K8sGateway 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 K8sGateway to automatically create Upstreams for any Kubernetes service that is created and discovered in the cluster.

For more information, see the Upstream API reference.

Types

Check out the following guides for examples on how to use the supported Upstreams types with K8sGateway.

Discovery

K8sGateway comes with a built-in service discovery feature that can scan the Kubernetes services and Functions in your cluster and automatically create K8sGateway 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
• OpenAPI-based Functions

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 K8sGateway installation to enable service discovery.

   helm upgrade -n gloo-system gloo-gateway gloo/gloo\
   --values gloo-gateway.yaml \
   --version 1.18.0-beta34 

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

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

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.