How-to guide Platform capabilities

Expose a service with Gateway API

Create a Gateway and route a package Service through it with an HTTPRoute.

Use kix.expose to create an HTTPRoute for a package Service when the cluster uses Gateway API.

This guide assumes:

Your cluster has the Gateway API CRDs and an Envoy Gateway controller.
You have a local package whose returned parts include a Service named service.

The envoy-gateway Kix package used below creates the GatewayClass and Gateway resources. Its default controller name is gateway.envoyproxy.io/gatewayclass-controller, which must match the controller installed in the cluster.

Make the package exposable

Add the standard ingress options to the package:

21
  options.ingress = kix.options.ingress;

View source on GitHub ↗

The option name is ingress for both supported exposure resources. Set config.ingress.host on an instance to choose its hostname.

Add kix.expose to the package’s build list and name the Service part it should route to:

56
    (kix.expose { service = "service"; })

View source on GitHub ↗

kix.expose reads the Service name and port from that part.

Create the Gateway

Add a Gateway instance with an HTTP listener:

19
      instances.gateway-system.gateway = {
20
        package = packages."envoy-gateway";
21
        config.listeners = [
22
          {
23
            name = "http";
24
            port = 80;
25
            protocol = "HTTP";
26
            allowedRoutes.namespaces.from = "All";
27
          }
28
        ];
29
      };

View source on GitHub ↗

The Gateway is in gateway-system, while the application in the next step is in another namespace. allowedRoutes.namespaces.from = "All" permits that HTTPRoute to attach to this listener.

The listener’s protocol, hostname, and allowedRoutes also decide the application’s public URL (self.exposure.url): an HTTP listener on port 80 gives http://<host>. If no listener accepts the host from the application’s namespace, evaluation fails and names each listener.

If your controller uses a different controller name, set config.controllerName on this instance to the value advertised by that controller.

Set the application hostname

Add the application instance and set the host clients will request:

33
      instances.gateway-example.web = {
34
        package = exposureApp;
35
        config.ingress.host = "web.example.test";
36
      };

View source on GitHub ↗

Kix resolves the gateway dependency and creates an HTTPRoute for the application’s Service.

Check the result

Evaluate the cluster before deploying it:

kix-examples/

❱ kix check how-to-platform-gateway
 TOOL       RESULT  DETAILS                      
 eval       pass    20 manifests evaluated       
 scorecard  pass    0 errors, 9 warnings, 1 info

Inspect the generated HTTPRoute:

kix-examples/ output excerpt

❱ kix build how-to-platform-gateway --output json
{
  "apiVersion": "gateway.networking.k8s.io/v1",
  "kind": "HTTPRoute",
  "metadata": {
    "name": "web",
    "namespace": "gateway-example"
  },
  "spec": {
    "hostnames": [
      "web.example.test"
    ],
    "parentRefs": [
      {
        "name": "gateway",
        "namespace": "gateway-system"
      }
    ],
    "rules": [
      {
        "backendRefs": [
          {
            "name": "web",
            "port": 80
          }
        ],
        "matches": [
          {
            "path": {
              "type": "PathPrefix",
              "value": "/"
            }
          }
        ]
      }
    ]
  }
}

The route attaches to the gateway-system/gateway Gateway and sends requests for web.example.test to port 80 of the web Service.

Route several paths

Pass paths instead of service when one hostname fans out to several Service parts. Each entry names a path and the Service part behind it; pathType defaults to Prefix and port to the port the Service part publishes through out.port:

1
(kix.expose {
2
  paths = [
3
    { path = "/"; service = "frontend"; }
4
    { path = "/api"; pathType = "Exact"; service = "api"; }
5
  ];
6
})

Kix renders one HTTPRoute with a rule per entry. In a cluster that routes through ingress-nginx, the same paths list renders one Ingress with a path entry per element.