Copy page

Client libraries

Go SDK

The Unikraft Cloud Go SDK is an autogenerated client library that interfaces with the Unikraft Cloud platform API, based on the public OpenAPI specification at https://github.com/unikraft-cloud/openapi.

Installation

Code
go get unikraft.com/cloud/sdk

Requires Go 1.25 or later.

Quickstart

Code
package main

import (
  "context"
  "fmt"

  "unikraft.com/cloud/sdk/platform"
)

func main() {
  ctx := context.Background()

  // Create a new client. The token and default metro are automatically
  // read from environment variables (UKC_TOKEN and UKC_METRO).
  client := platform.NewClient()

  // List all instances
  resp, err := client.GetInstances(ctx, nil, nil)
  if err != nil {
    panic(err)
  }

  // Check for API-level errors
  if resp.Status != "success" {
    panic(resp.Message)
  }

  for _, inst := range resp.Data.Instances {
    fmt.Printf("Name:  %s\n", *inst.Name)
    fmt.Printf("UUID:  %s\n", *inst.Uuid)
    fmt.Printf("State: %s\n", *inst.State)
    fmt.Printf("Image: %s\n", *inst.Image)
    fmt.Println("---")
  }
}

Authentication

Pass your token via platform.WithToken():

Code
client := platform.NewClient(
    platform.WithToken("your-api-token"),
)

Or set one of the following environment variables. NewClient reads them automatically in order of preference:

1. UKC_TOKEN
2. UNIKRAFT_CLOUD_TOKEN
3. KRAFTCLOUD_TOKEN (legacy name)

You can also set the default metro via the UKC_METRO environment variable. If not specified, the SDK defaults to fra.

Code
// No WithToken/WithDefaultMetro needed, NewClient reads the environment automatically
client := platform.NewClient()

Client options

Option	Description
WithDefaultEndpoint(string)	Full API endpoint address (for example, https://api.fra.unikraft.cloud)
WithDefaultMetro(string)	Metro shorthand—converted to endpoint address automatically
WithToken(string)	API token
WithHTTPClient(...)	Custom http.Client
WithUserAgent(string)	Override the User-Agent header
WithAllowInsecure(bool)	Skip TLS verification (development only)

WithDefaultEndpoint and WithDefaultMetro both set the API endpoint. Use WithDefaultMetro("fra") as a shorthand for WithDefaultEndpoint("https://api.fra.unikraft.cloud").

The base address is https://api.<metro>.unikraft.cloud.

Resources

The platform.Client interface covers the full Unikraft Cloud REST API surface.

Instances

Code
// Create
client.CreateInstance(ctx, req)

Code
// Read
client.GetInstances(ctx, ids, details)
client.GetInstanceByUUID(ctx, uuid, details)

Code
// Start / Stop
client.StartInstanceByUUID(ctx, uuid)
client.StartInstances(ctx, ids)
client.StopInstanceByUUID(ctx, uuid, req)
client.StopInstances(ctx, req)

Code
// Update
client.UpdateInstanceByUUID(ctx, uuid, req)
client.UpdateInstances(ctx, req)

Code
// Delete
client.DeleteInstanceByUUID(ctx, uuid)
client.DeleteInstances(ctx, ids)

Code
// Logs and metrics
client.GetInstanceLogsByUUID(ctx, uuid, req)
client.GetInstanceLogs(ctx, req)
client.GetInstanceMetricsByUUID(ctx, uuid)
client.GetInstanceMetrics(ctx, ids)

Code
// Wait for a target state
client.WaitInstanceByUUID(ctx, uuid, req)
client.WaitInstances(ctx, req)

Instance templates

Code
// Create
client.CreateTemplateInstances(ctx, req)

Code
// Read
client.GetTemplateInstances(ctx, ids, details, count, tags)
client.GetTemplateInstanceByUUID(ctx, uuid, details)

Code
// Update
client.UpdateTemplateInstanceByUUID(ctx, uuid, req)
client.UpdateTemplateInstances(ctx, req)

Code
// Delete
client.DeleteTemplateInstanceByUUID(ctx, uuid)
client.DeleteTemplateInstances(ctx, ids)

Service groups

Code
// Create
client.CreateServiceGroup(ctx, req)

Code
// Read
client.GetServiceGroups(ctx, ids, details)
client.GetServiceGroupByUUID(ctx, uuid, details)

Code
// Update
client.UpdateServiceGroupByUUID(ctx, uuid, req)
client.UpdateServiceGroups(ctx, req)

Code
// Delete
client.DeleteServiceGroupByUUID(ctx, uuid)
client.DeleteServiceGroups(ctx, ids)

Autoscale

Code
// Configuration (by service group UUID)
client.CreateAutoscaleConfigurationByServiceGroupUUID(ctx, uuid, req)
client.GetAutoscaleConfigurationsByServiceGroupUUID(ctx, uuid)
client.DeleteAutoscaleConfigurationsByServiceGroupUUID(ctx, uuid)

Code
// Configuration (batch)
client.CreateAutoscaleConfigurations(ctx, req)
client.GetAutoscaleConfigurations(ctx, ids)
client.DeleteAutoscaleConfigurations(ctx, ids)

Code
// Policies
client.CreateAutoscaleConfigurationPolicy(ctx, uuid, req)
client.GetAutoscaleConfigurationPolicies(ctx, uuid, req)
client.GetAutoscaleConfigurationPolicyByName(ctx, uuid, name)
client.DeleteAutoscaleConfigurationPolicies(ctx, uuid, req)
client.DeleteAutoscaleConfigurationPolicyByName(ctx, uuid, name)

Volumes

Code
// Create
client.CreateVolume(ctx, req)

Code
// Read
client.GetVolumes(ctx, ids, details)
client.GetVolumeByUUID(ctx, uuid, details)

Code
// Attach / Detach
client.AttachVolumeByUUID(ctx, uuid, req)
client.AttachVolumes(ctx, req)
client.DetachVolumeByUUID(ctx, uuid, req)
client.DetachVolumes(ctx, req)

Code
// Clone
client.CloneVolumeByUUID(ctx, uuid, req)
client.CloneVolumes(ctx, req)

Code
// Update
client.UpdateVolumeByUUID(ctx, uuid, req)
client.UpdateVolumes(ctx, req)

Code
// Delete
client.DeleteVolumeByUUID(ctx, uuid)
client.DeleteVolumes(ctx, ids)

Certificates

Code
// Create
client.CreateCertificate(ctx, req)

Code
// Read
client.GetCertificates(ctx, ids, details)
client.GetCertificateByUUID(ctx, uuid)

Code
// Delete
client.DeleteCertificateByUUID(ctx, uuid)
client.DeleteCertificates(ctx, ids)

Images

Code
// Read
client.GetImages(ctx, req, namespace)

Users and quotas

Code
// Read quotas
client.GetUser(ctx)
client.GetUserByUUID(ctx, uuid)

Code
// Create users
client.AddUsers(ctx)

Health

Code
// Check node health
client.Healthz(ctx)

Source

The SDK source and full API reference are available at github.com/unikraft-cloud/go-sdk and pkg.go.dev/unikraft.com/cloud/sdk.