evroc Go SDK

The evroc Go SDK is the official Go client for the evroc cloud APIs. It lets you provision virtual machines, configure networking, manage storage, and control access from your Go code.

For installation, examples, and the full API reference, see the GitHub repository.

Overview

When you're building services that run on evroc, you often need programmatic control over your infrastructure — scaling compute out at peak load, provisioning environments from a CI pipeline, or driving resources from a control plane of your own. The Go SDK wraps the evroc REST APIs in idiomatic, type-safe Go so you don't have to hand-roll HTTP clients or track API changes yourself.

The SDK covers the full evroc API — every service reachable through the evroc CLI, Terraform provider, and Console is available in Go.

Key features

The Go SDK provides:

  • Type-safe clients - Strongly typed Go structs for every API resource, with compile-time validation of request shapes
  • Builder pattern - Fluent builders for constructing VM, disk, security group, and other resource specs without memorizing the underlying API schema
  • Async helpers - Waiters that block until a resource reaches a desired state (e.g., VM running, disk ready), so you don't have to write polling loops
  • Context support - Every call accepts a context.Context for cancellation, timeouts, and deadlines
  • Configurable retries - Built-in exponential backoff for transient API errors
  • Automatic token refresh - Long-running programs keep authenticating as access tokens expire
  • Prometheus metrics - Optional metrics for request rates, latencies, and errors

For the current capability matrix, see the coverage table in the README.

How it works

You create a single Client that holds your credentials and HTTP configuration, then reach the service-specific sub-clients through it:

client, err := evroc.NewFromEnv(ctx)
vm, err := client.Compute().VirtualMachines().Get(ctx, "my-vm")

Each sub-client — Compute(), Networking(), Storage(), IAM(), Quotas(), Think(), and LoadBalancer() — exposes CRUD methods for its resources. Resource specs are built with fluent builders that help you construct valid requests:

disk, err := client.Compute().Disks().Create(ctx,
    compute.NewDiskBuilder("my-disk").
        WithImage(compute.DiskImageUbuntuMinimal2404).
        WithSizeGB(50).
        WithZone("a").
        Build(),
)

The SDK handles authentication, token refresh, retries, and response parsing internally, so you work with Go types rather than raw HTTP.

Authentication

The SDK supports three authentication methods:

  • evroc CLI credentials - If you've run evroc login, the SDK automatically reads your tokens and project settings from ~/.evroc/config.yaml (%USERPROFILE%\.evroc\config.yaml on Windows). This is the easiest path for local development.
  • User tokens - Set EVROC_REFRESH_TOKEN (or EVROC_TOKEN) along with EVROC_PROJECT and EVROC_REGION. A refresh token alone is enough — the SDK obtains an access token for you.
  • Service accounts - Set EVROC_SERVICE_ACCOUNT_ID and EVROC_SERVICE_ACCOUNT_SECRET for JWT bearer authentication. This is the recommended path for CI pipelines and production services.

All three paths converge on the same constructor:

client, err := evroc.NewFromEnv(ctx)

NewFromEnv reads environment variables first and falls back to the CLI config. To load a specific file instead, use NewFromFile or NewFromCLIConfig.

Service account credentials can be created through the SDK itself with client.IAM().ServiceAccounts() and client.IAM().ServiceAccountCredentials(). A credential's private key is returned only at creation time, so capture it then.

Prerequisites

To use the Go SDK, you need:

  • Go 1.24 or later
  • An evroc account with at least one project
  • Credentials — either from the evroc CLI (evroc login) or a service account

Install the SDK with:

go get github.com/evroc-oss/evroc-go-sdk

Learn more