thunder

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2026 License: MIT Imports: 12 Imported by: 3

README

Thunder SDK

Thunder SDK is a small Go client library for Thunder Compute integrations. It wraps the Thunder Central organization API-token surface used by automation that creates enrollment tokens, manages servers and clients, and works with zones.

Audience

This SDK is intended for Thunder Enterprise users building automation against Thunder Compute. It is not intended for Thunder Cloud users; cloud users should use the Thunder CLI and Thunder Compute Documentation. Those resources detail how to interface with instances and snapshots for our cloud offering.

Install

Requires Go 1.22 or newer.

go get github.com/Thunder-Compute/thunder-sdk

Usage

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	thunder "github.com/Thunder-Compute/thunder-sdk"
)

func main() {
	ctx := context.Background()
	client := thunder.NewThunder("", os.Getenv("THUNDER_API_TOKEN"))

	zones, err := client.ListZones(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("zones: %+v\n", zones)
}

Pass an empty base URL to use the default Thunder Central API endpoint:

client := thunder.NewThunder("", apiToken)

The client sends the token as a bearer token in the Authorization header.

Use a custom endpoint, HTTP client, user agent, or installer URL when needed:

client := thunder.NewThunder(
	"https://api.thundercompute.com:2096",
	apiToken,
	thunder.WithUserAgent("my-integration/1.0"),
)

Common Operations

Create a client enrollment token:

token, err := client.CreateClientEnrollment(ctx, thunder.CreateClientEnrollmentRequest{
	ZoneID:   "zone-1",
	GPUType:  "nvidia-l4",
	GPUCount: 1,
})

Create a server enrollment token:

token, err := client.CreateServerEnrollment(ctx, thunder.CreateServerEnrollmentRequest{
	ZoneID: "zone-1",
})

List registered servers and clients:

servers, err := client.ListServers(ctx, "zone-1")
clients, err := client.ListClients(ctx, "zone-1")

Create and delete zones:

zone, err := client.CreateZone(ctx, thunder.CreateZoneRequest{
	DisplayName: "production",
})

err = client.DeleteZone(ctx, zone.ZoneID)

Read and replace zone GPU oversubscription targets:

targets, err := client.ListZoneOversubscriptionTargets(ctx, "zone-1")

updated, err := client.SetZoneOversubscriptionTargets(ctx, "zone-1", []thunder.ZoneOversubscriptionTarget{
	{GPUType: "nvidia-l4", OversubscriptionTarget: 2.5},
})

Generate install commands for enrollment:

cmd := client.ServerEnrollmentCommand(thunder.ServerEnrollmentCommandRequest{
	EnrollmentToken: token.EnrollmentToken,
	ServerName:      "worker-1",
})
fmt.Println(cmd)

Errors

Non-2xx API responses are returned as *thunder.APIError. Helper functions are available for common status checks:

if thunder.IsForbidden(err) {
	// The API token is valid but lacks the required capability.
}

API Token Capabilities

Thunder Central API tokens need the capabilities required by the operation being called. The SDK exports capability constants such as CapabilityCreateClientEnrollmentToken, CapabilityReadZones, and CapabilityWriteZones so integrations can keep their setup code and documentation aligned with the API surface they use.

Development

Run the test suite with:

go test ./...

If you are working inside Thunder's Bazel workspace, the equivalent target is:

bazel test //thunder-sdk:thunder_test

This module has no third-party Go dependencies.

Versioning

Public releases should be tagged with semantic versions, for example v0.1.0. Consumers can then pin a release with:

go get github.com/Thunder-Compute/thunder-sdk@v0.1.0

Documentation

Overview

Package thunder provides a typed client for Central's organization API-token bearer interface.

The SDK intentionally covers the automation surface used by thunderd clients: creating client and server enrollment tokens, deleting servers by enrollment token, listing and revoking registered clients and servers, creating/listing zones, and managing zone GPU oversubscription targets.

Index

Constants

View Source 
const (
	DefaultBaseURL    = "https://api.thundercompute.com:2096"
	DefaultInstallURL = "https://get.thundercompute.com/install.sh"

	RoleClient = "client"
	RoleServer = "server"

	CapabilityCreateClientEnrollmentToken = "client_enrollment_tokens:create"
	CapabilityCreateServerEnrollmentToken = "server_enrollment_tokens:create"
	CapabilityRevokeClient                = "clients:revoke"
	CapabilityRevokeHost                  = "hosts:revoke"
	CapabilityReadHosts                   = "hosts:read"
	CapabilityReadClients                 = "clients:read"
	CapabilityReadZones                   = "zones:read"
	CapabilityWriteZones                  = "zones:write"
	CapabilityDeleteZone                  = "zones:delete"
	CapabilityCreateZone                  = "zones:create"
)

Variables

This section is empty.

Functions

func IsConflict 

func IsConflict(err error) bool

func IsForbidden 

func IsForbidden(err error) bool

func IsNotFound 

func IsNotFound(err error) bool

func IsPermanent 

func IsPermanent(err error) bool

func IsUnauthorized 

func IsUnauthorized(err error) bool

Types

type APIError 

type APIError struct {
	Method     string
	Path       string
	StatusCode int
	Status     string
	ErrorType  string `json:"error"`
	Message    string `json:"message"`
}

APIError is returned when Central responds with a non-2xx status.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) IsConflict 

