Client library for VictoriaMetrics Cloud API

Go client library for interacting with the VictoriaMetrics Cloud API. This library provides a simple and idiomatic way to manage VictoriaMetrics Cloud resources programmatically:

• Full library documentation you can find in package docs.
• More info about VictoriaMetrics Cloud can be found in the official documentation.
• More information about the API can be found in the API documentation.

Just sign up for a free trial to get started with VictoriaMetrics Cloud.

Features

• Manage deployments (list, create, update, delete, get details)
• Manage access tokens for deployments (list, create, delete, reveal secret, revoke)
• Manage alerting/recording rule files for deployments (list, create, update, delete, get content)
• Retrieve information about cloud providers, regions and tiers

Installation

go get github.com/VictoriaMetrics/victoriametrics-cloud-api-go

Usage examples

For detailed examples, see the examples directory:

• Client initialization - Different ways to initialize the client
• Listing cloud providers, regions, and tiers - How to retrieve information about available cloud providers, regions, and tiers
• Deployments management - How to list, create, update, and delete deployments
• Access tokens management - How to list, create, reveal, and delete access tokens
• Rule files management - How to list, create, update, and delete alerting/recording rule files

Creating a client

package main

import (
	"log"

	vmcloud "github.com/VictoriaMetrics/victoriametrics-cloud-api-go/v1"
)

func main() {
	// Create a new client with your API key
	client, err := vmcloud.New("your-api-key")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Use the client to interact with the API
	// ...
}

Listing deployments

deployments, err := client.ListDeployments(context.Background())
if err != nil {
	log.Fatalf("Failed to list deployments: %v", err)
}

for _, deployment := range deployments {
	fmt.Printf("Deployment: %s (ID: %s)\n", deployment.Name, deployment.ID)
}

Creating a deployment

deployment := vmcloud.DeploymentCreationRequest{
	Name:              "my-deployment", // name of the deployment
	Type:              vmcloud.DeploymentTypeSingleNode, // single-node deployment
	Provider:          vmcloud.DeploymentCloudProviderAWS, // AWS as cloud provider
	Region:            "us-east-2", // US East (Ohio)
	Tier:              21, // s.starter.a
	StorageSize:       20, // storage size in GB
	StorageSizeUnit:   vmcloud.StorageUnitGB,
	Retention:         30, // data retention period in days
	RetentionUnit:     vmcloud.DurationUnitDay, 
	Deduplication:     10, // deduplication period in seconds
	DeduplicationUnit: vmcloud.DurationUnitSecond,
	MaintenanceWindow: vmcloud.MaintenanceWindowWeekendDays, // maintenance window on weekends
}

createdDeployment, err := client.CreateDeployment(context.Background(), deployment)
if err != nil {
	log.Fatalf("Failed to create deployment: %v", err)
}

fmt.Printf("Created deployment: %s (ID: %s)\n", createdDeployment.Name, createdDeployment.ID)

Managing access tokens

// Create a new access token for a deployment
tokenRequest := vmcloud.AccessTokenCreateRequest{
	Description: "My API token",
	Type:        vmcloud.AccessModeReadWrite,
}

createdToken, err := client.CreateDeploymentAccessToken(context.Background(), "deployment-id", tokenRequest)
if err != nil {
	log.Fatalf("Failed to create access token: %v", err)
}

fmt.Printf("Created token: %s (ID: %s)\n", createdToken.Description, createdToken.ID)

// List access tokens for a deployment
tokens, err := client.ListDeploymentAccessTokens(context.Background(), "deployment-id")
if err != nil {
	log.Fatalf("Failed to list access tokens: %v", err)
}

for _, token := range tokens {
	fmt.Printf("Token: %s (ID: %s)\n", token.Description, token.ID)
}

Managing alerting/recording rules

// Create a new rule file
ruleContent := `
groups:
- name: example
  rules:
  - alert: HighRequestLatency
    expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
    for: 10m
    labels:
      severity: page
    annotations:
      summary: High request latency
`

err := client.CreateDeploymentRuleFileContent(context.Background(), "deployment-id", "high-latency-alert.yml", ruleContent)
if err != nil {
	log.Fatalf("Failed to create rule file: %v", err)
}

// List rule files
ruleFiles, err := client.ListDeploymentRuleFileNames(context.Background(), "deployment-id")
if err != nil {
	log.Fatalf("Failed to list rule files: %v", err)
}

for _, fileName := range ruleFiles {
	fmt.Printf("Rule file: %s\n", fileName)
}

Documentation

For more information about the VictoriaMetrics Cloud API, please refer to the VictoriaMetrics Cloud documentation.

Testing

The library includes a comprehensive test suite. To run the tests:

make test

The tests use mocked HTTP responses and don't require actual API credentials.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.