Skip to content

Services

Jump to bottom
Danny edited this page Oct 13, 2026 · 30 revisions

Services

This overview links to service guides and shows selected SDK method examples. Use each guide for its supported operations, prerequisites, and recovery rules.

Each GreenNode product is its own package, for example danny.vn/vngcloud/compute. Every package has New(cfg vngcloud.Config) *Client, built from the same Config other services use, and read methods shaped Method(ctx, *MethodInput) (*MethodOutput, error). Most methods are reads. A method can still return a permission error when the selected principal lacks access to that product or region. A required Input field is marked "required"; passing it empty, or passing a nil Input when a field is required, returns vngcloud.ErrInvalidInput before any request.

billing covers budget writes: budgets and thresholds can be created, changed, and deleted. pricing reads price quotes. See Billing and Pricing. dns covers hosted zone and record writes too: zones and records can be created, changed, and deleted. See DNS. loadbalancer covers load balancer writes too: a load balancer can be created, resized, and deleted, with its pools, members, listeners, and L7 policies. See Load Balancer. network covers security group and rule writes, Public NAT purchase and deletion, route and ACL writes, and subnet associations. See Network and Public NAT. compute covers SSH key writes: a key can be imported, created, or deleted (see Compute), and paid server writes: a server can be created, started, stopped, rebooted, renamed, resized, and deleted (see Compute Servers). volume covers paid volume writes: a volume can be created, deleted, attached, detached, and resized. See Volume. containerregistry covers repository and repository user writes too: a repository or a user can be created and deleted. See Container Registry. iam covers IAM reads, service account writes, policy writes, and group writes: a service account can be created, updated, have its secret reset, and deleted; a customer policy can be created, updated, deleted, and attached to or detached from a service account, a group, or an IAM user; a group can be created, updated, deleted, and have members added or removed. Every write is guarded against changing the caller's own access or a principal that already holds an IAM write right. See IAM below. tagging writes tags on any resource type. See Tagging.

Service-account coverage

The recorded product checks used service-account tokens in hcm-3:

Operation Observed result
network.GetSecurityGroup for the narrowly allowed group 200
Read of the excluded group Non-disclosing 403
network.UpdateSecurityGroup under the read-only action policy 403; description unchanged
project.ListProjects and group read with project discovery 200; matching project and group
iam.GetCallerIdentity 200; service-account principal

These checks first used a supplied static token, then repeated the allowed and excluded group reads through vngcloud.WithServiceAccount with the SDK's own token exchange. A secret reset produced a separate cache entry and a fresh exchange, and the old secret failed login with 401. Other services, regions, and universal permission coverage are not live-verified. Server enumeration, expiry-wait behavior, and deletion/activation revocation remain unverified. Explicit project selection is recommended; discovery denial remains a permission error and never switches identities or grants policies. NAT create/delete still require SDK IAM-user login in Hanoi. See Authentication for auth and rotation.

Coverage