func (e *APIError) IsConflict() bool

func (*APIError) IsForbidden 

func (e *APIError) IsForbidden() bool

func (*APIError) IsNotFound 

func (e *APIError) IsNotFound() bool

func (*APIError) IsPermanent 

func (e *APIError) IsPermanent() bool

IsPermanent reports whether retrying the same request should not help.

func (*APIError) IsUnauthorized 

func (e *APIError) IsUnauthorized() bool

type Client 

type Client struct {
	ClientID         string     `json:"clientId"`
	ZoneID           string     `json:"zoneId"`
	DisplayName      string     `json:"displayName"`
	GPUType          string     `json:"gpuType"`
	GPUCount         uint32     `json:"gpuCount"`
	CreatedAt        time.Time  `json:"createdAt"`
	UpdatedAt        time.Time  `json:"updatedAt"`
	LastSeenAt       *time.Time `json:"lastSeenAt,omitempty"`
	DecommissionedAt *time.Time `json:"decommissionedAt,omitempty"`
}

type ClientEnrollmentCommandRequest 

type ClientEnrollmentCommandRequest struct {
	EnrollmentToken    string
	EnrollmentTokenEnv string
}

type CreateClientEnrollmentRequest 

type CreateClientEnrollmentRequest struct {
	ZoneID           string `json:"zoneId"`
	GPUType          string `json:"gpuType"`
	GPUCount         uint64 `json:"gpuCount"`
	ExpiresInSeconds int64  `json:"expiresInSeconds,omitempty"`
}

type CreateServerEnrollmentRequest 

type CreateServerEnrollmentRequest struct {
	ZoneID           string `json:"zoneId"`
	ExpiresInSeconds int64  `json:"expiresInSeconds,omitempty"`
}

type CreateZoneRequest 

type CreateZoneRequest struct {
	DisplayName string `json:"displayName,omitempty"`
}

type CreateZoneResponse 

type CreateZoneResponse struct {
	ZoneID      string `json:"zoneId"`
	OrgID       string `json:"orgId,omitempty"`
	DisplayName string `json:"displayName"`
}

type DeleteEnrollmentServerResponse 

type DeleteEnrollmentServerResponse struct {
	EnrollmentTokenID string    `json:"enrollmentTokenId"`
	Role              string    `json:"role"`
	ClientID          string    `json:"clientId,omitempty"`
	ServerID          string    `json:"hostId,omitempty"`
	ServerDeleted     bool      `json:"nodeDeleted"`
	DeletedAt         time.Time `json:"deletedAt"`
}

type EnrollmentToken 

type EnrollmentToken struct {
	EnrollmentTokenID string     `json:"enrollmentTokenId"`
	EnrollmentToken   string     `json:"enrollmentToken"`
	OrgID             string     `json:"orgId"`
	ZoneID            string     `json:"zoneId,omitempty"`
	Role              string     `json:"role"`
	GPUType           string     `json:"gpuType,omitempty"`
	GPUCount          uint32     `json:"gpuCount,omitempty"`
	ExpiresAt         *time.Time `json:"expiresAt,omitempty"`
}

type Option 

type Option func(*Thunder)

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

func WithInstallURL 

func WithInstallURL(installURL string) Option

func WithUserAgent 

func WithUserAgent(userAgent string) Option

type RevokeClientResponse 

type RevokeClientResponse struct {
	ClientID         string    `json:"clientId"`
	DecommissionedAt time.Time `json:"decommissionedAt"`
}

type RevokeServerResponse 

type RevokeServerResponse struct {
	ServerID  string    `json:"hostId"`
	RevokedAt time.Time `json:"revokedAt"`
}

type Server 

type Server struct {
	ServerID        string               `json:"hostId"`
	ZoneID          string               `json:"zoneId"`
	DisplayName     string               `json:"displayName"`
	Hostname        string               `json:"hostname"`
	IP              string               `json:"ip"`
	ThunderdVersion *string              `json:"thunderdVersion,omitempty"`
	GPUType         string               `json:"gpuType"`
	GPUCount        uint32               `json:"gpuCount"`
	Status          string               `json:"status"`
	LastSeenAt      *time.Time           `json:"lastSeenAt,omitempty"`
	Configurations  ServerConfigurations `json:"configurations"`
}

type ServerConfigurations added in v0.2.0 

type ServerConfigurations struct {
	Cordoned bool `json:"cordoned"`
}

ServerConfigurations contains operator-declared controls that affect how the control plane uses a server independently of its reported health.

