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.
-
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.
-
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.
-
Specify in the application code the path to the file with the access token.
-
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_uuidhosts = [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 = truessh_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.keyin the/opt/agentdirectory of the virtual machine; - grants permissions to the token file to the
rootuser of therootgroup; - 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.keyfile up to date.
-
(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_installargument is not specified or has the valuetrue, the agent will be installed automatically during the deployment of your image-based application.
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.
- Create a JSON file containing the metrics to be sent and the time of collecting these metrics (
base_date). - 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.
-
Generate a key for AES-256 symmetric encryption. Generation parameters:
- Method: cryptographically secure random number generator
crypto/rand. - Key size: 32 bytes.
- Method: cryptographically secure random number generator
-
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.
- Method: cryptographically secure random number generator
-
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.
-
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.
-
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.
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>",}
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>",}