# 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

```bash title=""
go get unikraft.com/cloud/sdk
```

Requires Go 1.25 or later.

## Quickstart

```go title="main.go"
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()`:

```go title=""
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`.

```go title=""
// 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

```go
// Create
client.CreateInstance(ctx, req)
```

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

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

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

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

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

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

### Instance templates

```go
// Create
client.CreateTemplateInstances(ctx, req)
```

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

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

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

### Service groups

```go
// Create
client.CreateServiceGroup(ctx, req)
```

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

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

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

### Autoscale

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

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

```go
// 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

```go
// Create
client.CreateVolume(ctx, req)
```

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

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

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

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

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

### Certificates

```go
// Create
client.CreateCertificate(ctx, req)
```

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

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

### Images

```go
// Read
client.GetImages(ctx, req, namespace)
```

### Users and quotas

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

```go
// Create users
client.AddUsers(ctx)
```

### Health

```go
// Check node health
client.Healthz(ctx)
```

## Source

The SDK source and full API reference are available at
[github.com/unikraft-cloud/go-sdk](https://github.com/unikraft-cloud/go-sdk)
and [pkg.go.dev/unikraft.com/cloud/sdk](https://pkg.go.dev/unikraft.com/cloud/sdk).