APIs for retrieving License Service data

You can retrieve the aggregated license usage data for a cluster from the last 24 months by using dedicated API calls. Additionally, you can use the APIs to retrieve License Service version and health.

Available APIs

API Decription
Retrieving an audit snapshot Retrieve an audit snapshot that is needed to fulfill the requirements of Container Licensing rules.
Retrieving license usage of products Retrieve the list of products that are deployed on the cluster with their license usage. Use this API to integrate with external tools to monitor you license usage.
Retrieving license usage of bundled products Retrieve the list of bundled products that are deployed on the cluster with their license usage. Use this API to integrate with external tools to monitor you license usage.
Retrieving contribution of services Retrieve the contribution of services in the overall license usage of your bundled products. This information is additional and applies only to limited number of enabled products.
Retrieving information about License Service version Retrieve information about License Service version for troubleshooting or upgrade purposes.
Retrieving information about License Service health Retrieve information about License Service health to identify problems.

For an overview of all available APIs, see: License Service API schema.

Obtaining the License Service URL

To obtain the License Service URL that is required to retrieve license usage data from the cluster, complete the following steps:

  1. Open the OpenShift console and go to Networking > Routes.
  2. Set the project to All Projects.
  3. Find the ibm-licensing-service-instance route and copy the URL listed as Location. It is your License Service URL.

Note: Alternatively, you can use the following command to obtain the License Service URL: kubectl get routes -n ibm-common-services | grep ibm-licensing-service-instance | awk '{print $2}'. This 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.

You can use the License Service URL to access the simplified License Service interface for testing purposes. Paste the URL into your browser, select one of the APIs, and provide the authorization token. The interface is limited and retrieves the licensing data for last 30 days for all products.

API authentication

To use the License Service APIs, you need to authenticate first. To learn how to get the secure authentication token, see API authentication.

Retention period

You can use the APIs to retrieve the aggregated license usage for the last 24 months.

Retrieving an audit snapshot

API URL

<License Service URL>/snapshot

API parameters

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves a license usage snapshot for your cluster. An audit snapshot is a compressed .zip package that includes a complete set of audit documents that certify your license usage per cluster.

An audit snapshot consists of the following files:

File name Content
checksum.txt The unique checksums that are a proof that the audit snapshot was not tempered with.
data_condition.txt Audit snapshot metadata that includes information about the cluster, the time and date when the report was generated, and the reported period.
products_<reported_period>_<cluster hostname>.csv The highest license usage for each product that is deployed on the cluster within the reported period.
products_daily_<reported_period>_<cluster hostname>.csv The highest license usage for each product that is deployed on the cluster within the reported period daily.
bundled_products_<reported_period>_<cluster hostname>.csv The highest license usage for each bundled product that is included in the IBM Cloud Paks that are deployed on the cluster within the reported period.
bundled_products_daily_<reported_period>_<cluster hostname>.csv The highest license usage for each bundled product that is included in the IBM Cloud Paks that are deployed on the cluster within the reported period daily.
pub_key.pem The public key file that can be used to verify the signature.rsa file against the checksums.txt file.
signature.rsa A digital signature that can be used to verify whether the checksums.txt file was tampered with.
unrecognized-apps-<reported_period>.csv A list of pods from which the license usage data was not collected on a specified date. The pods have incomplete or missing product annotations that provide the product metadata that is needed for measurements. The information is provided for every date within the reported period. The list contains the namespace followed by a pod name.

Integrating with the audit snapshot

To integrate with the audit snapshot, use the names of the columns from the .csv files as the point of reference, not the column order. The names of the columns are fixed. However, the order of the columns might change.

Retrieving license usage of products

API URL

<License Service URL>/products

API parameters

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API retrieves the following information per product:

Description
name The name of the product.
id The identifier of the product.
metricPeakDate The date when the license metric usage of the product was the highest within the requested period.
metricQuantity The highest number of license units that the product used within the requested period.
metricName The license metric unit that is used by the product.

Retrieving license usage of bundled products

API URL

<License Service URL>/bundled_products

API parameters

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves information about the bundled products that are included in IBM Cloud Paks that are deployed on a cluster with the highest license usage within the requested period.

This API retrieves the following information per each bundled product:

Description
productName The name of the detected bundled product.
productId The identifier of the bundled product.
metricName The license metric unit that is used by the bundled product.
metricPeakDate The date when the license usage of the bundled product was the highest within the requested period.
metricMeasuredQuantity The highest number of license units that the bundled product used within the requested period.
cloudpakId The identification number of the IBM Cloud Pak® to which the program is bundled.
cloudpakVersion Version of the IBM Cloud Pak® to which the program is bundled.
cloudpakMetricName The license metric unit that is used by the entire IBM Cloud Pak® to which the bundled product contributes.
metricConversion The ratio that shows how the license usage of the bundled product is counted when compared with the license usage of the IBM Cloud Pak®. It shows how the program's license metrics are recalculated when compared to the IBM Cloud Pak® license metrics.
metricConvertedQuantity The number of license units that the bundled product contributed to the overall license usage of the IBM Cloud Pak®. The value is calculated by comparing metricMeasuredQuantity against metricConversion.

Retrieving contribution of services

This API is available from IBM Cloud Pak foundational services version 3.19.x.

API URL

<License Service URL>/services

API parameters

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves information about how the usage of services contributes to the overall license usage of the bundled products under which these services are grouped. This information might give you a better understanding of your license usage, however, it is not obligatory from the Container Licensing rules perspective.

You can use this API to retrieve information only for the products that have three-layer reporting structure that includes services that are grouped under bundled products, and are enabled for reporting, such as IBM Cloud Pak for Data.

This API retrieves the following information:

Description
cloudpakId The identifier of the Cloud Pak with which the bundled product and its services are deployed.
cloudpakMetricName The license metric unit that is used by the product.
productName The name of the bundled product.
productId The identifier of the bundled product.
metricName The license metric unit that is used by the bundled product.
serviceName The name of the service that is deployed under the bundled product.
serviceId The identifier of the service.
serviceMetricValue The highest number of license units that the service used that contributed to the overall license usage of its bundled product.
metricDate The date when the license metric usage of the product was the highest within the requested period.

Retrieving information about License Service version

API URL

<License Service URL>/version

API description

This API call retrieves the following information about the License Service version:

Description
version The version of License Service that is deployed on a cluster.
buildDate The buildDate identifies the image that was used to deploy License Service and might be needed for support purposes.
commit The commit ID identifies the image that was used to deploy License Service and might be needed for support purposes.

Retrieving information about License Service health

API URL

<License Service URL>/health

API parameters

API description

This API call retrieves the following information:

Description
count The number of pods that are deployed on the cluster but have incomplete or improper product annotations. Improper annotations result in the license usage of a product not being measured. The annotations include the product metadata, such as the product ID and metric, and are implemented by the IBM team that develops the product to enable license usage measurements.
pods The list of pods that that have improper annotations.