Configuring data sources

After deploying License Service Reporter, configure the License Service instance to enable data feeds from your clusters to License Service Reporter.

The support for this version of License Service Reporter is being sunset by the end of 2024. Install and configure the newest License Service Reporter version. For more information about the newest version, see License Service Reporter.

Complete the following actions to configure the following data sources to deliver licensing data to License Service Reporter.

Configuring the License Service instance for the cluster where License Service Reporter is deployed
Configuring the License Service instance for the remaining OpenShift clusters
Configuring the License Service instance for non-OpenShift clusters
Configuring SSL certificate validation when sending data to License Service Reporter
Delivering license usage of software installed in non-containerized environment from License Metric Tool to License Service Reporter
Uploading audit snapshots from offline environments into License Service Reporter
Verifying the License Service connection to the License Service Reporter

Configuring the License Service instance for the cluster where License Service Reporter is deployed

For the cluster where you deployed License Service Reporter, the License Service instance is automatically configured. Thanks to that, you do not need to perform any configuration and the license usage information are delivered to License Service Reporter.

Optionally, you can configure the License Service instance if you want to set the custom cluster name and ID. By default, the cluster name is set to the name of the first master node, and an ID is set to the kube-system namespace UID.

Important: Cluster ID and cluster name are included in the audit snapshot and must be clear for an auditor to identify the cluster.

Restriction: Cluster ID and cluster name cannot be changed after you configure the instance.

To set the custom cluster name and cluster ID, complete the following steps.

Log in to your OpenShift cluster console.
Go to Operators > Installed Operators.
Find and select the IBM Licensing Operator.
Go to the IBM License Service tab.
Edit the instance by expanding the menu at the end of the line and selecting Edit IBMLicensing.
In the YAML, add the following parameters and their values in the spec section under sender and click Save.
```
clusterID: <cluster_id>
clusterName: <your_cluster_name>
```

Where

<cluster_id> is a custom value expressed by a unique alphanumeric string that defines the cluster.
<cluster_name> is a custom, unique name that identifies the cluster on the License Service Reporter user interface.
(Optional) If you use HTTPS, you can enable certificate validation. For more information, see Configuring SSL certificate validation when sending data to License Service Reporter.

Configuring the License Service instance for the remaining OpenShift clusters

Configure the License Service instance to enable data feeds from for all remaining clusters to License Service Reporter for multi-cluster aggregations. Configure all clusters with software that should be included in the licensing calculations.

Copy the secret with a License Service Reporter token from the cluster where License Service Reporter is deployed.
1. Log in to the OpenShift console of the cluster where you deployed License Service Reporter.
2. Go to Workloads > Secrets and select the project where License Service Reporter is installed.
3. Find and select ibm-licensing-reporter-token.
4. Go to the YAML tab and copy the entire YAML with the secret.
Create the secret with a token on the cluster from which you want to retrieve licensing data.
1. Log in to the OpenShift cluster console.
2. Go to Workloads > Secrets.
3. Expand the Create menu and select From YAML.
4. Paste the contents of the YAML that you copied in step 1d into the editor, delete ownerReferences section, set the namespace to the License Service namespace and click Create.
Modify the License Service instance to enable data feeds from the cluster to License Service Reporter.
1. Log in to your OpenShift cluster console.
2. Go to Operators > Installed Operators.
3. Find and select the IBM Licensing Operator.
4. Go to the IBM License Service tab.
5. Edit the instance by expanding the menu at the end of the line and selecting Edit IBMLicensing.
6. Add the following content to the spec section in the YAML and click Save.
```
sender:
  reporterSecretToken: ibm-licensing-reporter-token
  reporterURL: <reporter_url>
  clusterID: <cluster_id>
  clusterName: <your_cluster_name>
```
  Where
  - <reporter_url> is a URL of the License Service Reporter that you deployed. To get the URL, complete the following steps:
    1. Log in to the OpenShift console of the cluster where you deployed License Service Reporter.
    2. Go to Networking > Routes and select the ibm-common-services project.
    3. Find ibm-license-service-reporter and copy the link that is provided under Location.
    Note: From IBM Cloud Pak foundational services version 3.6.x, the clusterID and clusterName parameters are optional. If you do not need to customize the ID and name of the cluster, remove the parameter from the sender section. Cluster ID and cluster name are included in the audit snapshot and must be clear for an auditor to identify the cluster.
    
    Restriction: Cluster ID and cluster name cannot be changed after you configure the instance.
    - <cluster_id> - By default, the cluster ID is set to the kube-system namespace UID. To set a custom ID, include this parameter in the YAML and provide a custom value expressed by a unique alphanumeric string that defines the cluster.
    - <cluster_name> - By default, the cluster name is set to the name of the first master node. To set a custom cluster name, include the parameter in the YAML and provide a custom, unique name that identifies the cluster on the License Service Reporter user interface.
