Audit snapshot

Audit snapshot is a record of license usage in your environment over a period of time. The audit snapshot is a compressed .zip package that includes a complete set of audit documents that certify your cumulative license usage.

Audit snapshot for container licensing

Audit snapshot is needed for compliance and audit purposes.

For core license metrics, you are obliged to use License Service and periodically generate an audit snapshot to fulfill container licensing requirements. For more information about core license metrics, see Reported metrics.

You do not need to complete any manual actions to prepare the audit snapshot, you only need to generate it.

At this point, the audit snapshot is required to be generated at least once a quarter, and stored for 2 years in a location from which it could be retrieved and delivered to auditors.

Note: The requirements might change over time. You should always make sure to follow the latest requirements that are posted on Passport Advantage.

For more information, see the following resources:

Best practices

  • It is recommended to generate an audit snapshot report monthly as a precaution.
  • Before decommissioning a cluster, record the license usage of the products that are deployed on this cluster by generating an audit snapshot until the day of decommissioning.
  • Plan your storage to contain regular audit snapshots. The size of an audit snapshot .zip package might vary and depends on the number of products and the range of the reporting period. On average, the size of the package for a small environment is around 10 KB, and for medium and large environments - around 100 KB.

Generating an audit snapshot

Generating license usage Snapshot from all connected environments

To generate an audit snapshot that is based on the selected criteria, see Generating license usage Snapshot from all connected environments.

Generating an audit snapshot with License Service

To generate the audit snapshot for License Service, see Retrieving an audit snapshot.

You can generate the consolidate license usage data of the multiple License Service clusters in a single report with one of the following methods:

Generating an audit snapshot with License Service Reporter

To generate the audit snapshot for License Service Reporter, see Retrieving an audit snapshot.

Content of the audit snapshot

The audit snapshot is a compressed .zip package that includes a complete set of audit documents that certify your cumulative license usage.

An audit snapshot might consists of the following files:

Table 1. List of audit snapshot files
File name Content
checksum.txt The unique checksums that are a proof that the audit snapshot was not tampered with.
data_condition.txt Audit snapshot metadata that includes the following information:
  • License Service version that was used to generate the snapshot
  • Information about cluster or clusters
  • Metrics that are included in the snapshot
  • Time and date when the report is generated
  • Reporting period: Start Date and End Date
  • Information about optional capabilities, such as, hyperthreading, or any additional Custom Resource definitions that are delivered by the product
  • 4.2.7 Information about namespaces that are restricted or that could not be accessed by License Service over a period of time
data_condition.json Audit snapshot metadata that includes all information that are listed in data_condition.txt and additionally information about custom cluster names and IDs that you defined in .json format. In the future, data_condition.json will replace the data_condition.txt file.
products_<reported_period>_<cluster hostname>.csv The aggregated highest license usage that is registered for each product within the reported period.
products_daily_<reported_period>_<cluster hostname>.csv The aggregated highest license usage that is registered for each product within the reported period per day.
bundled_products_<reported_period>_<cluster hostname>.csv The aggregated highest license usage for each bundled product that is a part of the IBM Cloud Paks.
bundled_products_daily_<reported_period>_<cluster hostname>.csv The aggregated highest license usage that is registered for each bundled product within the reported period per day.
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.
services_<reported_period>.csv The aggregated highest license usage for each Cloud Pak for Data services that are a part of bundled products.
services_daily_<reported_period>.csv The aggregated highest license usage that is registered for each Cloud Pak for Data services within the reported period per day.

Understanding the audit snapshot

Table 2. List of columns in the audit snapshot .csv files
Column Description
cloudpakId The identification number of the IBM Cloud Pak® to which the program is bundled.
name The name of the product.
cloudpakMetricName The license metric unit that is used by the entire IBM Cloud Pak® to which the bundled product contributes.
cloudpakVersion Version of the IBM Cloud Pak® to which the program is bundled.
clusterId The identification of the cluster for which the highest license usage is calculated.
date The date for which the metricQuantity or metricMeasuredQuantity is calculated.
id The identifier of the product.
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.
metricMeasuredQuantity The highest number of license units that the bundled product used within the requested period.
metricName The license metric unit that is used by 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.
productName The name of the detected bundled product.
productId The identifier of the bundled product.
serviceName The name of the Cloud Pak for Data service that is a part of the bundled product.
serviceId The identifier of the Cloud Pak for Data service that is a part of the bundled product.
serviceMetricValue The license metric used by the Cloud Pak for Data service that is a part of the bundled product.