Product Package Coverage Model Shape Notes
Billing billing Budgets, thresholds, cost, balance, alerts, prepaid resources Typed Budgets and thresholds support writes; see Billing and Pricing.
Pricing pricing Generic resource price quotes Typed Quotes are reads; see Billing and Pricing.
Backup Center backup Backends and policies Typed See Backup; hcm-3 only, no project scope.
Project project Project listing for the configured region Typed Used by optional project discovery.
Portal portal User info, zones, quota usage, quota detail, tag quota Typed zones; map-backed account and quotas Useful for account and quota metadata.
Compute compute Servers, SSH keys and writes, placement groups and policies, images, flavor price discovery, paid server writes Typed Some methods flatten nested list data; see Compute and Compute Servers.
Volume volume Volumes, underlying volumes, snapshots and policies, volume types and encryption types, price discovery, create, delete, attach, detach, resize Typed See Volume for discovery, snapshot policies, and write behavior.
Network network VPCs, subnets, WAN IPs, interfaces, security groups, virtual IPs, routes, ACLs, endpoints, DHCP options, VPN inventory, Public NAT inventory and catalogs, public-IP price discovery, NAT quotes and writes Typed NAT create/delete supports han-1 with IAM-user login; see Network, Network-VPN, and Network-NAT.
Load Balancer loadbalancer Load balancers, listeners, pools, health monitors, pool members, policies, tags, packages, certificates, plus certificate writes, create/resize price quotes, and load balancer, pool, listener, and policy writes Typed Requires IAM User permissions for the target load balancer resources; see Load Balancer for writes, the price guard, and waits.
Global Load Balancer globalloadbalancer Packages, regions, load balancers, listeners, pools, pool members, usage history Typed Catalog methods do not require project selection.
DNS dns Hosted zones and records, plus zone and record writes Typed Not project-scoped like regional compute resources; see DNS for writes and waits.
Container Registry containerregistry Repositories and users, plus repository and user create and delete Typed See Container Registry for writes, waits, and secret handling.
CDN cdn Public IP ranges, vCDN certificates and API keys, Web Accelerator reads and updates, enable/disable, traffic analytics Typed vCDN calls use an API key; see CDN.
Monitor monitor Uptime checks, probe locations, notification channels, log projects, and alarms Typed See Monitor, Monitor Alerts, and Monitor Log Alarms for reads and writes.
IAM iam Caller identity, IAM users, IAM actions, policies, groups, service accounts, plus service account, policy, and group writes Typed Page numbers start at 0, as in VKS; see IAM below for writes and guards.
Tagging tagging Resource tag reads, plus tag writes Typed One tag API serves every resource type; see Tagging for TagResource and its errors.
Storage storage Console management, native S3 object PUT/GET/DELETE/COPY, listing, HEAD, regions, projects, buckets, settings, S3 keys, project purchase, deletion, and auto-renew updates Typed Management uses the undocumented console API; native object operations use explicit S3 credentials. See Storage, Storage Objects, Storage Workload Access, Storage Projects, and Storage Bucket Settings.
VKS vks Cluster inventory, versions, quota Typed Read-only operations; see VKS.

Project

projectClient := project.New(cfg)
projectClient.ListProjects(ctx, in) // Region (optional; defaults to cfg's region)

Project-scoped services discover their project the same way when Config has no ProjectID set and exactly one project matches the region.

Portal

portalClient := portal.New(cfg)
portalClient.GetUserInfo(ctx, nil)
portalClient.ListZones(ctx, nil)
portalClient.ListQuotaUsed(ctx, nil)
portalClient.GetQuota(ctx, in)     // Name (required)
portalClient.GetTagQuota(ctx, nil)

portal.Zone is a struct with ID, UUID, Name, ZoneType, IsDefault, Description, IsEnabled, VolumeCount, ServerCount, OpenStackZone, and IPRanges. Only Name is not a pointer. Check pointers for nil before reading them; absent or null fields stay nil, while present false, zero, empty strings, and empty arrays stay distinct. ID and UUID are separate fields with no fallback. Unknown fields are ignored.

SDK JSON uses API spellings (uuid, isEnabled); CLI JSON, table, text, and queries use Go names (UUID, IsEnabled). Nil pointers encode as null. User info and quotas remain map-backed and preserve returned fields.

Compute

computeClient := compute.New(cfg)
computeClient.ListServers(ctx, in)              // Page, Size
computeClient.GetServer(ctx, in)                // ServerID (required)
computeClient.ListSSHKeys(ctx, in)              // Name, Page, Size
computeClient.ListServerGroups(ctx, in)         // Name, Page, Size
computeClient.ListServerSecurityGroups(ctx, nil)
computeClient.ListServerGroupMembers(ctx, nil)
computeClient.ListServerGroupPolicies(ctx, nil)
computeClient.ListOSImages(ctx, in)             // ZoneID
computeClient.ListGPUImages(ctx, nil)
computeClient.ListUserImages(ctx, in)           // Page, Size
computeClient.ListFlavorZones(ctx, in)          // ZoneID
computeClient.ListFlavors(ctx, in)              // FlavorZoneID or ZoneID, Name
computeClient.QuoteCreateServer(ctx, in)        // *compute.CreateServerInput

ListServerSecurityGroups and ListServerGroupMembers flatten nested data already returned by server and server-group list APIs. They do not require extra API calls.

SSH key writes (ImportSSHKey, CreateSSHKey, DeleteSSHKey) and the vngcloud.Secret a create returns are on the Compute page. Server writes (CreateServer, DeleteServer, StartServer, StopServer, RebootServer, RenameServer, ResizeServer) and their price guard are on Compute Servers.

ListFlavorZones filters the API's full flavor zone list to Input.ZoneID itself; leave it unset to list every flavor zone. QuoteCreateServer prices a server compute.CreateServerInput would create, without ordering it; see Billing and Pricing.

Volume