(Optional) If you use HTTPS, you can enable certificate validation. For more information, see Configuring SSL certificate validation when sending data to License Service Reporter.

Configuring the License Service instance for non-OpenShift clusters

You can configure License Service instance for non-OpenShift Kubernetes clusters to deliver data to License Reporter under following circumstances:

In addition to IBM Cloud Paks, you have IBM stand-alone containerized software that is deployed on non-OpenShift Kubernetes clusters.
Your IBM stand-alone containerized software is enabled for reporting and has integrated License Service.
You want to track license usage of your IBM Cloud Paks and IBM stand-alone containerized software on one report.

To configure the License Service instance for non-OpenShift Kubernetes clusters, complete the following steps.

Copy the secret with the License Service Reporter token from the cluster where License Service Reporter is deployed.
1. Log in to the cluster where you deployed License Service Reporter and run the following command.
```
kubectl get secret ibm-licensing-reporter-token -o yaml -n ibm-common-services > reporter-token.yml
```
2. Open reporter-token.yml in the text editor and make the following changes:
  - Remove the ownerReferences section.
  - Change the value of the namespace parameter in the metadata section to the namespace in which License Service is installed.
Create the secret with a token on the cluster with License Service. Log in to the cluster and run the following command to create a secret.
```
kubectl apply -f reporter-token.yml -n <enter the License Service namespace>
```
Modify the License Service instance to enable data feeds from the cluster to License Service Reporter.
1. Run the following command.
```
kubectl edit IBMLicensing -o yaml -n ibm-common-services
```
2. Modify the .yaml, add the following content under 'spec' section and save the file.
```
sender:
  reporterSecretToken: ibm-licensing-reporter-token
  reporterURL: <reporter_url>
  clusterID: <cluster_id>
  clusterName: <cluster_name>
```
  Where
  - <reporter_url> is a URL of the License Service Reporter that you deployed. To get the URL, complete the following steps:
    1. Log in to the OpenShift console of the cluster where you deployed License Service Reporter.
    2. Go to Networking > Routes and select the ibm-common-services project.
    3. Find ibm-license-service-reporter and copy the link that is provided under Location.
      
      Note: You can also use the following command: kubectl get routes -n ibm-common-services | grep ibm-license-service-reporter | awk '{print $2}'
    Note: From IBM Cloud Pak foundational services version 3.6.x, the clusterID and clusterName parameters are optional. If you do not need to customize the ID and name of the cluster, remove the parameter from the sender section. Cluster ID and cluster name are included in the audit snapshot and must be clear for an auditor to identify the cluster.
    
    Restriction: Cluster ID and cluster name cannot be changed after you configure the instance.
    - <cluster_id> is an optional parameter. By default, the cluster ID is set to the kube-system namespace UID. To set a custom ID, include this parameter in the YAML and provide a custom value expressed by a unique alphanumeric string that defines the cluster.
    - <cluster_name> is an optional parameter. By default, the cluster name is set to the name of the first master node. To set a custom cluster name, include the parameter in the YAML and provide a custom, unique name that identifies the cluster on the License Service Reporter user interface.
(Optional) If you use HTTPS, you can enable certificate validation. For more information, see Configuring SSL certificate validation when sending data to License Service Reporter.

Configuring SSL certificate validation when sending data to License Service Reporter

Learn how to configure SSL certificate validation for secure communication between License Service and License Service Reporter. Secure Sockets Layer (SSL) certificates ensure encrypted communication and authenticate the identity of the services involved.

Important: By default, License Service trusts the certificates that are issued by all certification authorities (CAs) which are bundled with Java Runtime Environment.

