SPK Licensing¶

Overview¶

The Service Proxy for Kubernetes (SPK) software requires a valid SPK license to begin processing 5G application traffic using SPK CRs. Once the SPK CWC obtains a valid license, it begins collecting and reporting monthly SPK software telemetry statistics for the cluster. SPK uses F5’s flexible consumption software licensing model, billing only for the SPK features used.

_images/spk_info.png Note: SPK Licensing applies to the cluster level, and is performed prior to installing the SPK Controller instances.

This document guides you through the activating the SPK software license.

Licensing stages¶

The CWC’s Common Product Component and Libraries (CPCL) module operates in disconnected mode; having no direct access to the internet. Uploading the license reports, and obtaining signed license acknowledgements from the F5 licensing server must occur at some point between the cluster and the internet. In this document, the Postman platform is used for licensing. Once the CWC and Controllers are installed, the licensing and entitlement events occur as follows:

Obtain the JSON Web Token (JWT).
Check CWC licensing status.
Download the CWC cluster report.
Send the report to the F5 licensing server.
Send the signed acknowledgement to CWC.

Telemetry reports¶

Once the cluster is successfully licensed, the CWC enters a Telemetry In Progress state, calculating the software usage statistics for the cluster. At the end of each month, the CWC generates a telemetry report which should be downloaded, sent to the F5 licensing server for acknowledgement, and the signed acknowledgement should then be sent back to the CWC. If a telemetry report is not signed by the F5 licensing server at the end of the month, it will be consolidated with the next telemtry report, and a consolidated report will then be available to download and sign.

Example of the Telemetry In Progress and report EndDate:

"TelemetryStatus": {
    "NextReport": {
        "StartDate": "2022-04-26 17:59:35.306014074",
        "EndDate": "2022-04-30 17:59:35",
        "State": "Telemetry In Progress"
    }
}

License expiration¶

The cluster license requires renewal after the LicenseExpiryDate has passed. It is important to note that SPK does not stop processing application traffic after this time, but will begin logging messages indicating the cluster must be relicensed.

Example of the LicenseExpiryDate:

"LicenseDetails": {
    "DigitalAssetID": "5ec9234e-8df3-4d90-9536-45142b87049f",
    "EntitlementType": "paid",
    "LicenseExpiryDate": "2022-11-17T00:00:00Z",
    "LicenseExpiryInDays": "204"
}

Licensing APIs¶

The CWC licensing APIs listed below can be used to perform licensing tasks programmatically, or with API platforms other than Postman. Refer to the Gather API info section to obtain the CWC’s SSL/TLS certificates and hostname. To use the Postman API platform, refer to the Procedures section of this document.

_images/spk_warn.png Important: The URL to contact the CWC Pod includes the Project name. In the examples below the CWC is in the spk-telemetry Project.

License status¶

Returns the current CWC licensing status. This API should be used both for licensing the cluster and checking the telemetry report status. The LicenseStatus should indicate Config Report Ready to Download prior to downloading a license report.

https://f5-spk-cwc.spk-telemetry:30881/status

Example:

curl --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem \
https://f5-spk-cwc.spk-telemetry:30881/status

License report¶

Downloads the CWC license report for the cluster. The license report will be sent to the F5 licensing server for acknowledgement.

https://f5-spk-cwc.spk-telemetry:30881/report

Example:

curl --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem https://f5-spk-cwc.spk-telemetry:30881/report

Send report¶

Sends the license report to Telemetry server for acknowledgement. Send the full report, including the {} curly brackets.

Note: The DigitalAssetID is obtained from the License status, and the JWT from your MyF5 account.

https://product.apis.f5.com/ee/v1/entitlements/telemetry

Example:

curl --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem \
https://product.apis.f5.com/ee/v1/entitlements/telemetry \
-H "Content-Type: application/json" -H "F5-DigitalAssetId: <DigitalAssetID>" \
-H "User-Agent: SPK" -H "Authorization: Bearer <JWT Object>" -d '{"report":"eyJhbG7ImRvYZW50"}'

Send manifest¶

Sends the acknowledged manifest to CWC. Send only the manifest data, no curly brackets {}, or “ quotations.

https://f5-spk-cwc.spk-telemetry:30881/receipt

Example:

curl --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem \
https://f5-spk-cwc.spk-telemetry:30881/receipt -d eyJhbGciOiJSUzUxMiIs

Requirements¶

Ensure you have:

A workstation with Postman installed, and internet access.
Installed the SPK software.
Installed the SPK CWC.
Obtained the JWT for this cluster from your MyF5 account.

Procedures¶

Gather API info¶

Licensing the SPK software requires querying the CWC REST API to determine the cluster’s licensing status, and uploading a valid license. To authenticate the CWC REST API, the SSL/TLS certificates and the IP address of the API interface must first be obtained. Use the steps below to obtain the API information.

Create a new directory for the CWC REST API certificates:
```
mkdir cwc_api
```

Copy each of the certificates into the new directory:

cp api-server-secrets/ssl/client/certs/client_certificate.pem cwc_api

cp api-server-secrets/ssl/ca/certs/ca_certificate.pem cwc_api

cp api-server-secrets/ssl/client/secrets/client_key.pem cwc_api

Obtain the name of the CWC Pod in the cluster:

In this example, the CWC is in the spk-telemetry Project.
```
oc get pods -n spk-telemetry | grep f5-spk-cwc
```
In this example, the CWC Pod is named f5-spk-cwc-86d89c4548-fmwpl.
```
f5-spk-cwc-86d89c4548-fmwpl   2/2     Running
```
Obtain the IP address of the node the CWC Pod is scheduled on:

