Service status

GOLDNET Cloud for developers

API, CLI and Terraform

Script your servers with a REST API and scoped tokens, drive them from the goldnet command line, or describe them as code with Terraform.

Everything on this page is built; GOLDNET Cloud opens for self-service soon. Until then, request access and we set it up for you by hand.

Your servers, as JSON

curl -H "Authorization: Bearer $GOLDNET_TOKEN" \
  https://cloud.vcom.co.za/v2/instances

{"instances": [
  {"id": "<id>", "label": "web-1",
   "plan": "vc-2c-4g", "status": "running"}
]}

Developers

Code examples

The same things the control panel does, from your terminal or your pipeline.

REST API

REST API with curl

# list your servers
curl -H "Authorization: Bearer $GOLDNET_TOKEN" \
  https://cloud.vcom.co.za/v2/instances

# create one (a retry with the same key never makes two)
curl -X POST https://cloud.vcom.co.za/v2/instances \
  -H "Authorization: Bearer $GOLDNET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"region":"dbn1","plan":"vc-2c-4g","image":"ubuntu-24.04","label":"web-1","ssh_key_ids":["<key-id>"]}'

# reboot it
curl -X POST -H "Authorization: Bearer $GOLDNET_TOKEN" \
  -H "Content-Type: application/json" -d '{"type":"reboot"}' \
  https://cloud.vcom.co.za/v2/instances/<id>/actions

goldnet CLI

goldnet command-line tool

goldnet auth <token>                 # saved with file mode 600
goldnet catalog                      # regions, plans, images, apps
goldnet servers create web-1 --plan vc-2c-4g --image ubuntu-24.04 --ipv6
goldnet servers create blog --plan vc-1c-1g --app wordpress
goldnet servers resize <id> vc-4c-8g
goldnet ssh-keys add laptop ~/.ssh/id_ed25519.pub
goldnet volumes create data-1 100 --server <id>
goldnet billing                      # balance, burn rate, this month
goldnet servers --json               # raw JSON for scripts

Terraform

main.tf

terraform {
  required_providers {
    goldnetcloud = { source = "goldnet/goldnetcloud" }
  }
}
provider "goldnetcloud" {}   # reads GOLDNET_TOKEN

resource "goldnetcloud_ssh_key" "me" {
  name       = "laptop"
  public_key = file("~/.ssh/id_ed25519.pub")
}

resource "goldnetcloud_instance" "web" {
  label       = "web-1"
  plan        = "vc-2c-4g"
  image       = "ubuntu-24.04"   # or app = "wordpress"
  ssh_key_ids = [goldnetcloud_ssh_key.me.id]
  tags        = ["web"]
}

output "ip" { value = goldnetcloud_instance.web.ipv4 }

HTTP and JSON

REST API

  • Everything in the panel. Servers, snapshots, volumes, IPs, firewalls, private networks, load balancers, databases, clusters, DNS, billing and your account, at /v2.
  • Scoped tokens. Read-only or read and write, an expiry date if you want one, and a list of networks a token may be used from. Revoke one and scripts using it stop at once.
  • Safe retries. Send an Idempotency-Key header when you create something, and a retry never makes two.
  • Operations you can follow. Every change to a server is an operation you can poll until it's done, and we check the result before we call it done.
  • Rate limits. Response headers tell you how many requests you have left.

A few endpoints

GET  https://cloud.vcom.co.za/v2/catalog      # public: plans, images, regions
GET  https://cloud.vcom.co.za/v2/instances
POST https://cloud.vcom.co.za/v2/instances
POST https://cloud.vcom.co.za/v2/instances/<id>/resize
GET  https://cloud.vcom.co.za/v2/operations/<id>

goldnet CLI

Command-line tool

  • One file. For Node.js 18 or newer, with nothing else to install.
  • Covers the daily work. Servers, SSH keys, snapshots, volumes, reserved IPs, DNS records and your balance.
  • Scriptable. Add --json for raw output; set GOLDNET_TOKEN in CI.
  • Not published for download yet. Ask us and we send it to you.

Infrastructure as code

Terraform provider

  • Resources. goldnetcloud_instance, _ssh_key, _firewall, _volume, _dns_domain and _dns_record.
  • Changes in place. Change a plan and the server is resized; grow a volume and it grows. Every change waits for its operation to finish.
  • Built from source. The provider is not on the Terraform Registry yet. Build it with Go and point Terraform at it with a dev override; ask us for the source.

Build and use the provider

go build -o ~/.terraform.d/goldnet/terraform-provider-goldnetcloud .
cat > ~/.terraformrc <<'EOF'
provider_installation {
  dev_overrides { "goldnet/goldnetcloud" = "/home/you/.terraform.d/goldnet" }
  direct {}
}
EOF
export GOLDNET_TOKEN=gnc_...

FAQ

Developer questions

Where do I get an API token?

On the API page of the control panel, once your account is open. A token is shown once: copy it then.

Is there an OpenAPI file?

Not yet. The API page in the panel lists the endpoints, and the CLI and Terraform provider show every call.

Can I use the API from my office network only?

Yes. Give the token a list of allowed networks and it is refused from anywhere else.

Which region do I use?

dbn1: Durban, in Teraco's Durban data centre.

Keep exploring

More of GOLDNET Cloud

Trial server

Try a server before you commit. We set it up with you.

One-click apps

WordPress, Docker, Node.js, MinIO, Gitea, WireGuard and LAMP.

Networking

Firewalls, private networks, IPv6, reserved IPs, load balancers.

Talk to a person, not a call centre

Our teams in Gqeberha and Durban answer Monday to Friday, 09:00 to 18:00. Our WhatsApp assistant answers any time, and the network is monitored around the clock.