type ServerEnrollmentCommandRequest 

type ServerEnrollmentCommandRequest struct {
	EnrollmentToken string
	IP              string
	Zone            string
	PortRange       string
	ServerName      string
}

type Thunder added in v0.3.0 

type Thunder struct {
	// contains filtered or unexported fields
}

Thunder is a typed SDK over Central's organization API-token bearer surface.

func NewThunder added in v0.3.0 

func NewThunder(baseURL, apiToken string, opts ...Option) *Thunder

func (*Thunder) ClientEnrollmentCommand added in v0.3.0 

func (c *Thunder) ClientEnrollmentCommand(enrollmentToken string) string

func (*Thunder) ClientEnrollmentCommandFor added in v0.3.0 

func (c *Thunder) ClientEnrollmentCommandFor(req ClientEnrollmentCommandRequest) string

func (*Thunder) CreateClientEnrollment added in v0.3.0 

func (c *Thunder) CreateClientEnrollment(ctx context.Context, req CreateClientEnrollmentRequest) (EnrollmentToken, error)

func (*Thunder) CreateServerEnrollment added in v0.3.0 

func (c *Thunder) CreateServerEnrollment(ctx context.Context, req CreateServerEnrollmentRequest) (EnrollmentToken, error)

func (*Thunder) CreateZone added in v0.3.0 

func (c *Thunder) CreateZone(ctx context.Context, req CreateZoneRequest) (CreateZoneResponse, error)

func (*Thunder) DeleteEnrollmentServer added in v0.3.0 

func (c *Thunder) DeleteEnrollmentServer(ctx context.Context, enrollmentTokenID string) (DeleteEnrollmentServerResponse, error)

func (*Thunder) DeleteZone added in v0.3.0 

func (c *Thunder) DeleteZone(ctx context.Context, zoneID string) error

func (*Thunder) EnrollClient added in v0.3.0 

func (c *Thunder) EnrollClient(ctx context.Context, req CreateClientEnrollmentRequest) (EnrollmentToken, error)

func (*Thunder) EnrollServer added in v0.3.0 

func (c *Thunder) EnrollServer(ctx context.Context, req CreateServerEnrollmentRequest) (EnrollmentToken, error)

func (*Thunder) ListClients added in v0.3.0 

func (c *Thunder) ListClients(ctx context.Context, zoneID string) ([]Client, error)

func (*Thunder) ListServers added in v0.3.0 

func (c *Thunder) ListServers(ctx context.Context, zoneID string) ([]Server, error)

func (*Thunder) ListZoneOversubscriptionTargets added in v0.3.0 

func (c *Thunder) ListZoneOversubscriptionTargets(ctx context.Context, zoneID string) (ZoneOversubscriptionTargetsResponse, error)

func (*Thunder) ListZones added in v0.3.0 

func (c *Thunder) ListZones(ctx context.Context) ([]Zone, error)

func (*Thunder) RevokeClient added in v0.3.0 

func (c *Thunder) RevokeClient(ctx context.Context, clientID string) (RevokeClientResponse, error)

func (*Thunder) RevokeServer added in v0.3.0 

func (c *Thunder) RevokeServer(ctx context.Context, serverID string) (RevokeServerResponse, error)

func (*Thunder) ServerEnrollmentCommand added in v0.3.0 

func (c *Thunder) ServerEnrollmentCommand(req ServerEnrollmentCommandRequest) string

func (*Thunder) SetZoneOversubscriptionTargets added in v0.3.0 

func (c *Thunder) SetZoneOversubscriptionTargets(ctx context.Context, zoneID string, targets []ZoneOversubscriptionTarget) (ZoneOversubscriptionTargetsResponse, error)

func (*Thunder) UnenrollClient added in v0.3.0 

func (c *Thunder) UnenrollClient(ctx context.Context, enrollmentTokenID string) (DeleteEnrollmentServerResponse, error)

func (*Thunder) UnenrollServer added in v0.3.0 

func (c *Thunder) UnenrollServer(ctx context.Context, enrollmentTokenID string) (DeleteEnrollmentServerResponse, error)

type Zone 

type Zone struct {
	ZoneID      string    `json:"zoneId"`
	DisplayName string    `json:"displayName"`
	ServerCount int       `json:"nodeCount"`
	ClientCount int       `json:"clientCount"`
	CreatedAt   time.Time `json:"createdAt"`
}

type ZoneOversubscriptionTarget 

type ZoneOversubscriptionTarget struct {
	GPUType                string  `json:"gpuType"`
	OversubscriptionTarget float64 `json:"oversubscriptionTarget"`
}

type ZoneOversubscriptionTargetsResponse 

type ZoneOversubscriptionTargetsResponse struct {
	OversubscriptionTargets       []ZoneOversubscriptionTarget `json:"oversubscriptionTargets"`
	DefaultOversubscriptionTarget float64                      `json:"defaultOversubscriptionTarget"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.