Configuration

This version of documentation is no longer updated. For the latest information, see the following links:
- Continuous Delivery (CD) documentation
- Support Cycle-2 (SC-2) documentation

Learn how to configure License Service after installation if needed.

Configuring 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 installation method.

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 installation method.

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:
      "kubernetes.io/ingress.class": nginx # Change to your ingress name
      "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:

    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-common-services
  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-common-services
  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-common-services
  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-common-services -o jsonpath="{range .items[*]}{.metadata.name}{'\n'}" | grep ibm-licensing-service-instance`
kubectl logs $podName -n ibm-common-services
kubectl describe pod $podName -n ibm-common-services

  2. Check Ingress settings depending on your parameter.

    kubectl get ingress -n ibm-common-services -o yaml

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

  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.

Using custom certificates

IMPORTANT: From License Service version v1.16.6, custom external certificates is handled using Ingress.

You can use either a self-signed certificate or a custom certificate when you use License Service API over https.

To set the custom certificate for automatic ingress configuration

  1. Change the certificate name to tls.crt.

  2. Change the key name to tls.key.

  3. Run the following command to change the directory to where the certificate and the key are stored:

    cd <certificate_directory>

  4. Create a secret by using the following command:

    licensingNamespace=$(kubectl get pods --all-namespaces | grep "ibm-licensing-service-" | awk {'print $1'})
kubectl create secret tls ibm-licensing-certs --key tls.key --cert tls.crt -n ${licensingNamespace}

  5. Open the IBMLicensing instance YAML to include the certificate by running the following command:

    kubectl edit IBMLicensing instance

  6. Edit the YAML and add the following sections under spec.ingressOptions.

    • Specify host explicitly by setting spec.ingressOptions.host to your external endpoint hostname.

    • To apply custom certificate, add following section under spec.ingressOptions.

      tls:
- hosts:
      - <your_hostname>
  secretName: ibm-licensing-certs

      Note: Hostname specified in spec.ingressOptions.host must exist under spec.ingressOptions.tls[0].hosts. Also, the custom certificate must be issued to this hostname. For example:

      apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicensing
metadata:
  name: instance
spec:
  ingressOptions:
      hosts: example.com
      tls:
        - hosts:
              - example.com
          secretName: ibm-licensing-certs

  7. Edit the YAML and add the following parameters to the IBMLicensing section, under spec:

    • To enable the https connection, add the following line: httpsEnable: true

    • To apply the custom certificate that you created as ibm-licensing-certs, add the following line: httpsCertsSource: custom

    For example:

    apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicensing
metadata:
    name: instance
  spec:
    httpsEnable: true
    httpsCertsSource: custom

  8. Save the changes in YAML.

To set the custom certificate for manual ingress configuration

To set the custom certificate for manual ingress configuration, see TLS.

Cleaning existing License Service dependencies

Earlier versions of License Service, up to 1.1.3, used OperatorSource and Operator Marketplace. These dependencies are no longer needed. If you installed the earlier version of License Service, before installing the new version remove the existing dependencies from your system.

Cleaning existing License Service dependencies outside of OpenShift

  1. Delete OperatorSource.

    To delete an existing OpenSource, run the following command:

    GLOBAL_CATALOG_NAMESPACE=olm
opencloudioSourceName=opencloud-operators
kubectl delete OperatorSource ${opencloudioSourceName} -n ${GLOBAL_CATALOG_NAMESPACE}

    where GLOBAL_CATALOG_NAMESPACE value is your global catalog namespace.

  2. Delete OperatorMarketplace.

    Note: Before deleting OperatorMarketplace check whether it is not used elsewhere, for example, for other Operators from OperatorMarketplace.

    To delete OperatorMarketplace, run the following command:

    GLOBAL_CATALOG_NAMESPACE=olm
kubectl delete Deployment marketplace-operator -n ${GLOBAL_CATALOG_NAMESPACE}
kubectl delete RoleBinding marketplace-operator -n ${GLOBAL_CATALOG_NAMESPACE}
kubectl delete ClusterRoleBinding marketplace-operator
kubectl delete ServiceAccount marketplace-operator -n ${GLOBAL_CATALOG_NAMESPACE}
kubectl delete Role marketplace-operator -n ${GLOBAL_CATALOG_NAMESPACE}
kubectl delete ClusterRole marketplace-operator

    where GLOBAL_CATALOG_NAMESPACE value is your global catalog namespace.

  3. Reinstall License Service to get CatalogSource that is missing. For more information, see Installing License Service.

Cleaning existing License Service dependencies on OpenShift Container Platform

  1. Delete OperatorSource.

    To delete an existing OpenSource, run the following command:

    GLOBAL_CATALOG_NAMESPACE= openshift-marketplaceolm
opencloudioSourceName=opencloud-operators
kubectl delete OperatorSource ${opencloudioSourceName} -n ${GLOBAL_CATALOG_NAMESPACE}

  2. Reinstall License Service to get CatalogSource that is missing. For more information, see Installing License Service.

Modifying the application deployment resources

You can modify the resources that are requested and limited by the Deployment for Application by editing the IBMLicensing instance.

To learn what resources are required for License Service in your environment, see Preparing for installation: Required resources.

  1. To modify the IBMLicensing instance, run the following command:

    kubectl edit IBMLicensing instance

  2. Modify the resource limits and resources in the following yaml and paste it in the command line.

    apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicensing
metadata:
  name: instance
spec:
# ...
  resources:
    limits:
      cpu: 500m # <- set the CPU limit to the desired value
      memory: 512Mi # <- set the memory limit to the desired value
    requests:
      cpu: 200m # <- set the requests limit to the desired value
      memory: 256Mi # <- set the memory limit to the desired value
# ...

    Where m stands for Millicores, and Mi for Mebibytes