volumeClient := volume.New(cfg)
volumeClient.ListVolumes(ctx, in)          // Name, Page, Size
volumeClient.GetVolume(ctx, in)            // VolumeID (required)
volumeClient.GetUnderlyingVolume(ctx, in)  // VolumeID (required)
volumeClient.ListVolumesByServer(ctx, in)  // ServerID (required)
volumeClient.ListVolumeTypeZones(ctx, in)  // ZoneID
volumeClient.ListVolumeTypes(ctx, in)      // VolumeTypeZoneID or ZoneID, IOPS
volumeClient.GetVolumeType(ctx, in)        // VolumeTypeID (required)
volumeClient.GetDefaultVolumeType(ctx, in) // ZoneID
volumeClient.ListEncryptionTypes(ctx, nil)
volumeClient.ListSnapshots(ctx, in)        // VolumeID (required), Page, Size
volumeClient.ListAllSnapshots(ctx, nil)
volumeClient.QuoteCreateVolume(ctx, in)    // *volume.CreateVolumeInput

Volume writes (CreateVolume, DeleteVolume, AttachVolume, DetachVolume, ResizeVolume) and their price guard, waits, and errors are on the Volume page.

ProjectID is optional in Config. Volume methods discover the project for the configured region when needed.

ListAllSnapshots is a convenience method that walks visible volumes and returns their snapshots. ListVolumesByServer lists the volumes attached to one server, including its boot volume. GetDefaultVolumeType's ZoneID selects which zone's default to read; without it, the API looks up the region's first zone, which can be disabled for the account. QuoteCreateVolume prices a volume volume.CreateVolumeInput would create, without ordering it; see Billing and Pricing.

Network

network imports compute for the compute.Server model, since ListServersBySecurityGroup returns full server objects.

networkClient := network.New(cfg)
networkClient.ListVNetworkRegions(ctx, nil)
networkClient.ListVPCs(ctx, in)                            // Name, Page, Size
networkClient.GetVPC(ctx, in)                               // VPCID (required)
networkClient.ListWANIPs(ctx, in)                           // Name, Page, Size
networkClient.ListNetworkInterfaces(ctx, in)                // Name, Page, Size
networkClient.ListSecurityGroups(ctx, in)                   // Name, Page, Size
networkClient.GetSecurityGroup(ctx, in)                     // SecurityGroupID (required)
networkClient.ListServersBySecurityGroup(ctx, in)           // SecurityGroupID (required)
networkClient.ListVirtualIPAddresses(ctx, in)               // Name, Page, Size
networkClient.ListRouteTables(ctx, in)                      // Name, Page, Size
networkClient.ListPeerings(ctx, in)                         // Name, Page, Size
networkClient.ListNetworkACLs(ctx, in)                      // Name, Page, Size
networkClient.GetNetworkACL(ctx, in)                        // NetworkACLID (required)
networkClient.ListInterconnects(ctx, in)                    // Name, Page, Size
networkClient.ListSubnets(ctx, nil)
networkClient.ListSubnetsByVPC(ctx, in)                     // VPCID (required)
networkClient.GetSubnet(ctx, in)                            // VPCID, SubnetID (both required)
networkClient.ListSecurityGroupRules(ctx, in)               // SecurityGroupID (required)
networkClient.ListAllSecurityGroupRules(ctx, nil)
networkClient.ListRouteTableRoutes(ctx, nil)
networkClient.GetVirtualIPAddress(ctx, in)                  // VirtualIPAddressID (required)
networkClient.ListAddressPairsByVirtualIPAddress(ctx, in)   // VirtualIPAddressID (required)
networkClient.ListAddressPairsByVirtualSubnet(ctx, in)      // VirtualSubnetID (required)
networkClient.ListAllVirtualIPAddressAddressPairs(ctx, nil)
networkClient.ListEndpoints(ctx, in)                        // ZoneID, VPCID, UUID, Page, Size
networkClient.GetEndpoint(ctx, in)                          // EndpointID (required)
networkClient.ListEndpointTags(ctx, in)                     // EndpointID (required)

ListEndpoints and GetEndpoint discover VNetwork region metadata when needed before reading endpoint resources.

The SDK has no method for a single network interface.

network also writes security groups and their rules, route tables and routes, and network ACLs, their rules, and subnet associations; see Network for CreateSecurityGroup, UpdateSecurityGroup, DeleteSecurityGroup, CreateSecurityGroupRule, DeleteSecurityGroupRule, CreateRouteTable, DeleteRouteTable, AddRoute, and RemoveRoute, their waits, and their errors, and Network ACLs for CreateNetworkACL, DeleteNetworkACL, AddNetworkACLRule, RemoveNetworkACLRule, AssociateNetworkACLSubnet, and DisassociateNetworkACLSubnet.

