How-to guide Platform capabilities

Expose a service with Ingress

Add ingress-nginx to a cluster and expose a package Service on a hostname.

Use kix.expose when a package already creates a Service and the cluster uses ingress-nginx. Kix connects the generated Ingress to the Service and applies it after the Service and ingress controller resources.

This guide assumes you have a local package whose returned parts include a Service named service.

Make the package exposable

Add the standard ingress options to the package:

21
  options.ingress = kix.options.ingress;

View source on GitHub ↗

The cluster author will use config.ingress.host to choose the hostname. The option set also accepts annotations for controller-specific configuration.

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, so the package doesn’t need to repeat either value.

Add ingress-nginx to the cluster

Create one ingress-nginx instance in the cluster:

22
      instances.ingress-system."ingress-nginx" = {
23
        package = packages."ingress-nginx";
24
      };

View source on GitHub ↗

kix.expose requests a dependency called ingressNginx, and the package’s meta.defaultAliases carries that name, so the lowercase ingress-nginx instance resolves it. The instance name has to be lowercase because the package names its resources after it. If the cluster already has one compatible instance, use that instance instead.

The ingress-nginx Service defaults to ClusterIP. Set config.service.spec.type = "LoadBalancer" when your environment provides external load balancers and traffic must enter the cluster through that Service.

Set the application hostname

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

28
      instances.ingress-example.web = {
29
        package = exposureApp;
30
        config.ingress.host = "web.example.test";
31
      };

View source on GitHub ↗

Kix resolves the ingressNginx dependency and creates an Ingress for the application’s Service.

Check the result

Evaluate the cluster before deploying it:

kix-examples/

❱ kix check how-to-platform-ingress
 TOOL       RESULT  DETAILS                       
 eval       pass    31 manifests evaluated        
 scorecard  pass    0 errors, 15 warnings, 1 info

Inspect the generated Ingress:

kix-examples/ output excerpt

❱ kix build how-to-platform-ingress --output json
{
  "apiVersion": "networking.k8s.io/v1",
  "kind": "Ingress",
  "metadata": {
    "name": "web",
    "namespace": "ingress-example"
  },
  "spec": {
    "ingressClassName": "ingress-nginx",
    "rules": [
      {
        "host": "web.example.test",
        "http": {
          "paths": [
            {
              "backend": {
                "service": {
                  "name": "web",
                  "port": {
                    "number": 80
                  }
                }
              },
              "path": "/",
              "pathType": "Prefix"
            }
          ]
        }
      }
    ]
  }
}

The Ingress uses web.example.test, selects the ingress class exposed by the controller instance, and sends requests for / to port 80 of the web Service.

Before sending traffic, point the hostname at the address through which your ingress controller is reachable. The way you obtain that address depends on the cluster environment.