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:

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.

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:

ICP cluster
IBM Cloud Kubernetes Services (IKS) on IBM Cloud
Amazon Elastic Kubernetes Service (EKS)
VMware Tanzu Kubernetes Grid
ICP 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:
    ingressClassName: ibm-icp-management
    annotations:
      "icp.management.ibm.com/rewrite-target": "/"
      "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:
    ingressClassName: public-iks-k8s-nginx
    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
    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:
    ingressClassName: nginx
    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(/|$)(.*)
    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:
    ingressClassName: nginx
    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(/|$)(.*)
    host: $loadBalancerIP
EOF

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:

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.
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
...
```

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
spec:
  ingressClassName: nginx
  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:

/status
/products
/bundled_products
/snapshot

Checking License Service components

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

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

Check Ingress settings depending on your parameter settings.
```
kubectl get ingress -n ibm-licensing -o yaml
```
Then, examine the output. It should include the host, path, tls (if configured), and other networking information under spec and status sections.
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.