Expose a service with Ingress

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

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:

  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:

    (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:

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

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.serviceType = "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:

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

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:

Run in kix-examples/

❱ kix check how-to-platform-ingress
 TOOL         RESULT  DETAILS                                                       
 eval         pass    30 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 15 warnings, 2 info

Inspect the generated Ingress:

Run in 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.