In this example, the CWC is in the spk-telemetry Project.
```
oc describe pod f5-spk-cwc-86d89c4548-fmwpl -n spk-telemetry | grep Node:
```
In this example, the CWC Pod is running on worker-0.ocp.f5.com with IP address 10.144.175.18.
```
Node:         worker-0.ocp.f5.com/10.144.175.18
```
Edit the hosts file on your system, or setup DNS resolution mapping the node IP address to the CWC’s hostname:

Important: The CWC hostname is required for SSL/TLS certiicate validation.
```
10.144.175.18 f5-spk-cwc.<project>
```
In this example, the CWC is in the spk-telemetry Project.
```
10.144.175.18 f5-spk-cwc.spk-telemetry
```

Configure Postman¶

Use the following steps below configure Postman to query the CWC REST API, and the remote F5 Licensing server.

Import the Collection:

A. Download the SPK License Collection.

B. Navigate to Workspaces and select + Create Workspace.

C. Enter a unique Name, select the appropriate Visibility setting, and click Create workspace.

D. Select the Collections tab on the left, and then click Import to the right of the Workspace name.

E. Select Upload Files in the middle of the page, and navigate to the file named spk-license-collection.json.

F. Select Open, and then click Import import on the bottom right.
Import the Environment:

A. Download the SPK License Environment.

B. Line 12 of the file references the spk-telemetry Project. If you’re using a different Project, edit the file and change the entry.

C. Select the Environment tab on the left, and then click Import to the right of the Workspace name.

D. Select Upload Files in the middle of the page, and navigate to the file named spk-license-environment.json.

E. Select Open, and then click Import on the bottom right.
Reference the CWC SSL/TLS Certificates:

A. Select Settings (gear icon) on the right, and then select Settings at the top of the menu.

B. Select the Certificates tab near the top/middle of the page.

C. Ensure CA Certificates is ON, and next to PEM file click Select File.

D. Navigate to the cwc_api folder created earlier, select ca_certificate.pem, and then Open.

E. Select Add Certificate in the section just below.

F. Change both the Host domain and port settings to * (asterisk).

G. Next to CRT file, click Select File, select client_certificate.pem, and then Open.

H. Next to KEY file, click Select File, select client_key.pem, and then Open.

I. Click the Add button, and then the X to the top right.

License the Software¶

Use the following steps to license the SPK software.

Click Collections on the left, and expand SPK-License to see the licensing APIs..
Select the No Environment drop-down on the top/right, and ensure the CWC API Environment is selected.
Under SPK-License on the left, select GET License Status, and click Send.

The response should indicate Config Report Ready to Download:

{
    "InitialRegistrationStatus":{
        "ClusterDetails":{
            "Name":"SPK Cluster"
        },
        "LicenseDetails":{
            "DigitalAssetID":"9b564406-9706-4cea-a82b-7ce3f425f7de",
            "EntitlementType":"paid"},
            "LicenseStatus":{"State":"Config Report Ready to Download"}
        },
        "TelemetryStatus":{
        }
    }
} 

Copy and save the DigitalAssetID from the response. In this previous step, the DigitalAssetID is 9b564406-9706-4cea-a82b-7ce3f425f7de.
Select GET License Report, and click Send.
Copy and save the entire report from the response, including the curly brackets {}:

The example output has been shortened for readability.
```
 {"report":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImRvY3VtZW50"}
```
Select POST Report to Telemetry Server.
Select Body in the request section, find Paste the full report here, and paste the report from step 6.
Select the Authorization tab, next to Token find Paste the JWT here, and paste the JWT object from step 1.
Select the Headers tab, in the middle of the page.
In the the F5-DigitalAssetId row, find Paste the Digital Asset ID here, and paste the DigitalAssetID from step 3.
Click Send.
The reponse should indicate 200 OK and contain a large license manifest.
Select Body in the reponse section, copy and save only the the manifest data. No “ quotation characters.

The reponse should appear similar to the example below.
```
{
    "manifest": "eyJhbGciOiJSUzUxMiIsImtpZCI6InYxIiwiamt1Ijoia"
}
```
Using the example above, the manifest data will appear as:
```
eyJhbGciOiJSUzUxMiIsImtpZCI6InYxIiwiamt1Ijoia
```
Select POST License Manifest to CWC, and then select Body.
Paste the manifest data into the request Body and click Send.
You should receive a 200 OK response from the CWC, with no data or errors.

Select GET status and click Send. The LicenseStatus should indicate Verification Complete:

Note: The State: Telemetry In Progress indicates CWC is gathering montly telemetry statistics.

{
    "Status": {
        "ClusterDetails": {
            "Name": "SPK Cluster"
        },
        "LicenseDetails": {
            "DigitalAssetID": "fd399be0-9e50-4d40-8c03-18f7782a7c8e",
            "EntitlementType": "paid",
            "LicenseExpiryDate": "2023-06-19T00:02:18Z",
            "LicenseExpiryInDays": "361"
        },
        "LicenseStatus": {
            "State": "Verification Complete"
        }
    },
    "TelemetryStatus": {
        "NextReport": {
            "StartDate": "2022-06-22 19:52:03.618492964 +0000 UTC m=+90678.992443204",
            "EndDate": "2022-06-30 19:52:03 +0000 UTC",
            "State": "Telemetry In Progress"
        }
    }
}

In the previous response, LicenseExpiryDate designates when the cluster license must be renewed, and EndDate designates when the next telemetry (software usage) report should be sent to the F5 licensing server.

Important: SPK does not stop processing application traffic after the LicenseExpiryDate, but will begin logging messages indicating the cluster must be relicensed.

Next step¶

Continue to the SPK Controller installation guide.

Feedback¶

Provide feedback to improve this document by emailing spkdocs@f5.com.

Previous Next