Tracking Liberty license usage on AWS ECS Fargate

You can track runtime license usage of Liberty that is deployed on Amazon Web Services (AWS) Elastic Container Service (ECS) Fargate. The license usage data contains information on system resource usage and the associated license bundle.

About this task

License usage tracking is done using a Task Definition. A Task Definition is an AWS abstract resource for running an application on Fargate. For more information, see Task definition parameters. The Docker labels within the Task Definition make it possible for IBM Cloud® Platform License Service to track usage for Liberty. You can create or update the Task Definition through AWS console GUI or JSON file. The Task Definition examples for Liberty runtime offerings and specific parameters are covered in subsequent sections.

Procedure

Create or update the Task Definition file to use in AWS ECS Fargate. The Task Definition includes the definitions of a container using the product (for example, WebSphere® Application Server Liberty Core) and another container for license usage logger. An example Task Definition follows.

{
  "executionRoleArn": "",
  "containerDefinitions": [
    {
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/ibm-license-usage-logger-for-fargate",
          "awslogs-region": "eu-central-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "user": "1001:0",
      "image": "icr.io/appcafe/open-liberty/samples/getting-started",
      "dependsOn": [
        {
          "containerName": "ibm-license-usage-logger-for-fargate",
          "condition": "START"
        }
      ],
      "essential": true,
      "name": "ibm_liberty",
      "dockerLabels": {
        "productID": "87f3487c22f34742a799164f3f3ffa78",
        "productName": "IBM WebSphere Application Server Liberty Core",
        "productMetric": "PROCESSOR_VALUE_UNIT"
      }
    },
    {
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/ibm-license-usage-logger-for-fargate",
          "awslogs-region": "eu-central-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "cpu": 0,
      "environment": [
        {
          "name": "AWS_S3_BUCKET_NAME",
          "value": "ibm-license-service-675801125365"
        },
        {
          "name": "AWS_S3_HTTPS_ENABLED",
          "value": "true"
        }
      ],
      "image": "quay.io/opencloudio/ibm-license-usage-logger-for-fargate:latest",
      "healthCheck": {
        "retries": 3,
        "command": [
          "CMD-SHELL",
          "./check-health.sh || exit 1"
        ],
        "timeout": 5,
        "interval": 30,
        "startPeriod": 300
      },
      "essential": false,
      "dockerLabels": {
        "productID": "33687f02f10b4475aa7236f4cd2f94e6",
        "productMetric": "FREE",
        "productName": "IBM License Usage Logger for Fargate"
      },
      "name": "ibm-license-usage-logger-for-fargate"
    }
  ],
  "memory": "2048",
  "family": "ibm-liberty",
  "taskRoleArn": "arn:aws:iam::675801125365:role/IBM-License-Usage-Role",
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "networkMode": "awsvpc",
  "cpu": "1024"
}

productID

The identifier for the product owner to entitle the use of Liberty.

productName

The name of the product owned to entitle the use of Liberty.

productMetric

The license metrics that are eligible for container licensing. The data is used for compliance and audit purposes. Set the product metrics.

VIRTUAL_PROCESSOR_CORE
Virtual processor Core (VPC) is a license metric unit that is based on the number of virtual cores (vCPUs) that are available to the product. A vCPU is a virtual core that is assigned to a virtual machine or a physical processor core.
PROCESSOR_VALUE_UNIT
Processor Value Unit (PVU) is a license metric unit that is based on the type and number of processors that are deployed on a server where the software is installed. For PVU-based licensing, IBM® defines a processor as a processor core on chip.

cloudpakName

The name of a product that entitles the use of another product. For example, product A may entitle products B and C. Use the cloudpakName label to identify product A and the productName label to identify product B or C.

cloudpakId

The identifier of a product that entitles the use of another product. For example, product A may entitle products B and C. Use the cloudpakId label to identify product A and the cloudpakId label to identify product B or C.

productCloudpakRatio

The product ratio for a contained product. For example, product A may entitle products B and C at different ratios. Use the productCloudpakRatio label to identify that ratio.

Use the Docker labels from the following options for the WebSphere Application Server (base) Liberty product you own.

WebSphere Application Server (base) Liberty stand-alone offering.

"essential": true,
        "name": "myapp",
        "dockerLabels": {
          "productID": "e7daacc46bbe4e2dacd2af49145a4723",
          "productName": "IBM WebSphere Application Server",
          "productMetric": "PROCESSOR_VALUE_UNIT"
        }

WebSphere Application Server (base) Liberty licensed through IBM WebSphere Application Server Hybrid Edition.

"essential": true,
        "name": "myapp",
        "dockerLabels": {
          "cloudpakName": "IBM WebSphere Hybrid Edition",
          "cloudpakId": "6358611af04743f99f42dadcd6e39d52",
          "productCloudpakRatio": "4:1",
          "productID": "e7daacc46bbe4e2dacd2af49145a4723",
          "productName": "IBM WebSphere Application Server",
          "productMetric": "VIRTUAL_PROCESSOR_CORE"
        }

WebSphere Application Server (base) Liberty licensed through IBM WebSphere Application Server Family Edition.

"essential": true,
        "name": "myapp",
        "dockerLabels": {
          "cloudpakName": "IBM WebSphere Application Server Family Edition",
          "cloudpakId": "be8ae84b3dd04d81b90af0d846849182",
          "productCloudpakRatio": "4:1", 
          "productID": "e7daacc46bbe4e2dacd2af49145a4723",
          "productName": "IBM WebSphere Application Server",
          "productMetric": "PROCESSOR_VALUE_UNIT"
        }

WebSphere Application Server (base) Liberty licensed through IBM WebSphere Application Server Cloud Pack for Applications.

"essential": true,
        "name": "myapp",
        "dockerLabels": {
          "cloudpakName": "IBM Cloud Pak for Applications",
          "cloudpakId": "4df52d2cdc374ba09f631a650ad2b5bf",
          "productCloudpakRatio": "4:1",
          "productID": "e7daacc46bbe4e2dacd2af49145a4723",
          "productName": "IBM WebSphere Application Server",
          "productMetric": "VIRTUAL_PROCESSOR_CORE"
        }

Set up licensing on AWS ECS Fargate for Liberty. See Tracking license usage on AWS ECS Fargate in the IBM Cloud Pak® foundational services documentation.

Check the license usage data.

Go to IBM-License-usage directory on the provided AWS S3 bucket.

The example of logger folder structure in the AWS S3 bucket.

IBM-License-usage     - The root folder.>
    <YYYY-MM-DD>                - The folder named with date in which the data was collected in the format “yyyy-mm-dd". The folder is listed in chronological order.
        product-<productID>     - The folder named with the first product id for which the data was collected
            task-<taskID>.csv   - The file with first task instance details on the day. The file is listed in chronological order.
            task-<taskID>.csv   - The file with the second task instance details.
        product-...             - The folder named with the second product id for which the data was collected.
            task-...            - The file with second task instance details.
    <YYYY-MM-DD>                - The folder named with date for the sewcond day in which the data was collected in the format “yyyy-mm-dd".

The data is refreshed every 5 minutes, starting at the beginning of the hour.

Calculate the peak daily usage by summing each metric for each timestamp from all available task-<taskID>.csv files.
Compare the values.

Optional: Aggregate the daily license usage data. For license data aggregation, use the open source tool IBM License Usage Aggregator for Fargate. See https://github.com/IBM/ibm-license-usage-aggregator-for-fargate.