Inventory from IBM License Service

IT Asset Management (Cloud)

IBM products (especially Cloud Paks) running in containers in a Kubernetes or OpenShift cluster are required to have their license consumption tracked by the IBM License Service, an application designed for this purpose. It monitors the Pods in the cluster, consuming a set of standardized annotations that must be applied to Pods running IBM products. It uses these annotations to determine what products are in use, and what licensing terms the products use. It exposes this information through a REST API.

Either of the Flexera Kubernetes Inventory Agent or the Lightweight Kubernetes Inventory Agent can connect with the IBM License Service through its REST API, so that you can import the correct data into IT Asset Management, and manage your license consumption through a "single pane of glass". The .ndi files for uploading inventory extracted from the IBM License Service follow this naming convention: k8s-ibm-licensing-shortClusterID-timestamp.ndi (with the placeholders updated with appropriate values). Example:

k8s-ibm-licensing-1656883d-20210726T010000.ndi

Note: The ability to connect with the IBM License Service is not enabled by default in either of the Kubernetes agents. It can be enabled by slightly different processes:

The Lightweight Kubernetes Inventory Agent requires that the --ibm-licensing flag is asserted (set to true) (see the example deployment.yaml file excerpt below)
The full Flexera Kubernetes Inventory Agent requires that the spec.ibmLicensing.enable attribute of the KRM spec must be true:
```
apiVersion: agents.flexera.com/v1
kind: KRM
...
spec:
  ibmLicensing:
    enable: true
```

Connecting to the REST API for IBM License Service

The two agents need to connect to the REST API endpoint as a URL:

The Lightweight Kubernetes Inventory Agent uses command-line flags to provide it with the correct URL for the API, and also with the token needed to authenticate with the API (see Options for the Lightweight Kubernetes Agent, with particular attention to --ibm-licensing [which must be set to enable the integration], --ibm-licensing-url, and --ibm-licensing-token). Alternatively, the values may be set in the deployment.yaml file:
```
apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    spec:
      containers:
      - name: agent
        args:
        ...
        - --ibm-licensing
        - --ibm-licensing-url
        - https://ibm-licensing-service-instance.ibm-common-services.svc:8080
        - --ibm-licensing-token
        - VoOMWJijBWuCxSxwgON11w7z 
```
The full Flexera Kubernetes Inventory Agent has the capacity to discover the API endpoint automatically, or it can be provided with the URL and token for the API in the same manner as the Lightweight Kubernetes Inventory Agent.

Data collection process

Either form of the Kubernetes agent collects product and bundled product information from the IBM License Service on a daily basis, maintaining a rolling window of 180 days of data. For example, if either agent is deployed on 2022-06-30, the process is as follows:

Load the client configuration.
Test the availability of the License Service API by issuing a request to its /version endpoint.
1. If the test fails, enter a retry loop with a 5 minute back-off until the test succeeds.
Determine the current day (2022-06-30) in the UTC time zone.
Determine the end of the period by subtracting one day from the current day (2022-06-29).
Determine the start of the period by subtracting 179 days from the end of the period (2021-12-31).
Request the product and bundled product data for each day from the start through the end of the period.
Write and/or upload an inventory file containing all 180 days of data.
Cache the final 7 days of the period.
Wait until 01:00:00 the next day (2022-07-01).
Request the product and bundled product data for the previous day (2022-06-30).
Slide the cache forward one day, storing the new data and deleting the old data.
Write and/or upload an inventory file containing the cached 7 days of data.
Start a 24-hour timer.
When the timer fires request the product and bundled product data for the previous day, slide the cache forward, produce an inventory.

If an agent (more typically, the Flexera Kubernetes Inventory Agent) is permitted to write to disk, it persists the cached data, which, if the agent is restarted, allows it to restore data from the cache, reducing the load on the IBM License Service. So for a restart, if there is data already in the cache, the agent validates whether the data covers the entire desired period:

If so, it resumes the above process from step 9
If not (for example, if the agent was disabled for several days), it starts from step 6 in the above process and requests data for the missing days.

The uploaded inventory format

Within the normal .ndi file format, the IBM License Service data is encapsulated in a ServiceProvider block. This block includes:

