vngcloud

A Go SDK and AWS-style command-line tool for GreenNode, formerly VNG Cloud. Inspect resources, get price quotes, and use selected management operations from Go, a terminal, or scripts.

This is a personal, unofficial project, not affiliated with or endorsed by GreenNode or VNG. Expect breaking changes until v1.0.0.

CLI quick start

Install with the Go version required by go.mod or later:

go install danny.vn/vngcloud/cmd/vngcloud@latest

Add Go's binary directory to your PATH if your shell cannot find vngcloud. Then configure your region and IAM User credentials:

vngcloud configure
vngcloud billing list-budgets

Configuration prompts for the root account email, IAM username, password, and optional two-factor authentication secret. Passwords and secrets are not echoed. The IAM User needs permission for the operations you call. For service-account setup, see Configuration.

Commands follow vngcloud <service> <operation> [flags]:

# Show servers as a table.
vngcloud compute list-servers --output table

# Print only server names.
vngcloud compute list-servers --query 'Items[].Name' --output text

# Use a named profile in another region.
vngcloud compute list-servers --profile production --region han-1

# Discover operations and their flags.
vngcloud --help
vngcloud compute list-servers --help

Create a named profile with vngcloud configure --profile production. Set --project-id when more than one project matches the region. See the CLI reference for all commands, flags, and exit codes.

Go SDK quick start

Add the module to your Go project:

go get danny.vn/vngcloud@latest

The SDK uses the same profiles and environment variables as the CLI. After vngcloud configure, this program lists your budgets:

package main

import (
	"context"
	"fmt"
	"log"

	"danny.vn/vngcloud"
	"danny.vn/vngcloud/billing"
)

func main() {
	ctx := context.Background()

	cfg, err := vngcloud.LoadConfig(ctx)
	if err != nil {
		log.Fatal(err)
	}

	budgets, err := billing.New(cfg).ListBudgets(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Budgets: %d\n", len(budgets.Items))
}

Each service has its own package and New(cfg) client. Clients built from the same configuration share authentication and project discovery. The SDK packages use only the Go standard library.

For credentials supplied through environment variables, static tokens, or a custom credentials provider, see Authentication and Configuration. The basic example shows multiple service clients in one program.

Service coverage

The SDK and CLI support selected operations in the services below. Coverage varies by service; the linked guides explain each service's supported scope.

Service	Supported resources and operations
Billing and pricing	Budgets, alerts, costs, balances, quotes
Compute	Servers, images, flavors, flavor price discovery, SSH keys, placement groups
Volumes	Create, attach, resize, volume price discovery; read snapshots, policies, encryption types, and disk types
Network	VPCs, subnets, IPs, security groups, routes, ACLs, NAT inventory, catalogs and quotes, VPN inventory, public-IP price discovery; NAT create/delete in han-1 with IAM-user login
Load balancers	Create, resize, pools, listeners, policies, TLS certs
DNS	Create, update, and delete private zones and records
Container registry	Repositories and repository users
Storage	Management, native S3 PUT/GET/DELETE/COPY, listing, HEAD, buckets, keys and settings
CDN	Web Accelerator updates, enable/disable, analytics, IP ranges
Monitoring	Uptime checks, channels, log projects, alarms, quota reads
IAM	Users, service accounts, policies, groups, access guards
Tagging	Read, add, and remove resource tags
Kubernetes	Read clusters, versions, and quota
Backup	Read backends and policies

Project discovery, account quotas, and global load balancer reads are also available. See the service overview for SDK method examples. Use the native vStorage object guide for binary file uploads and downloads, one-page listing, HEAD metadata, single-object current-name deletion with --yes, and server-side copy with --replace --yes. Create-only copy and move remain unavailable. Management uses the storage.New console client; object operations use the separate storage.NewObjectClient S3 client. For an application on vServer or VKS, see Storage Workload Access for identity setup, bucket grants, private key handoff, and rotation.

Scripts and AI agents

• Structured output: JSON by default, with table and text formats. Filter results with JMESPath expressions through --query.
• Predictable failures: errors go to stderr as JSON with stable exit codes. Commands never prompt without a terminal.
• CLI read-only guard: --read-only refuses every CLI write before any request. Set read_only = true in a profile to keep the guard enabled.
• Explicit writes: destructive commands require --yes. Supported paid creates and resizes compare a quote against --max-price before ordering. This check is not a provider price lock or a final billing guarantee. Quote commands place no orders.

vngcloud configure --profile agent
vngcloud configure set read_only true --profile agent
vngcloud compute list-servers --profile agent --output json

The read-only guard applies to the CLI. Use IAM policies to restrict the credentials themselves. See Security for credential storage, token caching, and write guards.

Documentation

• Getting started: installation and client setup.
• CLI reference: commands, flags, queries, and exit codes.
• Service overview: SDK method examples and service guide links.
• Storage Workload Access: application identities, bucket grants, private key handoff, rotation, and network prerequisites for vServer and VKS.
• Configuration: profiles, environment variables, regions, projects.
• Authentication: IAM User and service-account login, two-factor codes, static tokens, and custom credential providers.
• Known limitations: API quirks and recovery guidance.
• Release notes: changes by version.
• Go reference: package documentation.

Contributing

See CONTRIBUTING.md for setup and checks. Report security problems privately through SECURITY.md. Live tests and their helpers live in livetest/; see the compile-only commands in CONTRIBUTING.md.

Licensed under Apache 2.0.