Skip to content
kix docs

Install ingress-nginx

Add the ingress-nginx package when the cluster should run its own NGINX Ingress controller. The package creates the controller workload, Service, IngressClass, admission webhook, and their RBAC resources.

Add the controller instance

Section titled “Add the controller instance”

Add one instance in a platform namespace:

how-to/platform/ingress-cluster.nix (L22–L24)
      instances.ingress-system."ingress-nginx" = {
        package = packages."ingress-nginx";
      };

View source on GitHub ↗

The instance name becomes the default IngressClass name, so it has to be a legal Kubernetes object name. ingress-nginx is lowercase; ingressNginx is refused at evaluation. Packages that use kix.expose still resolve this controller, because the package declares meta.defaultAliases = [ "ingressNginx" ] and that alias is what the dependency matches on.

Choose how traffic reaches the controller

Section titled “Choose how traffic reaches the controller”

The controller Service defaults to ClusterIP. Keep that default when another in-cluster component forwards traffic to ingress-nginx.

For a cloud or bare-metal environment with LoadBalancer support, set config.serviceType = "LoadBalancer" on the instance. Use config.serviceAnnotations for provider-specific load balancer settings.

Evaluation rejects the Service when the cluster declares the loadBalancer role absent, as the kind flavor does. A managed provider instance satisfies the role. So does a shadowable or exclusive environment binding for a load balancer already supplied by the platform. If the cluster does not declare the role, Kix treats its availability as unknown and emits a trace warning instead of rejecting the Service.

Set config.replicaCount when the controller should run more than one replica.

Inspect and deploy

Section titled “Inspect and deploy”

Inspect the main generated resources:

Run in kix-examples/ Output excerpt 
❱ kix build how-to-platform-ingress --output json
[
  {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "ingress-nginx",
      "namespace": "ingress-system"
    },
    "replicas": 1
  }
]

The example renders one controller Deployment, a ClusterIP Service, and an IngressClass named ingress-nginx.

Deploy the cluster:

Run in kix-examples/ 
❱ kix deploy how-to-platform-ingress

After the deploy completes, check the controller resources:

Run in kix-examples/ 
❱ kix status how-to-platform-ingress

The controller must be ready before an Ingress can accept traffic. If the Service is a LoadBalancer, also wait for your provider to assign its external address.