Set-up SPK License

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 CRD usage summary telemetry statistics for the cluster. SPK uses F5’s flexible consumption software licensing model, billing only for the SPK features used.

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 Modes

As described in the SPK CWC guide, the Common Product Component and Libraries (CPCL) module supports two licensing modes:

  • disconnected - When the CWC does not have access to the internet, each licensing task must be performed manually. Use this document to perform the required licensing steps.

  • connected - When the CWC has access the internet, it can automatically perform each of the licensing tasks. Use this document to obtain the license status.

This document guides you through the process of activating and managing the SPK software license:

Activate SPK License

Prerequisites

Ensure you have:

Collect REST 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.

  1. Create a new directory for the CWC REST API certificates:

    mkdir cwc_api

  2. 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

  3. 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

  4. 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

  5. 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

License the cluster in Connected Mode

Once you choose to install SPK configured as “connected mode”, the clusters will be licensed in Connected Mode without any additional steps. To verify the cluster’s license, use the following command:

To verify the cluster’s license, use the following command:

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

The command output indicates the EntitlementType is paid and the LicenseExpiryDate is 2024-03-05. The LicenseExpiryInDays shows expiration occurs in 362 days.

{
"Status": {
   "ClusterDetails": {
      "Name": "My Cluster"
   },
   "LicenseDetails": {
      "DigitalAssetID": "5c367e83-b6cf-4a28-9899-8a3a98b65460",
      "EntitlementType": "eval",
      "LicenseExpiryDate": "2025-02-21T20:01:18Z",
      "LicenseExpiryInDays": "0"
   },
   "LicenseStatus": {
      "State": "Verification Complete"
   }
},
"TelemetryStatus": {
   "NextReport": {
      "StartDate": "2025-02-22 19:55:43 +0000 UTC",
      "EndDate": "2025-02-28 19:55:43 +0000 UTC",
      "State": "Telemetry In Progress"
   }
}
}

License the cluster in Disconnected Mode

When the CPCL module of CWC operates in disconnected mode; having no direct access to the internet, uploading license reports and obtaining signed license acknowledgements from the F5 licensing server must be performed manually. Once the CWC and Controllers are installed, the licensing and entitlement events occur as follows:

  1. Obtain the JSON Web Token (JWT).

  2. Check CWC licensing status.

  3. Download the CWC cluster report.

  4. Send the report to the F5 licensing server.

  5. Send the signed acknowledgement to CWC.