Load Balancing

Regional Load Balancer APIs are in loadbalancer.

lbClient := loadbalancer.New(cfg)
lbClient.ListLoadBalancers(ctx, in)         // Name, Page, Size
lbClient.GetLoadBalancer(ctx, in)           // LoadBalancerID (required)
lbClient.ListListeners(ctx, in)             // LoadBalancerID (required)
lbClient.GetListener(ctx, in)               // LoadBalancerID, ListenerID (both required)
lbClient.ListPools(ctx, in)                 // LoadBalancerID (required)
lbClient.GetPool(ctx, in)                   // LoadBalancerID, PoolID (both required)
lbClient.GetPoolHealthMonitor(ctx, in)      // LoadBalancerID, PoolID (both required)
lbClient.ListPoolMembers(ctx, in)           // LoadBalancerID, PoolID (both required)
lbClient.ListPolicies(ctx, in)              // LoadBalancerID, ListenerID (both required)
lbClient.GetPolicy(ctx, in)                 // LoadBalancerID, ListenerID, PolicyID (all required)
lbClient.ListTags(ctx, in)                  // LoadBalancerID (required)
lbClient.ListPackages(ctx, in)              // ZoneID
lbClient.ListCertificates(ctx, in)          // Name, Page, Size
lbClient.GetCertificate(ctx, in)            // CertificateID (required)
lbClient.ImportCertificate(ctx, in)         // Name, Type, Certificate (all required); CertificateChain, PrivateKey, Passphrase
lbClient.DeleteCertificate(ctx, in)         // CertificateID (required)
lbClient.QuoteCreateLoadBalancer(ctx, in)   // *loadbalancer.CreateLoadBalancerInput
lbClient.QuoteResizeLoadBalancer(ctx, in)   // *loadbalancer.ResizeLoadBalancerInput

QuoteCreateLoadBalancer prices a load balancer that loadbalancer.CreateLoadBalancerInput would create, and QuoteResizeLoadBalancer prices a package change loadbalancer.ResizeLoadBalancerInput describes, neither ordering anything; see Billing and Pricing. Every path ID above, including one carried in a body such as PackageID or SubnetID, is checked before any request; a malformed one, .. or / for example, returns vngcloud.ErrInvalidInput.

ImportCertificate sends PrivateKey and Passphrase to GreenNode, which stores the certificate and never returns the key back; both fields are vngcloud.Secret, so printing, logging, or JSON-encoding the Input gives [redacted]. Type is loadbalancer.CertificateTypeTLS ("TLS/SSL") or loadbalancer.CertificateTypeCA ("CA"); only TLS/SSL takes a key, chain, or passphrase. A failing import never returns the server's own message: on every failing status the returned error's message is fixed text (loadbalancer.ImportCertificateWithheldMessage), since no pattern match can be proven to catch every way a server might echo a rejected key or passphrase back; the status and (still redacted) code still come from the server. ImportCertificate is a POST and is never retried after a failure that may have already reached the server; the error names ListCertificates by name as the way to check what happened. DeleteCertificate reads the certificate first and returns loadbalancer.ErrCertificateInUse, sending nothing, when a listener still uses it.

loadbalancer also creates, resizes, and deletes load balancers, and creates, updates, and deletes their pools (with health monitors and members), listeners, and L7 policies; see Load Balancer for the price guard, busy handling, waits, and errors.

Global Load Balancer APIs are in globalloadbalancer.

glbClient := globalloadbalancer.New(cfg)
glbClient.ListPackages(ctx, nil)
glbClient.ListRegions(ctx, nil)
glbClient.ListLoadBalancers(ctx, in)   // Name, Offset, Limit
glbClient.GetLoadBalancer(ctx, in)     // LoadBalancerID (required)
glbClient.ListPools(ctx, in)           // LoadBalancerID (required)
glbClient.ListListeners(ctx, in)       // LoadBalancerID (required)
glbClient.GetListener(ctx, in)         // LoadBalancerID, ListenerID (both required)
glbClient.ListPoolMembers(ctx, in)     // LoadBalancerID, PoolID (both required)
glbClient.GetPoolMember(ctx, in)       // LoadBalancerID, PoolID, PoolMemberID (all required)
glbClient.ListUsageHistories(ctx, in)  // LoadBalancerID (required), From, To, Type

