Enabling optional features

You can enable the optional features of License Service to get extra benefits.

License Service works in the background and does not require any configuration for license compliance. However, you can perform optional configuration to enable additional License Service features and get extra benefits. By default, the features are disabled and transparent. To enable these features, edit the IBMLicensing custom resource.

Available features:

• Chargeback: Filtering the license usage data by user-defined groups - Use this feature to filter the license usage data by groups that are based on namespaces. Thanks to grouping, you can see how the internal organizations or business divisions in your company contribute to the overall license usage. This information might also help you monitor the namespaces during migrating your software to Cloud, or with establishing the potential chargeback.
• Enabling hyperthreading - Use this feature to enable License Service to properly count your license usage on the clusters where Simultaneous multithreading (SMT) or Hyper-Threading (HT) are enabled. When you enable hyperthreading, your license usage on clusters with SMT or HT are aggregated with regard to the hyperthreading rules.

Editing the IBMLicensing custom resource

Learn how to edit the IBMLicensing custom resource to enable the additional features.

• From the OpenShift console:

  1. Log in to your OpenShift console.
  2. Go to Operators > Installed Operators.
  3. From the Project drop-down list, select All Projects
  4. Select IBM Licensing Operator.
  5. Select the IBM License Service tab. The instance of License Service custom resource is listed.
  6. From the overflow action menu, select Edit IBMLicensing.

  7. Edit the YAML. For example, to enable chargeback, add the following line: chargebackEnabled: true under spec.

     spec:
      datasource: datacollector
      chargebackEnabled: true
      httpsEnable: true
     

  8. Click Save.

• From the command line:

  1. Run the following command:

     oc edit IBMLicensing instance -n ibm-common-services
     

     Note: The command assumes that the IBM Cloud Pak foundational services are installed in ibm-common-services namespace. If your product installs foundational services in a different namespace, adjust the command.

  2. Make your changes to the YAML.

Chargeback - Filtering the license usage data by user-defined groups

This feature is available from IBM Cloud Pak® foundational services version 3.7.x.

For license compliance purposes, License Service automatically collects information about the highest license usage of your products in all namespaces in the entire cluster. However, for internal accounting, you might need to calculate the expenses associated with the license usage of the individual internal organizations or business divisions in your company, that is - chargeback. Thanks to the new feature, you can define groups and assign namespaces to these groups. Then, you can retrieve the license usage reports for the individual groups. As a result, you can analyze and understand the contribution of each group to the overall license usage, especially during the peak, or for any time range. You can also see which group has the highest and lowest usage, and what software is mostly used throughout your organization.

To filter the license usage by groups, divide your namespaces into groups by labeling them. You can assign multiple namespaces to one group. If you do not assign a namespace to any group, you do not track its contribution to the overall usage. Next, enable filtering feature in the IBMLicensing custom resource, and retrieve the license usage with the /products API with groupName parameter.

Filtering by groups

Note: The following procedure is dedicated to tracking the license usage of products that are licensed with Virtual Processor Core (VPC) and Processor Value Unit (PVU). For the products that are licensed with other license metrics, check the product documentation to check if filtering by groups is supported and on what conditions.

Complete the following procedures to enable filtering by group.

1. Define groups

To define groups, add the group labels to your namespaces by completing the following steps:

1. Log in to your OpenShift cluster console.

2. Go to Administration > Namespaces.

3. Find the namespace that you want to label.

4. Click the overflow action menu next to the namespace name, and select Edit labels.

5. Add the following label to the list:

   ibm-chargeback-group=<groupName>
   

   where groupName is the name of the group that you will use to filter the data.

   Important: The name of the group must be other than default. This name is reserved for the development use only.

6. Repeat these steps for the remaining namespaces that you want to divide into groups. You can assign more than one namespace to one group.

2. Enable filtering by group

To enable filtering by group, complete the following steps.

1. Edit the IBMLicensing custom resource.

2. Add the following parameters to the IBMLicensing section, under spec:

   • To enable filtering by group, add the following line:

     chargebackEnabled: true
     

   • Optional: To set the retention period for which the filtered data is stored, add the following line and specify the number of days for storing the filtered data:

     chargebackRetentionPeriod: <number of days>
     

     Note: Specify the chargebackRetentionPeriod to define the number of days after which the data is deleted. If you do not add chargebackRetentionPeriod to the custom resource, the retention period is set to 62 days.

Retention period

Storing information about license usage of the products that are installed on the namespaces that belong to the groups requires extra memory. Because of that, the filtered data can only be stored for a limited time. By default, the chargebackRetentionPeriod is set to 62 days. In case of issues with retrieving the filtered data, decrease the retention period to avoid overflow.