The /version and /health data (collected from the matching endpoints of the API)
The date range that the data covers
A series of zero or more Product and BundledProduct elements showing the related data recovered that day. These elements have added date and clusterid attributes, and otherwise mirror the IBM License Service data model (for details, see https://www.ibm.com/docs/en/cpfs?topic=service-license-swagger-api-schema).

The following example shows the structure of the ServiceProvider block within the .ndi file. The lines have been wrapped here for presentation, and the example uses dummy data:

<ServiceProvider Type="IBM License Service" LastInventoryResult="0" 
        LastInventoryError="" Name="d8259158-fdfe-4ba3-ae28-be62a51df7f9">
    <Property Name="Version" Value="1.6.0"/>
    <Property Name="BuildDate" Value="Mon Jul 12 16:45:52 UTC 2021"/>
    <Property Name="IncompleteAnnotationCount" Value="0"/>
    <Property Name="IncompleteAnnotationPods" Value=""/>
    <Property Name="StartDate" Value="2021-07-24"/>
    <Property Name="EndDate" Value="2021-07-25"/>
    <Product date="2021-07-24T00:00:00Z" id="eb9998dcc5d24e3eb5b6fb488f750fe2" 
        name="IBM Cloud Pak for Data" metricName="VIRTUAL_PROCESSOR_CORE" 
        metricQuantity="2" clusterid="d8259158-fdfe-4ba3-ae28-be62a51df7f9"/>
    <BundledProduct date="2021-07-24T00:00:00Z" 
        cloudpakId="eb9998dcc5d24e3eb5b6fb488f750fe2" 
        cloudpakName="IBM Cloud Pak for Data" cloudpakVersion="3.2.1" 
        productId="fb1b19783983ec76198729a9b945723" 
        productName="IBM Cloud Pak for Data Control Plane" 
        metricName="VIRTUAL_PROCESSOR_CORE" 
        cloudpakMetricName="VIRTUAL_PROCESSOR_CORE" metricConversion="1:1" 
        metricConvertedQuantity="2" metricMeasuredQuantity="2" 
        clusterid="d8259158-fdfe-4ba3-ae28-be62a51df7f9"/>
    <Product date="2021-07-25T00:00:00Z" id="eb9998dcc5d24e3eb5b6fb488f750fe2" 
        name="IBM Cloud Pak for Data" metricName="VIRTUAL_PROCESSOR_CORE" 
        metricQuantity="2" clusterid="d8259158-fdfe-4ba3-ae28-be62a51df7f9"/>
    <BundledProduct date="2021-07-25T00:00:00Z" 
        cloudpakId="eb9998dcc5d24e3eb5b6fb488f750fe2" 
        cloudpakName="IBM Cloud Pak for Data" cloudpakVersion="3.2.1" 
        productId="fb1b19783983ec76198729a9b945723" 
        productName="IBM Cloud Pak for Data Control Plane" 
        metricName="VIRTUAL_PROCESSOR_CORE" 
        cloudpakMetricName="VIRTUAL_PROCESSOR_CORE" metricConversion="1:1" 
        metricConvertedQuantity="2" metricMeasuredQuantity="2" 
        clusterid="d8259158-fdfe-4ba3-ae28-be62a51df7f9"/>
</ServiceProvider>

Field	Description
`BuildDate`	The date when the current version of the IBM License Service was compiled for release.
`IncompleteAnnotationCount`	The number of pods found with incomplete annotations about IBM Cloud Pak applications in use within the pod.
`Version`	The full version the IBM License Service
`IncompleteAnnotationPods`	A list of the pods where the required annotations are incomplete.
`StartDate`	If this attribute is empty, the API returned products and bundled products for the last 30 days as a default. When either `StartDate` or `EndDate` is specified in the query to the API, both must be supplied. The `StartDate` is the first day for which details are returned (that is, this value is inclusive).
`EndDate`	See `StartDate` for more details. The `EndDate` is the day after the last data was collected (that is, this value is exclusive). Therefore in the example above, data for just one day (2021-07-24) is returned.
`Product`	An element with the following attributes: `date` — The date when this particular product was found in the cluster `id` — The internal IBM ID for this application `name` — The published name of the application `metricName` — The license metric associated with this product (metrics may be used to filter the applications returned from the IBM License Service API) `metricQuantity` — The value associated with the metric (for example, if the `metricName` is `VIRTUAL_PROCESSOR_CORE`, a quantity of 2 means that the product in this row consumes 2 cores in the current cluster) `clusterid` — The identifier for the cluster where this product was found installed.
`BundledProduct`	An element with the following attributes: `date` — The date when this bundled product was found in the cluster `cloudpakId` — The internal IBM ID for the Cloud Pak containing this `BundledProduct` `cloudpakMetricName` — The metric associated with this bundle (metrics may be used to filter the data returned from the IBM License Service API) `cloudpakName` — The published name of the bundle `cloudpakVersion` — The version of the installed bundle `productId` — The internal IBM ID for this product within the Cloud Pak bundle `productName` — The name of this application within the bundle `metricName` — The metric associated with this product within the bundle `metricConversion` — a string representing the ratio to be applied when converting the `metricMeasuredQuantity` to the `metricConvertedQuantity` `metricMeasuredQuantity` — The value for the metric that the IBM License Service recovered for the installation `metricConvertedQuantity` — The result of applying the `metricConversion` ration to the `metricMeasuredQuantity` `clusterid` — The identifier for the cluster where this product was found installed.

IT Asset Management (Cloud)

Current