Package and region catalog methods are global metadata calls. Inventory and nested resource methods require IAM User access to the target resources.

DNS

dnsClient := dns.New(cfg)
dnsClient.ListHostedZones(ctx, in)  // Name, Page, Size
dnsClient.GetHostedZone(ctx, in)    // HostedZoneID (required)
dnsClient.ListRecords(ctx, in)      // HostedZoneID (required), Name
dnsClient.GetRecord(ctx, in)        // HostedZoneID, RecordID (both required)

DNS APIs are not project-scoped in the same way as regional compute resources. They may still require IAM User permissions for the DNS product.

Zone writes (CreateHostedZone, UpdateHostedZone, DeleteHostedZone), record writes (CreateRecord, UpdateRecord, DeleteRecord), and their waits are on the DNS page.

Container Registry

Repository and user reads and writes, their waits, and the registry secret handling are on the Container Registry page.

IAM

iamClient := iam.New(cfg)
iamClient.GetCallerIdentity(ctx, nil)
iamClient.ListUsers(ctx, in)                   // Page, Size
iamClient.ListActions(ctx, nil)
iamClient.ListServiceAccounts(ctx, in)         // Name, Page, Size
iamClient.GetServiceAccount(ctx, in)           // ServiceAccountID (required)
iamClient.ListPolicies(ctx, in)                // Name, Page, Size
iamClient.GetPolicy(ctx, in)                   // PolicyID (required)
iamClient.ListPolicyAttachments(ctx, in)       // PolicyID (required)
iamClient.ListGroups(ctx, nil)
iamClient.GetGroup(ctx, in)                    // GroupID (required)
iamClient.ListGroupPolicies(ctx, in)           // GroupID (required), Page, Size
iamClient.ListUserPolicies(ctx, in)            // UserID (required), Page, Size
iamClient.ListUserGroups(ctx, in)              // UserID (required)
iamClient.ListServiceAccountPolicies(ctx, in)  // ServiceAccountID (required), Page, Size

Policy and group reads run on the IAM console host; every other call, including every service account call, runs on the dashboard host. Page numbers start at 0 in iam, as in vks: Page: 0 is the first page, and a non-positive Size sends vngcloud.DefaultPageSize.

Policy.Managed() reports whether a policy is one GreenNode manages: it can be read and attached, but never updated or deleted.

iam also writes service accounts, policies, and groups; see IAM for CreateServiceAccount, UpdateServiceAccount, ResetServiceAccountSecret, DeleteServiceAccount, CreatePolicy, UpdatePolicy, DeletePolicy, AttachServiceAccountPolicy, DetachServiceAccountPolicy, AttachUserPolicy, DetachUserPolicy, CreateGroup, UpdateGroup, DeleteGroup, AddUserToGroup, RemoveUserFromGroup, AttachGroupPolicy, DetachGroupPolicy, their guards, and their errors.

Tagging

taggingClient := tagging.New(cfg)
taggingClient.ListResourceTags(ctx, in)  // ResourceID (required)

ListResourceTags reads any resource's tags through the one tag API the vServer gateway serves for every resource type. TagResource, its read-merge write, and its errors are on the Tagging page.

Storage

storageClient := storage.New(cfg)
storageClient.ListRegions(ctx, nil)
storageClient.ListProjects(ctx, in) // Region (optional; defaults from cfg's region)
storageClient.ListBuckets(ctx, in)  // ProjectID (required), Region
storageClient.GetBucket(ctx, in)    // ProjectID (required), Bucket (required), Region
storageClient.ListS3Keys(ctx, in)   // ProjectID (required), Region

objectClient, err := storage.NewObjectClient(storage.ObjectConfig{
	Region: "HCM04", Credentials: storage.ObjectCredentials{
		AccessKeyID: vngcloud.Secret("<access-key-id>"),
		SecretAccessKey: vngcloud.Secret("<secret-access-key>"),
	},
}) // native S3 data plane; credentials stay in memory

For the storage.New(cfg) management calls above, Region is a vStorage region name, HCM04 or HAN02. Empty maps hcm-3 to HCM04 and han-1 to HAN02. The native ObjectConfig.Region requires the exact value HCM04 or HAN02; it does not use the management region defaults. storage also writes buckets and S3 keys; see Storage for CreateBucket, DeleteBucket, CreateS3Key, and DeleteS3Key, the console API's envelope errors, and the state of an account with no project.

Home

SDK

CLI

Clone this wiki locally