Note: Remember to regularly generate audit snapshot to preserve all the data required for compliance purposes. Generate audit snapshot at least once during the span of retention period.

To estimate the retention period that best suits your environment consider the number of products that are deployed in the namespace, and the number of groups that you define.

Given that the maximal accepted size of the storage is 1 MiB, which equals 1048576 bytes, you can use the following formula to estimate the maximal retention period for your environment:

1048576 / (number of products * number of groups * 11.85)

The outcome is the number of days to which you should set the retention period for the specified number of products and groups.

The following table shows the estimated retention period for different number of products and groups expressed in the number of days:

3. Retrieve license usage data by group

To retrieve the license usage data for the defined group, use the /products API and use the groupName parameter for filtering.

You can retrieve license usage for more than one group by adding more groupName=<groupName> parameters to get the total contribution of these groups.

API URL: <License Service URL>/products?token=<token>&groupName=<groupName>

For more information, see Retrieving license usage of products.

Understanding the reported values

The API retrieves the license usage of products that are deployed in the namespaces that are assigned to the defined group or groups. The license usage is expressed by the metricQuantity value which is the number of metric units that the group contributes to the overall usage of the product on the cluster. As a result the metricQuantity be expressed by a fraction.

Example scenario

You can use chargeback to track license usage for your products in different divisions in your organization. First, think about how many groups you can distinguish, and gather information about which namespaces these groups use.

In this example, the organization needs to define two groups HR and Procurement. The organization follows the procedure and defines the groups by adding the labels to appropriate namespaces, and then enables filtering by group. As the organization defines only 2 groups that use only one product, the chargeback retention period is set to 90 days as recommended for small environments.

• The following API retrieves license usage for the HR group:

  LS-host/products?token=token&groupName=HR

Response:

  "name": "IBM Cloud Pak for Integration",
  "id": "c8b82d189e7545f0892db9ef2731b90d",
  "metricPeakDate": "2021-07-08",
  "metricName": "VIRTUAL_PROCESSOR_CORE",
  "metricQuantity": 1.5

• The following API retrieves license usage for the Procurement group:

  LS-host/products?token=token&groupName=Procurement

  Response:

  "name": "IBM Cloud Pak for Integration",
  "id": "c8b82d189e7545f0892db9ef2731b90b",
  "metricPeakDate": "2021-07-08",
  "metricName": "VIRTUAL_PROCESSOR_CORE",
  "metricQuantity": 0.5
  

Based on the example, the HR group contributes 1.5 VPCs of the overall usage of IBM Cloud Pak for Integration on the peak date, while Procurement group contributes 0.5 VPC.

• The following API retrieves the overall license usage that is registered on a cluster:

  LS-host/products?token=token

  Response:

  "name": "IBM Cloud Pak for Integration",
  "id": "c8b82d189e7545f0892db9ef2731b90d",
  "metricPeakDate": "2021-07-08",
  "metricName": "VIRTUAL_PROCESSOR_CORE",
  "metricQuantity": 4
  

As the overall license usage of IBM Cloud Pak for Integration on the peak date equals 4, and the HR group contributes 1.5 VPCs and the Procurement group 0.5 VPC, you can calculate that the remaining usage, 2 VPCs, is used outside of the defined groups.

The following image represents the license usage on the cluster.

The following statements summarize the license usage calculations for the cluster:

• The group contribution, that is expressed in the number of metrics, is a sum of converted metric contributions of all bundled products that are reported for this group.
• The converted metric contribution of a bundled product in the group is proportional to the overall use of the product on the cluster.
• To calculate the contribution of the HR group, the converted metric contribution needs to be estimated for IBM MQ Advanced and IBM MQ.
• The following example shows how to calculate the converted metric contribution for IBM MQ Advanced that is deployed within the HR group.

You can base on the example to similarly calculate the converted metric contribution of any bundled product within the group.

Enabling hyperthreading

This feature is available from IBM Cloud Pak® foundational services version 3.11.x.

License Service supports hyperthreading, also referred to as Simultaneous multithreading (SMT) or Hyper-Threading (HT). To take advantage of the benefits of using this technology, enable hyperthreading in License Service. Hyperthreading might have great impact on your licensing costs. For more information, see Hyperthreading.

You can enable hyperthreading for the clusters where all working nodes have SMT or HT enabled. To enable hyperthreading, complete the following steps.

1. Edit the IBMLicensing custom resource.

2. Add the following lines to the IBMLicensing section, under spec:

features:
  hyperThreading:
    threadsPerCore: <number of threads>

Note: Set the value of the threadsPerCore parameter to the lowest number of threads per core in your infrastructure. The following table lists the acceptable values.