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.27 or later.

Quickstart

main.go
package main

import (
  "context"
  "fmt"

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

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

  // Create a new client. NewClientFromEnv reads the token and default metro
  // from environment variables (UKC_TOKEN and UKC_METRO).
  client := platform.NewClientFromEnv()

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

  // Check for API-level errors
  if resp.Status != platform.ResponseStatusSuccess {
    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"),
)

NewClient uses only the options you pass and doesn't read the environment.

To configure the client from the environment, use NewClientFromEnv. It reads the token from the first of these environment variables that's set:

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

It also reads the default metro from the UKC_METRO environment variable. If not specified, the SDK defaults to fra. Options you pass to NewClientFromEnv take precedence over the environment.

Code
// Reads UKC_TOKEN (or a fallback) and UKC_METRO from the environment
client := platform.NewClientFromEnv()

Client options

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.

An existing client also has methods that return a client with one setting changed:

Code
// Query another metro with the same token
resp, err := client.WithMetro("sfo").GetInstances(ctx, nil, platform.GetInstancesOpts{})

Resources

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

In the examples below:

• ids is a []platform.NameOrUUID that selects resources by name or UUID. Passing nil to a list method, such as GetInstances or GetVolumes, returns all resources. The autoscale read methods are the exception and need at least one service group.
• req is the request type that the method takes, for example platform.CreateInstanceRequest or []platform.StartInstancesRequestItem.
• platform.<Method>Opts{} holds the optional query parameters, for example platform.GetInstancesOpts{Details: &details, Tags: []string{"production"}}.

Instances

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

Code
// Read
client.GetInstances(ctx, ids, platform.GetInstancesOpts{})
client.GetInstanceByUUID(ctx, uuid, platform.GetInstanceByUUIDOpts{})

Code
// Start / Stop / Suspend
client.StartInstanceByUUID(ctx, uuid, platform.StartInstanceByUUIDRequestBody{})
client.StartInstances(ctx, req)
client.StopInstanceByUUID(ctx, uuid, platform.StopInstanceByUUIDRequestBody{})
client.StopInstances(ctx, req)
client.SuspendInstanceByUUID(ctx, uuid, platform.SuspendInstanceByUUIDRequestBody{})
client.SuspendInstances(ctx, req)

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

Code
// Delete
client.DeleteInstanceByUUID(ctx, uuid, platform.DeleteInstanceByUUIDRequestBody{})
client.DeleteInstances(ctx, req)

Code
// Logs and metrics
client.GetInstanceLogsByUUID(ctx, uuid, platform.GetInstanceLogsByUUIDRequestBody{})
client.GetInstanceLogs(ctx, req, platform.GetInstanceLogsOpts{})
client.GetInstanceMetricsByUUID(ctx, uuid)
client.GetInstanceMetrics(ctx, ids, platform.GetInstanceMetricsOpts{})

Code
// History
client.GetInstanceHistoryByUUID(ctx, uuid)
client.GetInstanceHistory(ctx, ids, platform.GetInstanceHistoryOpts{})

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

Instance templates

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

Code
// Read
client.GetTemplateInstances(ctx, ids, platform.GetTemplateInstancesOpts{})
client.GetTemplateInstanceByUUID(ctx, uuid, platform.GetTemplateInstanceByUUIDOpts{})

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

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

Instance checkpoints

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

Code
// Read
client.GetCheckpointInstances(ctx, ids, platform.GetCheckpointInstancesOpts{})
client.GetCheckpointInstanceByUUID(ctx, uuid, platform.GetCheckpointInstanceByUUIDOpts{})

Code
// History
client.GetCheckpointHistoryByUUID(ctx, uuid)
client.GetCheckpointHistory(ctx, ids, platform.GetCheckpointHistoryOpts{})

Code
// Update
client.UpdateCheckpointInstanceByUUID(ctx, uuid, req)
client.UpdateCheckpointInstances(ctx, req)

Code
// Delete
client.DeleteCheckpointInstanceByUUID(ctx, uuid)
client.DeleteCheckpointInstances(ctx, ids)

Service groups

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

Code
// Read
client.GetServiceGroups(ctx, ids, platform.GetServiceGroupsOpts{})
client.GetServiceGroupByUUID(ctx, uuid, platform.GetServiceGroupByUUIDOpts{})

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, platform.GetAutoscaleConfigurationsOpts{})
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, platform.GetVolumesOpts{})
client.GetVolumeByUUID(ctx, uuid, platform.GetVolumeByUUIDOpts{})

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)

Volume templates

Code
// Create a template from existing volumes
client.CreateTemplateVolume(ctx, ids)

Code
// Read
client.GetTemplateVolumes(ctx, ids, platform.GetTemplateVolumesOpts{})
client.GetTemplateVolumeByUUID(ctx, uuid, platform.GetTemplateVolumeByUUIDOpts{})

Code
// Update
client.UpdateTemplateVolumeByUUID(ctx, uuid, req)
client.UpdateTemplateVolumes(ctx, req)

Code
// Delete
client.DeleteTemplateVolumeByUUID(ctx, uuid)
client.DeleteTemplateVolumes(ctx, ids)

Certificates

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

Code
// Read
client.GetCertificates(ctx, ids, platform.GetCertificatesOpts{})
client.GetCertificateByUUID(ctx, uuid)

Code
// Update
client.UpdateCertificateByUUID(ctx, uuid, req)
client.UpdateCertificates(ctx, req)

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

Images

In the image methods, req is a list of image references ([]platform.GetImagesRequestTagOrDigest, []platform.PinImageRequestItem or []platform.UnpinImageRequestItem).

Code
// Read
client.GetImages(ctx, req, platform.GetImagesOpts{})
client.GetImageStore(ctx, req, platform.GetImageStoreOpts{})

Code
// Pin / Unpin
client.PinImages(ctx, req)
client.UnpinImages(ctx, req)

Users and quotas

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

Audit events

SubscribeAuditEvents streams audit events on a channel:

Code
events, err := client.SubscribeAuditEvents(ctx, platform.SubscribeAuditEventsOpts{})
if err != nil {
    panic(err)
}
for event := range events {
    fmt.Println(event)
}

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.