4.2.7 Viewing information about namespace scoping in audit snapshot

4.2.7 This feature is available from License Service version 4.2.7.

Information about namespaces that are restricted or that could not be accessed by License Service over a period of time is collected by License Service and included in the audit snapshot. You can view this information in data_condtion.json and data_condition.txt files.

License Service tracks the following data:

  • The namespaces that License Service has a restricted access to over a specific time period.
  • The namespaces that cannot be accessed by License Service for more than 6 hours even though they are in scope of License Service scanns. Problems with accessing the namespaces are caused by the lack of permissions to access these namespaces, for example when the Role or RoleBinding is missing.

Example:

License Service is resticted to scan only the ibm-licensing namespace between 01/06/2024 and 30/06/2024, and ns1 namespace between 15/06/2024 and 30/06/2024. Additionally, within the requested period, ns1 namespace is not available to License Service for at least 6 hours.

The following information is displayed in the data_condition.json file:

"limitedScopeOfNamespaces" : [ {
   "name" : "ibm-licensing",
   "dateFrom" : "2024-06-01",
   "dateTo" : "2024-06-30"
}, {
   "name" : "ns1",
   "dateFrom" : "2024-06-15",
   "dateTo" : "2024-06-30"
} ],
"errors" : {
   "namespacesAccessDenied" : [ {
      "name" : "ns1"
   } ]
}

The following information is displayed in the data_condition.txt file:

Limited scope of namespaces:
   Namespace, access from - access to:
      ibm-licensing	1 Jul 2024 - 30 Jul 2024
      ns1	15 Jul 2024 - 30 Jul 2024
Errors:
   Namespaces access denied:
      ns1

Note: The limitedScopeOfNamespaces and Limited scope of namespaces sections are included in the audit snapshot only if you enabled namespace scoping during the audited period. For more information, see Limiting visibility of namespaces in License Service.

Audit snapshot in a multicluster environment

Note: License Service Reporter is only available with IBM Cloud Paks.

If you deploy and configure License Service Reporter, you can retrieve the audit snapshot for multiple clusters directly from the Licensing dashboard, or using the License Service Reporter API.

Audit snapshots that can be created in Kubernetes clusters and IBM License Metric Tool (ILMT):

  • For all Kubernetes clusters: The Audit Snapshot that is created with action button of License Service Reporter, is the collection of Audit Snapshots identical in content. These Audit Snapshots are created on-demand in all Kubernetes clusters by License Services. Therefore, Audit Snapshot collection created in License Service Reporter can be used to facilitate preserving Snapshots from all Kubernetes.

  • In IBM License Metric Tool (ILMT): As per IBM compliance, an audit snapshot is not valid even if the audit snapshot package information is uploaded from ILMT to License Service Reporter and that information is used to create a file with format similar to Audit Snapshots files for containerized environments. For non-containerized environments measured by ILMT, only Audit Snapshot created in ILMT is legitimate for Compliance purpose.

Audit Snapshot created by ILMT contains additional information that is specific for non-containerized deployments.

In offline scenario, to import the services usage data version 4.2.0 or later into the License Service Reporter version 4.2.0, you must use audit snapshot upload API that contains the services information, by using PUT request on /snapshot endpoint. The PUT request must contain the zip file that is generated from the License Service 4.2.0 or later, that has Cloud pak for Data services. For more information, see Uploading audit snapshots from offline environments into License Service Reporter.

Note: Audit snapshots that are generated from License Service Reporter do not contain the unrecognized-apps-<reported_period>.csv file.

For more information about how to generate audit snapshot for multiple clusters, directly from the Licensing dashboard, see Generating audit snapshot from the Licensing dashboard. To learn how to retrieve the audit snapshot by using the dedicated API, see Retrieving an audit snapshot for multiple clusters.