v4.2.0 • Latest

Go SDK

The CloudNexus Go SDK provides a type-safe, idiomatic interface to all CloudNexus infrastructure APIs. Designed for high-concurrency environments, it features automatic retry logic, context support, zero-allocation pagination, and seamless integration with Go's standard library.

Installation

The SDK requires Go 1.20 or later. Install it using go get:

Terminal

go get github.com/cloudnexus/sdk-go/v4

Quick Start

Initialize the client and make your first API call. The SDK automatically reads credentials from ~/.cloudnexus/config or environment variables.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/cloudnexus/sdk-go/v4"
	"github.com/cloudnexus/sdk-go/v4/vps"
)

func main() {
	ctx := context.Background()
	
	// Initialize client with auto-discovered credentials
	client, err := cnx.NewClient()
	if err != nil {
		log.Fatal("failed to init client: %w", err)
	}

	// List all running VPS instances
	instances, err := client.VPS.List(ctx, vps.ListOpts{
		Status: vps.StatusRunning,
		Limit:  10,
	})
	if err != nil {
		log.Fatal("list failed: %w", err)
	}

	for, inst := range instances.Items {
		fmt.Printf("%s | %s | %s\n", inst.ID, inst.Name, inst.Region)
	}
}

💡 Tip

The SDK uses sdk-go under the hood for retry strategies, request tracing, and structured logging. Configure it via cnx.WithRetryPolicy() or cnx.WithTelemetry() options.

Authentication

The SDK supports multiple authentication methods. Credentials are resolved in the following order:

Method	Environment Variable	Use Case
API Key	`CNX_API_KEY`	CI/CD, Serverless
Access Token	`CNX_ACCESS_TOKEN`	Short-lived sessions
Workspace Config	~/.cloudnexus/config	Local development

Explicit key configuration:

client, err := cnx.NewClient(
	cnx.WithAPIKey("cnx_live_xxxxxxxxxxxx"),
	cnx.WithWorkspace("production"),
)

Pagination

All list operations return a cursor-based paginator. Iterate safely without loading everything into memory:

pager := client.Databases.ListAll(ctx, db.ListOpts{})
for pager.Next(ctx) {
	cluster := pager.Current()
	fmt.Println(cluster.ID)
}
if err := pager.Err(); err != nil {
	log.Fatal(err)
}

Error Handling

The SDK exports typed errors for precise failure handling. Wrap or match against cnx.Err*:

_, err := client.VPS.Create(ctx, vps.CreateOpts{...})
if err != nil {
	var apiErr cnx.APIError
	if errors.As(err, &apiErr) {
		switch apiErr.Code {
		case cnx.CodeRateLimited:
			log.Println("Back off and retry")
		case cnx.CodeQuotaExceeded:
			log.Println("Request support to increase limits")
		default:
			log.Printf("API error %d: %s", apiErr.Code, apiErr.Message)
		}
	}
}

⚠️ Important

Always check pager.Err() after pagination loops and handle cnx.ErrRequestTimeout in distributed systems to avoid silent failures.

Example: Managed PostgreSQL Cluster

Provision, connect, and scale a database cluster programmatically:

cluster, err := client.Databases.Create(ctx, db.CreateOpts{
	Name:   "app-primary-db",
	Engine: db.EnginePostgreSQL,v14,
	Region: "us-east-1",
	Tier:   db.TierStandard,2, // 2 vCPU, 4GB RAM
	MaintenanceWindow: db.MaintenanceOpts{
		Day: db.DaySunday, Hour: 3,
	},
})
if err != nil { log.Fatal(err) }

// Wait for provisioning
if err := cluster.AwaitReady(ctx); err != nil {
	log.Fatal("provisioning failed: %w", err)
}

fmt.Println("Connection String: %s", cluster.ConnectionURI)

// Scale vertically
_, err = client.Databases.Resize(ctx, cluster.ID, db.ResizeOpts{
	Tier: db.TierStandard,4, // 4 vCPU, 8GB RAM
})

Context & Cancellation

Every SDK method accepts a context.Context. Use it to enforce deadlines, cancel long-running operations, or inject request-scoped values:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

// Operation will abort if not completed within 10s
backup, err := client.Backups.Create(ctx, backup.Opts{...})

API Reference

Complete type documentation, method signatures, and configuration options are available in the official reference:

Need help? Open an issue on GitHub or join our Developer Discord. The SDK is open-source under the MIT license.