Configuring Kubernetes Ingress

Kubernetes Ingress is an API object that provides routing rules to manage external users' access to the services in a Kubernetes cluster, typically via HTTPS/HTTP.

If you want to configure ingress for License Service for your cluster, it is recommended to follow automatic ingress configuration.

If you have specific ingress configuration where you want to add license service endpoints to it, or have problems with automatic path not working, then follow manual ingress configuration.

After you install License Service, see Checking License Service components.

Automatic Ingress configuration

You can allow the IBMLicensing operator to handle ingress creation. Ingress is managed by the License Service Operator and based on the configuration in IBMLicensing instance.

Complete the following steps:

  1. Get the nginx Ingress controller, for example, from https://kubernetes.github.io/ingress-nginx/deploy.

    Note: If you already have Ingress controller on the cluster, you do not need another one.

  2. Apply this IBMLicensing instance to your cluster:

    cat <<EOF | kubectl apply -f -
    apiVersion: operator.ibm.com/v1alpha1
    kind: IBMLicensing
    metadata:
      name: instance
    spec:
      apiSecretToken: ibm-licensing-token
      datasource: datacollector
      httpsEnable: true
      ingressEnabled: true
      ingressOptions:
        annotations:
          "nginx.ingress.kubernetes.io/rewrite-target": "/\$2" # <- if you copy it into yaml file, then use "/$2"
         "nginx.ingress.kubernetes.io/backend-protocol": HTTPS
        path: /ibm-licensing-service-instance(/|$)(.*)
    EOF
    

    See the following examples for specific clusters:

    cat <<EOF | kubectl apply -f -
    apiVersion: operator.ibm.com/v1alpha1
    kind: IBMLicensing
    metadata:
      name: instance
    spec:
      apiSecretToken: ibm-licensing-token
      datasource: datacollector
      httpsEnable: true
      ingressEnabled: true
      ingressOptions:
        annotations:
          "icp.management.ibm.com/rewrite-target": "/"
          "kubernetes.io/ingress.class": "ibm-icp-management"
          "nginx.ingress.kubernetes.io/backend-protocol": HTTPS
    EOF
    
    • IBM Cloud Kubernetes Services (IKS) on IBM Cloud

    First, get your cluster name or id:

    cluster=<your iks cluster name or id from ibmcloud>
    

    Then, get the subdomain for your cluster, or provide a variable for subdomain:

    subdomain=$(ibmcloud ks cluster get --cluster $cluster | grep "Ingress Sub" | awk '{print $3}')
    

    Then, apply the instance:

    cat <<EOF | kubectl apply -f -
    apiVersion: operator.ibm.com/v1alpha1
    kind: IBMLicensing
    metadata:
      name: instance
    spec:
      apiSecretToken: ibm-licensing-token
      datasource: datacollector
      httpsEnable: true
      ingressEnabled: true
      ingressOptions:
        annotations:
          "nginx.ingress.kubernetes.io/rewrite-target": "/\$2" # <- if you copy it into yaml file, then use "/$2"
          "kubernetes.io/ingress.class": "public-iks-k8s-nginx"
          "nginx.ingress.kubernetes.io/backend-protocol": HTTPS
        host: $subdomain
        path: /ibm-licensing-service-instance(/|$)(.*)
    EOF
    
    • Amazon Elastic Kubernetes Service (EKS)

    To retrieve your host, consult EKS documentation.

    Then, get the subdomain for your cluster or provide a variable for subdomain:

    subdomain=$(kubectl get svc ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
    

    Then, apply the instance:

    cat <<EOF | kubectl apply -f -
    apiVersion: operator.ibm.com/v1alpha1
    kind: IBMLicensing
    metadata:
      name: instance
    spec:
      apiSecretToken: ibm-licensing-token
      datasource: datacollector
      httpsEnable: true
      ingressEnabled: true
      ingressOptions:
        annotations:
          "kubernetes.io/ingress.class": nginx
          "nginx.ingress.kubernetes.io/rewrite-target": "/\$2" # <- if you copy it into yaml file, then use "/$2"
          "nginx.ingress.kubernetes.io/backend-protocol": HTTPS
        path: /ibm-licensing-service-instance(/|$)(.*)
        host: $subdomain
    EOF
    
    • VMware Tanzu Kubernetes Grid

    Before you retrieve the IP, check your current network configuration.

    To get the load balancer IP, and set it as a variable, run the following command:

    loadBalancerIP=$(kubectl get svc ingress-nginx-controller -n ingress-nginx -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
    

    Then, apply the instance:

    cat <<EOF | kubectl apply -f -
    apiVersion: operator.ibm.com/v1alpha1
    kind: IBMLicensing
    metadata:
      name: instance
    spec:
      apiSecretToken: ibm-licensing-token
      datasource: datacollector
      httpsEnable: true
      ingressEnabled: true
      ingressOptions:
        annotations:
          "kubernetes.io/ingress.class": nginx
          "nginx.ingress.kubernetes.io/rewrite-target": "/\$2" # <- if you copy it into yaml file, then use "/$2"
          "nginx.ingress.kubernetes.io/backend-protocol": HTTPS
        path: /ibm-licensing-service-instance(/|$)(.*)
        host: $loadBalancerIP
    EOF
    
  3. Access the instance at your ingress host with the following path: /ibm-licensing-service-instance.

For more information, see Setting up Kubernetes Ingress in IBM Cloud Docs.

Note: For HTTP, set spec.httpsEnable to false, and edit ingressOptions. Read more about the options here: IBMLicensingOperatorParameters.

Troubleshooting: If the instance is not updated properly, for example after updating ingressOptions, try deleting the instance and creating new one with new parameters.

Manual Ingress configuration

To manually configure Ingress, complete the following steps:

  1. Edit the IBMLicensing instance with the following command:

    kubectl edit ibmlicensing instance
    

    Note: License Service consist of a number of Kubernetes resources that are created based on IBMLicensing instance. Edit the instance to change the current configuration.

  2. Disable automatic creation of Ingress in the IBM Licensing instance. Set the ingressEnabled parameter to false. It allows you to create a custom Ingress.

    spec:
    ...
      ingressEnabled: false
    ...
    
  3. Configure Ingress to point to correct path inside License Service. This can be done in three ways:

    • If you can create dedicated subpage for License Service then it can be done by the following way:

      Create Ingress with the following yaml:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: example
        namespace: ibm-licensing
        annotations:
          nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" # <- HTTPS or HTTP depanding of the setting of httpsEnable in the IBMLicensing instance
      spec:
        rules:
          - host: example.ibm.com # <- this should be your dedicated url host that you reserve for this page
            http:
              paths:
                - path: /ibm-licensing-service-instance(/|$)(.*)
                  pathType: Prefix
                  backend:
                    service:
                      name: ibm-licensing-service-instance
                      port:
                        number: 8080
      

      With this configuration, License Service works on all subpages, visit the url you provided instead of example.licensing.ibm.com to see Licensing Services landing page.

    • If you cannot create dedicated subpage, and your ingress controller allows redirects (you do not have other ingresses that share same config with license service and they do not allow ingress redirects) then use this yaml for ingress:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: example
        namespace: ibm-licensing
        annotations:
          nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" # HTTPS or HTTP depanding of the setting of httpsEnable in the IBMLicensing instance
          nginx.ingress.kubernetes.io/rewrite-target: /$2
      spec:
        rules:
          - host: example.ibm.com
            http:
              paths:
              - path: /ibm-licensing-service-instance(/|$)(.*)
                pathType: Prefix
                backend:
                  service:
                    name: ibm-licensing-service-instance
                    port:
                      number: 8080
      

      With this configuration, License Service works on all subpages, visit the url that you have provided instead of example.ibm.com at /ibm-licensing-service-instance to see Licensing Services landing page.

    • If you do not have dedicated page and redirects, then create the following yaml:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: example
        namespace: ibm-licensing
        annotations:
          nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" # <- this should be HTTP if you have httpsEnable set to false in IBMLicensing instance
         kubernetes.io/ingress.class: nginx
      spec:
        rules:
          - host: example.licensing.ibm.com
            http:
              paths:
              - path: /status
                pathType: Prefix
                backend:
                  service:
                    name: ibm-licensing-service-instance
                    port:
                      number: 8080
              - path: /products
                pathType: Prefix
                backend:
                  service:
                    name: ibm-licensing-service-instance
                    port:
                      number: 8080
              - path: /bundled_products
                pathType: Prefix
                backend:
                  service:
                    name: ibm-licensing-service-instance
                    port:
                      number: 8080
              - path: /snapshot
                pathType: Prefix
                backend:
                  service:
                    name: ibm-licensing-service-instance
                    port:
                      number: 8080
      

With this configuration License Service works only on certain subpages, visit the url you provided instead of example.ibm.com in one of the following pages:

Checking License Service components

After you install License Service, complete the following steps to check whether License Service works properly.

  1. To check if the pod is running, use the following commands:

    podName=`kubectl get pod -n ibm-licensing -o jsonpath="{range .items[*]}{.metadata.name}{'\n'}" | grep ibm-licensing-service-instance`
    kubectl logs $podName -n ibm-licensing
    kubectl describe pod $podName -n ibm-licensing
    
  2. Check Ingress settings depending on your parameter settings.

    kubectl get ingress -n ibm-licensing -o yaml
    

    Then, examine the status part of the output. It should include the host, path, tls (if configured), and other networking information.

  3. Run the License Service APIs, and make sure that you get results that reflect your environment's license usage. For more information, see APIs for retrieving License Service data.