Enabling chargeback feature

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.

Editing the IBMLicensing custom resource

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

Filtering the license usage data by user-defined 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.

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.

Enable filtering by group

To enable filtering by group, complete the following steps.

  1. Edit the IBMLicensing custom resource (CR).

    • 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.
    • From the command line:

      Run the following command:

      • OpenShift: oc edit IBMLicensing instance -n <your-License-Service-namespace>
      • Kubernetes: kubectl edit IBMLicensing instance -n <your-License-Service-namespace>

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

  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:

Table 1. Estimated retention period for products and groups
Environment Small Medium Large
Products up to 50 50-75 more than 75
Suggested retention period 1 quarter (90 days) 2 months (60 days) 1 month (30 days)

Retrieve license usage data by group

For more information about the API and the perameters, 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.

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.

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 image shows the breakdown of the license usage on the cluster.

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

Table 2. Overall usage of IBM MQ Advanced
Information Value Comments
Overall usage of IBM MQ Advanced on the cluster 1 vCPU + 1 vCPU + 2 vCPUs = 4 vCPUs To calculate the overall usage of the bundled product, add the vCPUs that are used by all the instances of the bundled product in the cluster. vCPU is calculated according to the IBM Container Licensing rules. For more information, see IBM Container Licenses on Passport Advantage.
Metric conversion for IBM MQ Advanced 2:1 Metric conversion is defined in the licensing document of the product
Metric converted quantity for IBM MQ Advanced on the cluster 4 vCPUs * 2:1 = 2 VPCs To calculate the metric converted quantity, multiply the overall usage of the bundled product on the cluster by the metric conversion ratio. As a result, the value represents the number of VPCs that the bundled product contributes on the cluster
Converted metric contribution of IBM MQ Advanced in the HR group 1 vCPU /4 vCPUs * 2 VPCs = 0.5 VPC To calculate the contribution of the bundled product within the group divide the number of the vCPUs used within the group by the overall number of vCPUs used on the cluster and multiply it by the metric converted quantity for the cluster.

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