Allocations

Summary:

The allocation endpoint allows users to look at shared container costs broken out by a specified grouping. This endpoint will analyze the usage in the cluster, determine what portion of the cluster resources (via metrics) each group used, apply an overall weighting to them, and then divvy up the cost (pulled from Cloudability Cost data) into the groupings, based on that calculation. Any references to "Unallocated" references the same data that is called "Idle" in the User Interface.

Endpoint:

/containers/allocations

Query Arguments:

Parameter

Description

Default

Allowed

start/end

Start/End date for the window of allocation results. End date is inclusive.

Required

Format YYYY-MM-DD

group

Group the reported data by the given dimensions. Comma-separated value.

namespace

cluster
daemonset
job
namespace
pod
replicaset
replication_controller
service
cldy:labels:* (ie labels)

metrics

Metrics to calculate allocations for. Comma-separated value.

cpu/reserved
memory/reserved_rss
network/tx
network/rx
filesystem/usage

cpu/reserved
cpu/usage
memory/reserved
memory/reserved_rss
memory/usage
network/tx
network/rx
filesystem/usage

filters

Filter the reported data to the given dimension values. NOTE if filtering on cluster, the cost basis is also filtered, affecting the allocation percentages

N/A

pretty

Pretty-print the JSON response

None

true

Example Requests:

curl "https://api.cloudability.com/v3/containers/allocations?pretty=true&start=2018-11-01&end=2018-11-05" \
-u "${API_KEY}:"
{
  "result": {
    "allocations": [
      {
        "dimensions": [
          {
            "key": "namespace",
            "value": "team-1"
          }
        ],
        "metrics": [
          {
            "key": "cpu/reserved",
            "allocation": 1,
            "resource": {
              "mean": 674165746,
              "unit": "microcpu"
            },
            "fairShare": 0.9998232082752361
          },
          {
            "key": "memory/reserved_rss",
            "allocation": 0.7110344399914752,
            "resource": {
              "mean": 146106173228,
              "unit": "bytes"
            },
            "fairShare": 0.9957661490726946
          },
          {
            "key": "network/tx",
            "allocation": 1,
            "resource": {
              "mean": 435740119,
              "unit": "bytes"
            },
            "fairShare": 0.9990017505131438
          },
          {
            "key": "network/rx",
            "allocation": 1,
            "resource": {
              "mean": 471140316,
              "unit": "bytes"
            },
            "fairShare": 0.9853141815856736
          },
          {
            "key": "filesystem/usage",
            "allocation": 0.012227972902595396,
            "resource": {
              "mean": 322426673,
              "unit": "bytes"
            },
            "fairShare": 0.8637788876614724
          }
        ],
        "percentages": {
          "allocation": 0.6989469052842922,
          "fairShare": 0.9829955726607892,
          "fairShareUnallocated": 0.28404866737649703
        },
        "costs": {
          "fairShare": 1292.6725601966923,
          "allocation": 919.1389164142072
        }
      },
      {
        "dimensions": [
          {
            "key": "namespace",
            "value": "team-2"
          }
        ],
        "metrics": [
          {
            "key": "cpu/reserved",
            "allocation": 0.00004671091205959907,
            "resource": {
              "mean": 31490,
              "unit": "microcpu"
            },
            "fairShare": 0.00004670132384416218
          },
          {
            "key": "memory/reserved_rss",
            "allocation": 0.002285694571098157,
            "resource": {
              "mean": 469673574,
              "unit": "bytes"
            },
            "fairShare": 0.003200994425973792
          },
          {
            "key": "network/tx",
            "allocation": 0.00017524825032780823,
            "resource": {
              "mean": 76362,
              "unit": "bytes"
            },
            "fairShare": 0.0001750717190047967
          },
          {
            "key": "network/rx",
            "allocation": 0.00039125174354488,
            "resource": {
              "mean": 184334,
              "unit": "bytes"
            },
            "fairShare": 0.00038550490836877045
          },
          {
            "key": "filesystem/usage",
            "allocation": 0.00006559102038988304,
            "resource": {
              "mean": 1729501,
              "unit": "bytes"
            },
            "fairShare": 0.004633321542816044
          }
        ],
        "percentages": {
          "allocation": 0.0016277144384634554,
          "fairShare": 0.002725047866724222,
          "fairShareUnallocated": 0.0010973334282607665
        },
        "costs": {
          "fairShare": 3.5835304863092263,
          "allocation": 2.1404997631294083
        }
      },
      {
        "dimensions": [
          {
            "key": "namespace",
            "value": "team-3"
          }
        ],
        "metrics": [
          {
            "key": "cpu/reserved",
            "allocation": 0.00013011430911213508,
            "resource": {
              "mean": 87718,
              "unit": "microcpu"
            },
            "fairShare": 0.00013009040091972748
          },
          {
            "key": "memory/reserved_rss",
            "allocation": 0.0007375190902668424,
            "resource": {
              "mean": 151548344,
              "unit": "bytes"
            },
            "fairShare": 0.0010328565013316222
          },
          {
            "key": "network/tx",
            "allocation": 0.0008240011293263761,
            "resource": {
              "mean": 359050,
              "unit": "bytes"
            },
            "fairShare": 0.0008231777678514478
          },
          {
            "key": "network/rx",
            "allocation": 0.01451345611568346,
            "resource": {
              "mean": 6837874,
              "unit": "bytes"
            },
            "fairShare": 0.014300313505957653
          },
          {
            "key": "filesystem/usage",
            "allocation": 0.001862805385947693,
            "resource": {
              "mean": 49118373,
              "unit": "bytes"
            },
            "fairShare": 0.13158779079571156
          }
        ],
        "percentages": {
          "allocation": 0.0011054974792736251,
          "fairShare": 0.014279379472486479,
          "fairShareUnallocated": 0.013173881993212854
        },
        "costs": {
          "fairShare": 18.777868928499075,
          "allocation": 1.4537667275097281
        }
      }
    ],
    "unallocated": {
      "metrics": [
        {
          "key": "memory/reserved_rss",
          "allocation": 0.28594234634886845,
          "resource": {
            "mean": 58756565982,
            "unit": "bytes"
          }
        },
        {
          "key": "filesystem/usage",
          "allocation": 0.9858436307446075,
          "resource": {
            "mean": 25994683244,
            "unit": "bytes"
          }
        }
      ],
      "percentages": {
        "allocation": 0.29874400551866864
      },
      "cost": 392.8585124874148
    },
    "available": [
      {
        "key": "cpu/reserved",
        "mean": 674284954,
        "unit": "millicores"
      },
      {
        "key": "filesystem/usage",
        "mean": 26367957791,
        "unit": "bytes"
      },
      {
        "key": "memory/reserved_rss",
        "mean": 205483961128,
        "unit": "bytes"
      },
      {
        "key": "network/rx",
        "mean": 478162524,
        "unit": "bytes"
      },
      {
        "key": "network/tx",
        "mean": 436175531,
        "unit": "bytes"
      }
    ],
    "weights": [
      {
        "key": "cpu/reserved",
        "value": 0.15
      },
      {
        "key": "filesystem/usage",
        "value": 0.1
      },
      {
        "key": "memory/reserved_rss",
        "value": 0.7
      },
      {
        "key": "network/rx",
        "value": 0.025
      },
      {
        "key": "network/tx",
        "value": 0.025
      }
    ]
  }
}

Exporting Allocations Data to CSV

The /allocations endpoint also supports CSV export. Adding the header Accept: text/csv will result in a CSV output

More Complex Request Example:

curl "https://api.cloudability.com/v3/containers/allocations?pretty=true&start=2018-11-01&end=2018-11-05&metrics=cpu/reserved&filters=cluster==${CLUSTER_UID}&group=service" \
-u "${API_KEY}:"