VK Cloud logo

Resource Usage Tracking

You can pass resource consumption metrics to VK Cloud when users work with your image-based applications purchased in Marketplace. This allows VK Cloud to automatically charge users for the consumed resources according to their selected tariff plan.

The example below shows how to organize secure delivery of metrics to VK Cloud using the following security mechanisms:

  • access to the Marketplace API via temporary tokens with automatic rotation performed without service downtime;
  • data encryption using a public and private key pair;
  • storing private keys only in protected infrastructure;
  • multi-level compromise detection.

Preparatory steps

  1. To encrypt request data to the Marketplace API and verify the authenticity of the digital signature of the response from the Marketplace server, request the public encryption key at marketplace@cloud.vk.com.

  2. When preparing the image of the VM where your image-based application is installed, create a folder for storing the file with the Marketplace API access token.

  3. Specify in the application code the path to the file with the access token.

  4. When preparing the service package of your image-based application, add additional resources to the Terraform manifest as shown in the example:

    resource "ivkcs_ssh_keypair" "keypair" {}   resource "ivkcs_user_data" "init" {  uuid         = var.instance_uuid  hosts        = [local.hosts_name]  target_os    = "almalinux9"  token_file_path  = "/opt/agent/xaas-secret-auth-token.key"  token_file_owner = "root"  token_file_group = "root"  token_rotate     = true      ssh_authorized_keys = [    ivkcs_ssh_keypair.keypair.public_key,  ]}

    Here:

    • uuid — the identifier of the image-based application instance.
    • hosts — the list of host names for initializing the Marketplace agent.
    • target_os — the OS of the virtual machine with the deployed application.
    • token_file_path — the path to the file with the token.
    • token_file_owner — the user who will be assigned as the owner of the token file. Optional argument.
    • token_file_group — the group that will be assigned to the token file. Optional argument.
    • token_rotate — a flag indicating whether automatic token rotation is performed:
      • true — the token will be updated from time to time. It is recommended to enable token rotation when passing sensitive information to VK Cloud, such as resource consumption metrics of users of your application.
      • false — the token will not be updated. This is the default value.

    For more information about the resource arguments, see the section The ivkcs_user_data resource.

    The resource configuration shown in the example:

    • creates a Marketplace API access token with a limited validity period;
    • places the token file xaas-secret-auth-token.key in the /opt/agent directory of the virtual machine;
    • grants permissions to the token file to the root user of the root group;
    • enables periodic token updates;
    • launches for the Marketplace agent (if it is installed) a task to keep the token in the /opt/agent/xaas-secret-auth-token.key file up to date.
  5. (Optional) To use the Marketplace agent for keeping the token in the file up to date, make sure that the Terraform manifest does not prohibit the agent installation: agent_install = false.

    If the agent_install argument is not specified or has the value true, the agent will be installed automatically during the deployment of your image-based application.

1. Get the Marketplace API access token

On the first API call, extract the token from the file whose path was specified in the token_file_path parameter of the Terraform manifest. On subsequent calls, the way to obtain the token depends on whether the agent is installed on your application instance.

Extract the current version of the token from the file whose path was specified in the token_file_path parameter of the Terraform manifest.

2. Prepare the source data

  1. Create a JSON file containing the metrics to be sent and the time of collecting these metrics (base_date).
  2. Add a timestamp in UTC format (timestamp) to the file.

Example of a JSON file with source data for sending:

{  "payload": {    "metrics": [      {        "id": 5001,        "param": "cpu_usage",        "value": 85.5      },      {        "id": 5002,        "param": "ram_usage",        "value": 16384      }    ],    "base_date": "2024-03-20T14:00:00Z"  },  "timestamp": "2024-03-20T14:00:00Z"}

You can send no more than 50 metrics at a time.

3. Encrypt the data for sending

  1. Generate a key for AES-256 symmetric encryption. Generation parameters:

    • Method: cryptographically secure random number generator crypto/rand.
    • Key size: 32 bytes.
  2. Generate an initialization vector (IV) for the CBC (Cipher Block Chaining) encryption mode. Generation parameters:

    • Method: cryptographically secure random number generator crypto/rand.
    • IV size: 16 bytes.
  3. Encrypt the JSON file with the source data. Encryption parameters:

    • Algorithm: AES in CBC mode.
    • Padding scheme: PKCS7.
    • Key: the 32-byte key generated in the previous steps.
    • IV: the 16-byte initialization vector generated in the previous steps.
  4. Encrypt the symmetric encryption key and the initialization vector. Encryption parameters:

    • Algorithm: RSA with the OAEP padding scheme.
    • Hash function: SHA-256.
    • Key: the public key obtained earlier.
  5. Compose the request body for the API call using the following structure:

    {    "encryptedPayload": "<ENCRYPTED_DATA>",    "encryptedKey": "<ENCRYPTED_KEY>",    "encryptedIV": "<ENCRYPTED_IV>"}

    Here:

    • <ENCRYPTED_DATA> — the encrypted JSON file with the source data.
    • <ENCRYPTED_KEY> — the encrypted symmetric encryption key.
    • <ENCRYPTED_IV> — the encrypted initialization vector.

4. (Optional) Test sending metrics

To debug the process of sending metrics to VK Cloud, make a request to the Marketplace API:

curl -X POST https://msk.cloud.vk.ru/marketplace/api/infra-api/v1-public/metrics/decrypt \-H 'Authorization: Bearer <TOKEN>' \-H 'Content-Type: application/json' \--data-raw '{    "encryptedPayload": "<ENCRYPTED_DATA>",    "encryptedKey": "<ENCRYPTED_KEY>",    "encryptedIV": "<ENCRYPTED_IV>"}'

Here:

  • <TOKEN> — the API access token.
  • <ENCRYPTED_DATA> — the encrypted JSON file with the source data.
  • <ENCRYPTED_KEY> — the encrypted symmetric encryption key.
  • <ENCRYPTED_IV> — the encrypted initialization vector.

Upon successful processing of the request, the API will return the list of the passed metrics.

Response example:

{    "payload": {        "metrics_ids": [5001, 5002],        "timestamp": "2024-03-20T14:00:02Z"    },    "signature": "<ENCRYPTED_SIGNATURE>",}

5. Send the metrics to VK Cloud

Make a request to the Marketplace API:

curl -X POST https://msk.cloud.vk.ru/marketplace/api/infra-api/v1-public/metrics/push \-H 'Authorization: Bearer <TOKEN>' \-H 'Content-Type: application/json' \--data-raw '{    "encryptedPayload": "<ENCRYPTED_DATA>",    "encryptedKey": "<ENCRYPTED_KEY>",    "encryptedIV": "<ENCRYPTED_IV>"}'

Here:

  • <TOKEN> — the API access token.
  • <ENCRYPTED_DATA> — the encrypted JSON file with the source data.
  • <ENCRYPTED_KEY> — the encrypted symmetric encryption key.
  • <ENCRYPTED_IV> — the encrypted initialization vector.

Upon successful processing of the request, the API will return the list of the passed metrics.

Response example:

{    "payload": {        "metrics_ids": [5001, 5002],        "timestamp": "2024-03-20T14:00:02Z"    },    "signature": "<ENCRYPTED_SIGNATURE>",}
Was this article helpful?