Use the following steps to license the cluster in disconnected mode:

  1. Verify the current LicenseStatus of the CWC Pod, and obtain the DigitalAssetID used to license the cluster:

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

    In this example, LicenseStatus shows Config Report Ready to Download, and the DigitalAssetID is b9270cae-5980-4c0e-bb44-f1948ff4b235.

    {"InitialRegistrationStatus":{"ClusterDetails":{"Name":"SPK Cluster"},
"LicenseDetails":{"DigitalAssetID":"b9270cae-5980-4c0e-bb44-f1948ff4b235",
"EntitlementType":"paid"},"LicenseStatus":{"State":"Config Report Ready to Download"}},"TelemetryStatus":{}

  2. Download the Config Report and copy/paste it into a text file:

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

    The command output should appear similar to this truncated example:

    {"report": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImRv"}

  3. Send the Config Report, including the { and } characters, to the F5 licensing server along with the DigitalAssetID and your unique JWT:

    Important: The returned manifest is quite large, the command below captures the output to a file named manifest.txt.

    curl -X POST https://product.apis.f5.com/ee/v1/entitlements/telemetry \
-H "Content-Type: application/json" \
-H "F5-DigitalAssetId: b9270cae-5980-4c0e-bb44-f1948ff4b235" \
-H "User-Agent: SPK" \
-H "Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6" \
-d '{"report": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImRv"}'
-o 'manifest.txt'

  4. View the contents of the returned manifest.txt file:

    cat manifest.txt

    The command output should resemble this truncated example:

    {"manifest":"eyJhbGciOiJSUzUxMiIsImtpZCI6InYxIiwiamt1"}

  5. Send only the Manifest string after the : character. Do not include the { and } or “ characters:

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

  6. Verify the cluster license status:

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

    The command output indicates the EntitlementType is paid and the LicenseExpiryDate is 2024-03-05. The LicenseExpiryInDays shows expiration occurs in 362 days.

    {"Status":{"ClusterDetails":{"Name":"SPK Cluster"},"LicenseDetails":{"DigitalAssetID":"f06ae970-5b16-4fc1-894e-ce419b928cc9",
"EntitlementType":"paid","LicenseExpiryDate":"2024-03-05T00:01:13Z","LicenseExpiryInDays":"362"},
"LicenseStatus":{"State":"Verification Complete"}},"TelemetryStatus": {"NextReport":
{"StartDate":"2023-03-08 00:03:20.585513148 UTC m=+3093.980461514","EndDate":"2023-03-31 00:03:20 UTC",
"State":"Telemetry In Progress"}

Switching License

Notes:

  • Switching license is allowed from eval to paid and from paid to paid, but not from eval to eval.

  • Switching license is not allowed when current telemetry report is in any of the below states. User is expected to submit these reports prior to switching the license.

    • Config report ready to download.

    • Config report downloaded.

Use the following steps to switch license:

  1. Verify the current license status.

    It should be Verification Complete.

  2. Verify the status of Telemetry.

    It should be Telemetry in Progress.

  3. Switch license by calling /reactivate API.

    Example:

    curl --k --cert-type PEM --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem \
https://f5-spk-cwc.spk-telemetry:30881/reactivate -d <JWT object>

  4. Download Update report. This update report is the aggregated telemetry report from the start of month till the switch license is triggered.

    Example:

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

  5. Send Update Report to Telemetry server.

    Example:

    curl -X POST 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 '<Full_Report>'

  6. View the contents of manifest file.

  7. Send manifest string to CWC using /receipt API.

  8. Verify status again.

Renew Your License

The cluster license must be renewed promptly once the LicenseExpiryDate has been reached. Once a user contacts the F5 sales team to renew their license, the F5 Licensing Server (TEEMs) is updated with the subscription information as agreed. After the LicenseExpiryDate, the F5 Licensing Server will then send the updated subscription details to the clusters upon receiving the telemetry report.

Note: SPK continues to process application traffic without interruption after the LicenseExpiryDate passes and logs a message in the CWC pod indicating that the license has expired.

When a user renews their subscription, the F5 Licensing Server updates the entitlement expiry date.

Connected Mode:

When a user renews their subscription in Connected Mode, after license expiry, and when a telemetry report is sent to F5 Licensing Server, the CPCL directly interacts with the F5 Licensing Server and updates the product with renewed license details.

Disconnected Mode

In Disconnected Mode after expiry, the user should generate and send license telemetry report using the licensing APIs as described below:

  1. Download the CWC license report for the cluster using the ‌CWC licensing API. The license report will be sent to the F5 Licensing Server for acknowledgment.

    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

  2. Send the downloaded license report to Telemetry Server for acknowledgment. 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 Post:

    curl -X POST 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 '<Full_Report>'

  3. Send 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

    When the manifest file is submitted, CWC updates the latest expiry dates received from the F5 Licensing Server and generates a log message to record the event.

  4. Verify license status, see License status.

Telemetry reports

Once the cluster is successfully licensed, the CWC enters a Telemetry In Progress state, calculating the software CRD usage summary telemetry 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 telemetry 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": "2023-01-06 13:59:35.306014074 +0000 UTC m=+1346.343452122",
        "EndDate": "2023-01-31 13:59:35",
        "State": "Telemetry In Progress"
    }
}

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 license the cluster, refer to the Procedures section of this document.

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 -X POST 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 '<Full_Report>'

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

Reactivate/Switch License

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

Can either switch a license from evaluation to paid license using the new JWT, or resubmit a JWT that was not properly submitted causing a CWC failure.

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

Example:

curl --k --cert-type PEM --cert client_certificate.pem --key client_key.pem --cacert ca_certificate.pem \
https://f5-spk-cwc.spk-telemetry:30881/reactivate -d <JWT object>

Next step

Continue to the SPK Controller installation guide.

Feedback

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