License Assign/Revoke API

Overview

This task API simplifies assigning and revoking licenses to/from BIG-IP devices. The API provides a simplified interface for the various pool license types supported by BIG-IQ. The API does not require knowing the deviceReference of managed devices nor the reference of the license to be assigned/revoked. All pool license types except Fraud Protection Service (FPS) licenses are supported. This includes individual BIG-IP VE licenses managed in a RegKey Pool on BIG-IQ.

Prerequisites

Make certain that the following prerequisites have been met.

  • The BIG-IQ Centralized Management device is operational, has completed the setup wizard, and completed any other needed configuration.
  • The BIG-IQ license allows licensing managed or unmanaged BIG-IP devices.
  • You have one or more pool licenses activated and ready to be assigned to BIG-IP devices. This can include standalone BIG-IP VE licenses in a RegKey Pool.
  • You have one of the following roles: administrator, device manager, or license manager.

Note: When you perform these tasks using the example code provided, review the listed IP addresses and change them as appropriate for your environment. For example, if you are not running the script directly on the BIG-IQ device, change localhost to be the IP address of the BIG-IQ Centralized Management device.

Supported license types

All but FPS licenses are supported. This includes:

  • purchased pool licenses
  • utility licenses
  • volume licenses
  • individual BIG-IP VE licenses managed by BIG-IQ in a RegKey Pool

Supported device types

This API supports licensing three types of BIG-IP devices:

  • Managed devices are devices added to BIG-IQ’s device inventory. BIG-IQ supports operations above and beyond licensing for these devices (e.g. backups, upgrades, configuration management, etc.).
  • Unmanaged devices are devices that BIG-IQ communicates with solely for licensing purposes. Because these devices are not actively managed via device trust, user credentials must be provided when performing licensing operations.
  • Unreachable devices (sometimes referred to as disconnected devices) are devices that BIG-IQ can generate licenses for without direct communication between BIG-IQ and BIG-IP. Because there is no direct communication between BIG-IQ and BIG-IP, clients must provide additional device information as input. The client is responsible for installing the license on BIG-IP.

Assign a license

All assignment operations involve initiating a task, after which you should poll for task completion. See the Poll for task completion section below for details about polling.

Assign a purchased pool license to a managed device

To assign a purchased pool license to a managed device, supply the name of the pool and the discovery address of the BIG-IP. The discovery address is the address used to add the BIG-IP to BIG-IQ. A successful response will indicate the assignment task has started. You should subsequently poll the returned selfLink waiting for the task to complete.

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request

{
  "licensePoolName": "pool name",
  "command": "assign",
  "address": "192.0.2.1"
}

Response

{
    "licensePoolName": "pool name",
    "command": "assign",
    "address": "192.0.2.1",
    "id": "d717c6a1-f3bd-46cb-8410-c6fda58940b9",
    "status": "STARTED",
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/lm"
    },
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/lm"
        }
    ],
    "ownerMachineId": "b814fef0-2e8b-460d-af43-0d100dc50352",
    "taskWorkerGeneration": 1,
    "generation": 1,
    "lastUpdateMicros": 1497509153046646,
    "kind": "cm:device:tasks:licensing:pool:member-management:devicelicensingassignmenttaskstate",
    "selfLink": "https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9"
}

Assign a pool license offering to a managed device

All supported licenses other than purchased pools will have one or more offerings under the top-level license. An example utility license offering is F5-BIG-MSP-BT-1G-LIC-DEV. The offering names generally include the feature (good/better/best – the “BT” in the example) and throughput (the “1G” in the example). For RegKey Pools, each registration key in the pool is an offering. The API offers a couple of fields, skuKeyword1 and skuKeyword2 to allow you to specify the offering name you would like to assign. The fields are optional – you can supply zero, one or both of the fields. The API will match the strings provided against the offering names in the specified pool. If both search fields are provided, the first value must appear prior to the second in the offering name. If multiple offerings match the provided search criteria, the API will assign the first available offering (licenses in a RegKey Pool that are already assigned will be bypassed). In some cases, searching solely for the feature/throughput won’t be specific enough. The feature may be represented by “B”, but that also matches against the “F5-BIG” prefix. You can extend the search criteria, including dashes or other characters as needed to ensure the desired offering is selected.

Note, utility license assignments require one additional field, which is the unit of measure.

Example assignment of a utility license offering:

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request

{
  "licensePoolName": "u1",
  "command": "assign",
  "address": "192.0.2.1",
  "skuKeyword1": "BT",
  "skuKeyword2": "1G",
  "unitOfMeasure": "daily"
}

The response and need for polling for final status is similar to the purchased pool case shown above.

Example assignment of a license from a regkey pool:

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request

{
  "licensePoolName": "rgp1",
  "command": "assign",
  "address": "192.0.2.1",
  "skuKeyword1": "I3242"
}

Assigning a license to an unmanaged device

The above examples for managed devices also apply to unmanaged devices, the only difference being unmanaged devices require credentials also be provided.

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "assign",
  "address": "192.0.2.1",
  "user": "admin",
  "password": "password"
}

