Setting up Ingress

Step 1: Create a ClusterIP service

A ClusterIP service is required to make your app reachable from within the cluster so that external requests can be forwarded to the app pod. To be included in Ingress load balancing, the names of the ClusterIP services that expose your apps must be unique across all namespaces in your cluster.

For each app deployment that you want to expose, create a Kubernetes ClusterIP service. Your app must be exposed by a Kubernetes service to be included in the Ingress load balancing.

kubectl expose deploy <app_deployment_name> --name my-app-svc --port <app_port> -n <namespace>

Step 2: Set up TLS termination with TLS certificates and Kubernetes secrets

Your TLS certificate must be stored as a Kubernetes secret in each namespace where your apps exist.

• To use the IBM-provided Ingress subdomain, see Setting up TLS secrets for the IBM-provided Ingress subdomain.

• To use a custom domain, see Setting up TLS secrets for custom subdomains.

Step 3: Create the Ingress resource

Create the Ingress resource to define the routing rules that the Ingress controller uses to route traffic to your app service.

1. Create the Ingress resource in a YAML file.

   The format of the Ingress resource definition varies based on your cluster's Kubernetes version, because API version networking.k8s.io/v1beta1 is unsupported in Kubernetes cluster versions 1.22+.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: my-ingress-resource
   spec:
     ingressClassName: nginx-example
     tls:
     - hosts:
       - <domain_name>
       secretName: <tls_secret_name>
     rules:
     - host: HOSTNAME
       http:
         paths:
         - path: <app_path_1>
           pathType: Prefix
           backend:
             service:
               name: <app_service_1>
               port:
                 number: 80
         - path: <app_path_2>
           pathType: Prefix
           backend:
             service:
               name: <app_service_2>
               port:
                 number: 80
   
   

   annotations

   kubernetes.io/ingress.class: Specify the Ingress class to apply. The IBM-provided Ingress classes are "public-iks-k8s-nginx" for public ALBs and "private-iks-k8s-nginx" for private ALBs.

   Specify this custom class in an IngressClass resource and a ibm-ingress-deploy-config configmap. To customize routing for Ingress, you can add Kubernetes NGINX annotations (nginx.ingress.kubernetes.io/<annotation>). Custom IBM Cloud Kubernetes Service annotations (ingress.bluemix.net/<annotation>) are not supported.

   Note: For configurations in which another component manages your Ingress ALBs, such as if Ingress is deployed as part of a Helm chart, don't specify this annotation. Instead, find the Ingress class for your configuration, and specify that class in a spec.ingressClassName: <class_name> field.

   ingressClassName

   The Ingress class name. The IBM-provided Ingress classes are public-iks-k8s-nginx for public ALBs and private-iks-k8s-nginx for private ALBs.

   tls.hosts

   To use TLS, replace <domain> with the IBM-provided Ingress subdomain or your custom domain.

   tls.secretName

   Replace <tls_secret_name> with the name of the Kubernetes secret where your TLS certificate is stored.

   host

   Replace <domain> with the IBM-provided Ingress subdomain or your custom domain.

   path

   Replace <app_path> with a slash or the path that your app is listening on. The path is appended to the specified Ingress domain to create a unique route to your app. When you enter this route into a web browser, network traffic is routed to the ALB. The ALB looks up the associated service and sends network traffic to the service. The service then forwards the traffic to the pods where the app runs.

   pathType

   The URL path matching method. Supported values are ImplementationSpecific, Exact, or Prefix. For more information about and examples of each path type, see the community Kubernetes documentation.

   service.name

   Replace app1_service and app2_service, and so on, with the name of the services you created to expose your apps. Make sure that the apps you specify are in the same namespace.

   service.name

   Replace <app1_service> and <app2_service>, and so on, with the name of the services you created to expose your apps. Make sure that the apps you specify are in the same namespace.

   service.port.number

   The port that your service listens to. Use the same port that you defined when you created the Kubernetes service for your app.

2. Apply the Ingress resource to your cluster. Ensure that the resource deploys into the same namespace as the app services that you specified in the resource.

   kubectl apply -f community-ingress-resource.yaml -n <namespace>
   

Step 4: Verify your Ingress setup

1. List your ALBs and copy the IP address (classic) or hostname (VPC) for one ALB that runs the Kubernetes Ingress image. In the output, choose an ALB that has a Build in the format <community_version>_<ibm_build>_iks.

   ibmcloud ks ingress alb ls -c <cluster>
   

2. Use the ALB's IP address (classic) or hostname (VPC), the app path, and your domain to verify that you can successfully send traffic to your app through this ALB.

   curl http://<ALB_IP>/<app_path> -H "Host: <ingress_subdomain>"
   

   For example, to send a request to an app called myapp by using a default Ingress subdomain, run the following command.

   curl http://169.X.X.X/myapp -H "Host: mycluster-a1b2cdef345678g9hi012j3kl4567890-0000.us-south.containers.appdomain.cloud"
   

Having trouble connecting to your app through Ingress? Try Troubleshooting Ingress. You can check the health and status of your Ingress components by running ibmcloud ks ingress status-report get -c <cluster_name_or_ID>.

Creating custom domains for public ALBs

Follow the steps to create a custom domain for public ALBs.

1. Create a custom domain. To register your custom domain, work with your Domain Name Service (DNS) provider or IBM Cloud DNS. If the apps that you want Ingress to expose are in different namespaces in one cluster, register the custom domain as a wildcard domain, such as *.custom_domain.net. Note that domains are limited to 130 characters or fewer in Kubernetes version 1.20 or later.

2. Define an alias for your custom domain by specifying the IBM-provided subdomain as a Canonical Name record (CNAME). To find the IBM-provided Ingress domain, run ibmcloud ks cluster get --cluster <cluster_name> and look for the Ingress subdomain field.

   Specifying the IBM-provided subdomain as a CNAME is required for automatic health checks to remove any failing IPs from the DNS response, and to ensure that your custom domain updates when you add or remove ALBs.

Creating custom domains for private ALBs

Follow the steps to create a custom domain for private ALBs. Note that custom domains are required to use Ingress with private ALBs.

If you have a classic cluster with only a private VLAN, you must first configure your own DNS service that is available on your private network.

1. Create a custom domain through your DNS service provider. Note that Ingress URLs must be 130 characters or fewer.

2. Map your custom domain to the private ALBs by adding their IP addresses as A records (classic clusters) or their VPC hostname as a CNAME (VPC clusters). To find the ALB IP addresses (classic) or hostname (VPC), run ibmcloud ks ingress alb ls -c <cluster_name_or_ID>.