greennode

README

gnode

Unofficial community Go SDK for VNG Cloud (GreenNode) services.

Originally forked from vngcloud/vngcloud-go-sdk, but has been extensively rewritten — new module layout, zero external dependencies (net/http stdlib only), context-aware APIs, idiomatic Go patterns, and broader API coverage. This is not affiliated with or endorsed by VNG Cloud.

Installation

go get danny.vn/gnode

Quick Start

Service account (client credentials)

package main

import (
  "context"
  "fmt"

  "danny.vn/gnode"
  lbv2 "danny.vn/gnode/services/loadbalancer/v2"
)

func main() {
  c, err := greennode.NewClient(context.Background(), greennode.Config{
    Region:       "hcm-3",
    ClientID:     "__YOUR_CLIENT_ID__",
    ClientSecret: "__YOUR_CLIENT_SECRET__",
    ProjectID:    "__YOUR_PROJECT_ID__",
  })
  if err != nil {
    panic(err)
  }

  packages, err := c.LoadBalancer.ListLoadBalancerPackages(
    context.Background(), lbv2.NewListLoadBalancerPackagesRequest())
  if err != nil {
    panic(err)
  }

  for _, pkg := range packages.Items {
    fmt.Printf("Package: %+v\n", pkg)
  }
}

IAM user (username/password + optional TOTP)

package main

import (
  "context"

  "danny.vn/gnode"
  "danny.vn/gnode/auth"
)

func main() {
  c, err := greennode.NewClient(context.Background(), greennode.Config{
    Region:    "hcm-3",
    ProjectID: "__YOUR_PROJECT_ID__",
    IAMAuth: &auth.IAMUserAuth{
      RootEmail: "root@company.com",
      Username:  "your-username",
      Password:  "your-password",
      TOTP:      &auth.SecretTOTP{Secret: "YOUR_BASE32_SECRET"}, // omit if no 2FA
    },
  })
  if err != nil {
    panic(err)
  }

  // Use c.Compute, c.LoadBalancer, etc. as normal
  _ = c
}

The Region field (e.g. "hcm-3", "han-1") derives all endpoint URLs automatically. Explicit endpoint fields (e.g. VServerEndpoint) override the defaults if set.

Custom HTTP client

Use option.WithHTTPClient to inject a custom *http.Client — useful for rate limiting, tracing, or proxies:

import (
  "net/http"

  "danny.vn/gnode"
  "danny.vn/gnode/option"
)

httpClient := &http.Client{
  Transport: myRateLimitedTransport,
}

c, err := greennode.NewClient(ctx, greennode.Config{...},
  option.WithHTTPClient(httpClient),
)

Other options:

Option	Description
option.WithHTTPClient(c)	Replace the underlying *http.Client
option.WithTransport(t)	Set a custom http.RoundTripper on the default client
option.WithUserAgent(ua)	Override the User-Agent header

TOTP providers

Provider	Usage
&auth.SecretTOTP{Secret: "..."}	Compute TOTP from a base32 shared secret
auth.TOTPFunc(func(ctx) (string, error) { ... })	Bring your own source (Vault, env var, CLI prompt)
nil	No 2FA required

Services

Service	Description
Compute	Server lifecycle, floating IPs, server groups
Volume	Block volumes, snapshots, volume types
Network	VPCs, subnets, security groups, endpoints
Load Balancer	Load balancers, listeners, pools, certificates
GLB	Global load balancer pools, listeners
DNS	Hosted zones, DNS records
Identity	OAuth2 token acquisition
Portal	Portal info, project listing

See docs/architecture.md for the full architecture overview.

Documentation

• Architecture — layered design, request lifecycle, error handling
• API Coverage — what the SDK supports vs. what GreenNode exposes
• Test Coverage — coverage map and improvement plan

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

Documentation

Index

• type Client
  • func NewClient(ctx context.Context, cfg Config, opts ...option.ClientOption) (*Client, error)
• type Config

Types

type Client

type Client struct {
	// Primary services (latest API version)
	LoadBalancer *lbv2.LoadBalancerServiceV2
	Compute      *computev2.ComputeServiceV2
	Network      *networkv2.NetworkServiceV2
	Volume       *volumev2.VolumeServiceV2
	DNS          *dnsv1.VDnsServiceV1
	GLB          *glbv1.GLBServiceV1
	Portal       *portalv2.PortalServiceV2
	Identity     *identityv2.IdentityServiceV2

	// Legacy API versions
	ComputeV1 *computev1.ComputeServiceV1
	NetworkV1 *networkv1.NetworkServiceV1
	VolumeV1  *volumev1.VolumeServiceV1
	PortalV1  *portalv1.PortalServiceV1
}

Client provides flat access to all service APIs.

func NewClient

func NewClient(ctx context.Context, cfg Config, opts ...option.ClientOption) (*Client, error)

NewClient creates a fully-wired SDK client from the given configuration.

type Config

type Config struct {
	Region       string // e.g. "hcm-3", "han-1" — derives default endpoint URLs
	ClientID     string
	ClientSecret string
	ProjectID    string
	UserID       string
	ZoneID       string
	UserAgent    string
	IAMAuth      *auth.IAMUserAuth // optional — enables IAM user auth instead of client credentials

	RetryCount    int
	SleepDuration time.Duration

	IAMEndpoint      string
	VServerEndpoint  string
	VLBEndpoint      string
	VNetworkEndpoint string
	GLBEndpoint      string
	DNSEndpoint      string
}

Config holds all configuration needed to create an SDK client.