Configure Gateway API

Gateway API is an official Kubernetes project focused on L4 and L7 routing in Kubernetes. This project represents the next generation of Kubernetes Ingress, Load Balancing, and Service Mesh APIs. From the outset, it has been designed to be generic, expressive, and role-oriented. (Official documentation)

On this runbook we’ll show you how to configure the basics to start using Gateway API with StackGres.

Important: In case your Kubernetes cluster, does not have a LoadBalancer implementation, we recommend installing one so the Gateway resource has an Address associated with it. We recommend using MetalLB.

Gateway API components

There are four main components to configure the Gateway API:

  1. Gateway Controller: A gateway controller is software that manages the infrastructure associated with routing traffic across contexts using Gateway API, analogous to the earlier ingress controller concept. Gateway controllers often, but not always, run in the cluster where they’re managing infrastructure.

There are various controller you can use for your infrastructure, check the list here.

For the demo purpose we will use the Envoy Gateway.

  1. GatewayClass: Is a cluster-scoped resource. There must be at least one GatewayClass defined in order to be able to have functional Gateways.

  2. Gateways: A Gateway describes how traffic can be translated to Services within the cluster. That is, it defines a request for a way to translate traffic from somewhere that does not know about Kubernetes to somewhere that does.

It defines a request for a specific load balancer config that implements the GatewayClass’ configuration and behaviour contract. The resource may be created by an operator directly, or may be created by a controller handling a GatewayClass.

  1. Routes: Route resources define protocol-specific rules for mapping requests from a Gateway to Kubernetes Services.

We will show you how to create a TCPRoute to handle Postgres traffic. You can check the different types of Routes here

SGCluster

In order to focus on the Gateway API configuration we will assume that you already have your SGCluster up and running. Check the StackGres Demo Quickstart to create your cluster. The demo cluster used here was created on GKE.

Demo SGCluster:

❯ kubectl get sgclusters.stackgres.io -n my-db NAME VERSION INSTANCES PROFILE DISK my-db 16.2 1 size-s 10Gi

SGCluster service:

 kubectl get services -n my-db -l stackgres.io/cluster=true NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE my-db ClusterIP 10.63.219.145 <none> 5432/TCP,5433/TCP 61m my-db-config ClusterIP None <none> <none> 61m

Configure Gateway API

1. Install the Gateway API Controler:

Even though GKE already provides a Gateway API controller, we’ll use the Envoy controller.

Install it executing the next command:

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace

Note: For custom requirements check the official documentation

2. Create the GatewayClass

cat <<EOF | kubectl apply -f - apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata:  name: eg spec:  controllerName: gateway.envoyproxy.io/gatewayclass-controller EOF

Check the object created:

❯ kubectl get gatewayclasses.gateway.networking.k8s.io NAME CONTROLLER ACCEPTED AGE eg gateway.envoyproxy.io/gatewayclass-controller True 86m

3. Create the Gateway

cat <<EOF | kubectl apply -f - apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata:  name: tcp-gateway  namespace: my-db spec:  gatewayClassName: eg  listeners:  - name: pg-gateway  protocol: TCP  port: 5432  allowedRoutes:  kinds:  - kind: TCPRoute EOF

Check the object created:

❯ kubectl get gateways.gateway.networking.k8s.io -n my-db NAME CLASS ADDRESS PROGRAMMED AGE tcp-gateway eg 34.89.14.197 True 72m

Note that we are using the namespace my-db because only the GatewayClass is cluster-scoped.

The IP address might take a few minutes to be assigned. This is the public IP that you need to use as the service endpoint.

4. Create the TCPRoute

cat <<EOF | kubectl apply -f - apiVersion: gateway.networking.k8s.io/v1alpha2 kind: TCPRoute metadata:  name: my-db-route  namespace: my-db spec:  parentRefs:  - name: tcp-gateway  sectionName: pg-gateway  rules:  - backendRefs:  - name: my-db  port: 5432 EOF
  • Check the sectionName field in the parentRefs. This correspond directly with the name in the listeners in the Gateway
  • The backendRefs correspond to the database service.

Check Postgres connection

Once you configured the Gateway API, the last thing is to check if you have connection to your database cluster:

We got the superuser passsword with the next command:

PASSWORD=$(kubectl get secret -n my-db my-db --template '{{ printf "%s" (index .data "superuser-password" | base64decode) }}') echo "user: postgres" echo "password: $PASSWORD"

output:

user: postgres password: 7a83-4f62-4c71-815

Now we can test the connection to the cluster:

❯ psql -h 34.89.14.197 -p 5432 -U postgres -d postgres Password for user postgres: psql (16.3 (Ubuntu 16.3-1.pgdg22.04+1), server 16.2 (OnGres 16.2-build-6.31)) Type "help" for help. postgres=#

Next steps

  • The above example was intended to show you the basic configuration of the Gateway API. If you want to expose your database, make sure to configure a secure connection to it.

  • Check the security documentation for the Envoy Gateway here