If you’re using a BIG-IP that is configured with an ssl-port other than 443 that also supports licensing with this configuration, you can supply the relevant port via the port field:

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "assign",
  "address": "192.0.2.1",
  "user": "admin",
  "password": "password",
  "port": 8443
}

Assigning a license to an unreachable device

For unreachable devices, BIG-IP credentials are not required. Instead, you must explicitly indicate that you want a license for an unreachable device as well as providing the device’s MAC address and the platform on which the device runs (the hypervisor field). If desired, you can also provide an optional description for the assignment via the tenant field. For this use case, the address does not need to be unique across devices.

For the hypervisor field, supported aliases include:

  • aws
  • azure
  • gce
  • vmware
  • hyperv
  • kvm
  • xen
POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "assign",
  "address": "192.0.2.1",
  "assignmentType": "UNREACHABLE",
  "macAddress": "FA:16:3E:1B:6D:32",
  "hypervisor": "vmware"
}

After polling for task completion, if the assignment is successful, the body will include a licenseText field with the license. Note that the license will be formatted for JSON output; if your client doesn’t handle it for you, you will need to substitute newline characters. This license can then be installed on BIG-IP manually or via BIG-IP API. The license will eventually reside within the /config/bigip.license file on BIG-IP. If placed directly in the bigip.license file, BIG-IP’s reloadlic command will load the new license. If the provided MAC address or platform/hypervisor are incorrect, BIG-IP will likely reject the license.

Revoke a license

Similar to the assignment operations, revoking a license involves initiating a task, after which you should poll for task completion.

Revoke a license from a managed device

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "revoke",
  "address": "192.0.2.1"
}

Revoke a license from an unmanaged device

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "revoke",
  "address": "192.0.2.1",
  "user": "admin",
  "password": "password"
}

You can also supply the port, if needed.

Revoke a license from an unreachable device

POST https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management

Request:

{
  "licensePoolName": "pool name",
  "command": "revoke",
  "address": "192.0.2.1",
  "assignmentType": "UNREACHABLE",
  "macAddress": "FA:16:3E:1B:6D:32"
}

Poll for task completion

For any assign or revoke task, you will need to poll the task waiting for it to complete. If successful, the final task status will be FINISHED and the licenseAssignmentReference will contain the reference to the resulting assignment. If the task fails, the final task status will be FAILED and errorMessage will be populated with relevant details. You can review restjavad logs for additional detail as needed.

Note that a finished task means BIG-IP accepted and installed the license, though subsequent MCP validation on BIG-IP may reject the license. You may want to validate the BIG-IP is operational after the task completes. This gap may be eliminated in a future release.

Tasks are retained for one week, though history also appears in the BIG-IQ Device audit log which has a longer default retention period.

GET https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9

Response

{
    "address": "192.0.2.1",
    "command": "assign",
    "currentStep": "POLL_ASSIGNMENT_STATUS",
    "endDateTime": "2017-06-14T23:46:04.532-0700",
    "generation": 7,
    "id": "d717c6a1-f3bd-46cb-8410-c6fda58940b9",
    "identityReferences": [
        {
            "link": "https://localhost/mgmt/shared/authz/users/lm"
        }
    ],
    "kind": "cm:device:tasks:licensing:pool:member-management:devicelicensingassignmenttaskstate",
    "lastUpdateMicros": 1497509164582382,
    "licenseAssignmentReference": {
        "link": "https://localhost/mgmt/cm/device/licensing/pool/purchased-pool/licenses/9a79bcf5-906e-4418-83c2-190ea22b9ec8/member-management/9847bfb5-f0a4-474b-b978-04586fc6d17d"
    },
    "licensePoolName": "pool name",
    "ownerMachineId": "b814fef0-2e8b-460d-af43-0d100dc50352",
    "selfLink": "https://localhost/mgmt/cm/device/tasks/licensing/pool/member-management/d717c6a1-f3bd-46cb-8410-c6fda58940b9",
    "skuKeyword1": "",
    "skuKeyword2": "",
    "startDateTime": "2017-06-14T23:45:53.063-0700",
    "status": "FINISHED",
    "userReference": {
        "link": "https://localhost/mgmt/shared/authz/users/lm"
    },
    "username": "lm"
}

Example of a failed response:

{
    "address": "192.0.2.1",
    "command": "assign",
    "currentStep": "GET_LICENSE",
    "endDateTime": "2017-06-14T23:57:10.608-0700",
    "errorMessage": "License pool 'bad pool name' not found",
    "id": "dee9bd7a-7760-452e-ab61-93df87f5cf36",
    "licensePoolName": "bad pool name",
    "status": "FAILED",
    ...
}

View outstanding assignments

The below example shows how to view all outstanding assignments across licenses. This is roughly equivalent to the Assignments page in the BIG-IQ UI.

GET https://localhost/mgmt/cm/device/licensing/assignments

Response

{
  "totalItems": 1,
  "items": [
    {
      "assignmentType": "UNREACHABLE",
      "auditRecordReference": {
        "link": "https://localhost/mgmt/cm/device/licensing/audit/e1f14034-8e3b-4ede-bba5-acb56afb71a7"
      },
      "deviceAddress": "192.0.2.1",
      ...