Configuring a trusted CA certificate to enable certificate validation

If you enable certificate validation when sending data from License Service to License Service Reporter that is deployed in the same namespace, which is a default, License Service automatically uses the internal certificate that is issued by the OpenShift certificate manager. This streamlines the setup process and eliminates the need for further configuration. No action is required.
If License Service Reporter uses a certificate that is issued by a trusted CA, complete the following steps to modify the License Service instance and enable certificate validation:
Log in to your OpenShift cluster console.
Go to Operators > Installed Operators.
Find and select the IBM Licensing Operator.
Go to the IBM License Service tab.
Edit the instance by expanding the menu at the end of the line and selecting Edit IBMLicensing.
Add the following content to the spec.sender section in the YAML and click Save.
```
spec:
sender:
   validateReporterCerts: True
```
Verify whether the configuration is successful by completing the following step: Verifying the successful configuration of certificate validation.

Enabling SSL certificate validation for License Service Reporter

Complete the following steps to enable certificate validation:

Copy the secret with the License Service Reporter certificate from the cluster where License Service Reporter is deployed.
1. Log in to the OpenShift console of the cluster where you deployed License Service Reporter.
2. Go to Workloads > Secrets and select the project where License Service Reporter is installed.
3. Find and select the secret that contains the License Service Reporter route certificate. By default, License Service Reporter uses the ibm-license-reporter-cert certificate.
  
  Important: If you use a custom certificate (Configuring a custom certificate), find and select the ibm-licensing-reporter-certs secret.
4. Go to the YAML tab and copy the entire YAML with the secret.
Create the secret with a certificate on the cluster from which you want to send the license usage data to License Service Reporter.
1. Log in to the OpenShift cluster console.
2. Go to Workloads > Secrets.
3. Expand the Create menu and select From YAML.
4. Paste the contents of the YAML that you copied in step 1d into the editor. Delete the ownerReferences section and set the namespace to the License Service namespace.
5. Click Create.
Modify the License Service instance to enable certificate validation when sending data to License Service Reporter.
1. Log in to your OpenShift cluster console.
2. Go to Operators > Installed Operators.
3. Find and select the IBM Licensing Operator.
4. Go to the IBM License Service tab.
5. Edit the instance by expanding the menu at the end of the line and selecting Edit IBMLicensing.
6. Add the following content to the spec.sender section in the YAML and click Save:
```
spec:
sender:
   validateReporterCerts: True
   reporterCertsSecretName: ibm-license-service-reporter-cert      # <-- you need to provide this value when the License Service Reporter certificate is not trusted by the default CA that is bundled with Java
```
Where

ibm-license-service-reporter-cert is the name of the secret that you create in step 2 that contains the certificate. Note that the certificate must be correctly configured and the Subject Alternative Name (SAN) must match the URL that is specified for License Service Reporter in the hubURL field within the IBMLicensing instance. This is essential for establishing a secure SSL connection.

Note: The secret that you specify as reporterCertsSecretName must contain a tls.crt key with a valid License Service Reporter certificate.

Verifying the successful configuration of certificate validation

To verify that certificate validation is successful, check License Service logs. After you successfully complete certificate validation, License Service logs contain the following information:

   Importing license-service-reporter certificate into truststore to establish secure connection when sending data...
   Certificate was added to keystore
   ...
   2024-05-21 13:41:33.920 [main] INFO Enabling SSL certificate validation when sending data to the License Service Reporter.
   ...
   2024-05-21 13:47:41.712 [scheduling-1] INFO License Service Reporter URL = <lsr-url>, cluster name = ..., cluster ID = ...
   2024-05-21 13:47:42.319 [scheduling-1] INFO Connected to License Service Reporter 4.2.3
   ...
   2024-05-21 13:47:43.404 [scheduling-1] INFO Sending data to <lsr-url>/snapshot?token=*****
   2024-05-21 13:47:43.805 [scheduling-1] INFO Data successfully sent to the license service reporter: <lsr-url>/snapshot?token=*****

Note: After License Service restarts, the logs return this information after a few minutes because of the delay of the initial data upload from License Service to License Service Reporter.

Delivering license usage of software installed in non-containerized environment from License Metric Tool to License Service Reporter

For more information, see Delivering license usage of IBM Cloud Pak solutions and stand-alone containerized software installed in non-containerized environment from License Metric Tool to License Service Reporter Opens in a new tab .

Uploading audit snapshots from offline environments into License Service Reporter

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

Prerequisites:

License Service Reporter in version 1.18 or higher included in foundational services 3.21 and newer
Audit snapshot must be generated by using License Service version 1.18 or higher included in foundational services 3.21 and newer

Note: If upload fails with error 422, make sure that the audit snapshot is generated from the correct License Service version, and that you use License Service Reporter that supports the upload.

If you use License Service to track license usage in offline environments, you can upload audit snapshot that is generated for offline environments into License Service Reporter. Thanks to the upload, the additional measurements are included in the collective license usage statistics on Licensing dashboard and in License Service Reporter reports.

Procedure

Complete the following actions to upload audit snapshots from offline environments into License Service Reporter.

Generate an audit snapshot from the offline environment. For more information and instructions, see Retrieving an audit snapshot.
Upload the generated audit snapshot .zip package into License Service Reporter with the following CURL query:
```
curl -k -X PUT -F 'file=@<audit_snapshot_file_name.zip>' "<License Service Reporter URL>/snapshot?token=<token>"
```
where:

<audit_snapshot_file_name.zip> is the name of your audit snapshot package

<token> is your authentication token for connecting to License Service Reporter. For more information, see Obtaining and updating an API token.

<License Service Reporter URL> is the URL of your License Service Reporter instance. For more information, see Obtaining License Service Reporter URL.

For more information about this API, see License Service Reporter Swagger API schema.

Note: The audit snapshot can cover data from any period, however the package cannot exceed 1 MB. If your package contains large amounts of data, upload takes long and you are notified that the connection being prematurely closed, change your load balancer settings.

During the upload, License Service Reporter verifies the audit snapshot checksums and the signature to ensure data authenticity.

Verification

If upload completes successfully, you get the HTTP 200 response with the following message: Audit snapshot file upload finished successfully.

Changing load balancer settings

If your package contains large amounts of data, you might need to increase load balancer timeout to receive correct response from the server. Otherwise, upload times out with an error message that the client prematurely closed the connection while reading the response header. The timeout occurs when the process does not finish within the timeout period that is currently set for load balancer.

Note: If load balancer closes connection with License Service Reporter due to exceeded timeout, it does not always mean that the upload failed as the process continues anyway. Check logs to verify whether the upload was successful or not.

For example, if you have the HAProxy load balancer, complete the following steps to change the client and server timeout value:

On the load balancer node, edit the /etc/haproxy/haproxy.cfg file. In the defaults section, change the values for timeout client and timeout server from 1m to 5m.
Run the following command to restart HAProxy: systemctl restart haproxy.

Verifying the License Service connection to the License Service Reporter

Note: Data sent by License Service (License Service Reporter data source) will be visible in License Service Reporter after around an hour of configuring the data sources.

After you deploy the License Service instance successfully, you can verify whether the License Service has connected to License Service Reporter and sent data. After around 10 minutes of deploying License Services instance, check the License Service logs and look for the following similar entries:

2022-09-14 12:17:46.840 [scheduling-1] INFO  Starting sender task
2022-09-14 12:17:46.852 [scheduling-1] INFO  License Service Reporter URL = https://console-openshift-console.apps.ls-js.cp.fyre.ibm.com, cluster name = my_cluster, cluster ID = my_cluster_id
2022-09-14 12:17:46.934 [scheduling-1] INFO  Connected to License Service Reporter 1.18.0
2022-09-14 12:17:46.968 [scheduling-1] INFO  Sending data from 2022-09-14 to 2022-09-14
2022-09-14 12:17:47.478 [scheduling-1] INFO  Sending data to https://console-openshift-console.apps.ls-js.cp.fyre.ibm.com/snapshot?token=*****
2022-09-14 12:17:47.640 [scheduling-1] INFO  Saving last hub synchronization date = 2022-09-14
2022-09-14 12:17:47.662 [scheduling-1] INFO  Sender task finished

If you find these entries in the License Service logs, it confirms that the License Service has connected to the License Service Reporter successfully. If no data is visible in License Service Reporter after configuring data sources, see Troubleshooting License Service Reporter