slicer

package module
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2025 License: MIT Imports: 15 Imported by: 1

README

Golang SDK for Slicer

SDK for SlicerVM.com

Installation

go get github.com/slicervm/sdk@latest

Example usage

Create a new slicer config:

slicer new api \
    --count=0 \
    --graceful-shutdown=false \
    --ram 4 \
    --cpu 2 > api.yaml

Create a VM (node) in a host group with the default RAM/CPU settings as defined in the host group.

package main

import (
    "fmt"
    "os"
    sdk "github.com/slicervm/sdk"
)

func main() {
    // Typically you'd load these from environment variables
    baseURL := os.Getenv("SLICER_URL")      // API base URL
    token := os.Getenv("SLICER_TOKEN")      // Your API token
    userAgent := "my-microvm-client/1.0"
    hostGroup := "api"                       // Existing host group name

    client := sdk.NewSlicerClient(baseURL, token, userAgent, nil /* or &http.Client{} */)

    createReq := sdk.SlicerCreateNodeRequest{
        RAMGB:      4,
        CPUs:       2,
        Userdata: `#!/bin/bash
echo 'Bootstrapping...'
ping -c3 google.com

sudo reboot
`,
        SSHKeys: []string{"ssh-rsa AAAA..."}, // Optional: inject public SSH keys
        ImportUser: "alexellis", // Optional: Import GitHub keys for a specific user
    }

    res, err := client.CreateNode(hostGroup, createReq)
    if err != nil {
        panic(fmt.Errorf("failed to create node: %w", err))
    }

    fmt.Printf("Created VM: hostname=%s ip=%s created_at=%s\n", res.Hostname, res.IP, res.CreatedAt)
    fmt.Printf("Parsed IP only: %s\n", res.IPAddress())
}

Start Slicer:

sudo -E slicer up ./api.yaml

Run the program i.e. after running go build -o client main.go:

SLICER_URL=http://127.0.0.1:8080 SLICER_TOKEN="$(sudo cat /var/lib/slicer/auth/token)" ./client

You'll find the logs for the microVM at /var/log/slicer/HOSTNAME.txt, showing the userdata executing.

Notes:

  • The argument order for NewSlicerClient is (baseURL, token, userAgent, httpClient).
  • RAMGB, CPUs, and ImportUser should be set; Userdata and SSHKeys are optional.
  • Userdata runs on first boot; keep it idempotent.
  • Use a persistent http.Client (e.g. with timeout) in production instead of nil.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSecretExists is an error returned when a secret with given name already exists.
	ErrSecretExists = errors.New("secret already exists")
)

Functions

This section is empty.

Types

type CreateSecretRequest added in v0.0.6 

type CreateSecretRequest struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Data is the secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions (defaults to system default)
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

CreateSecretRequest is the payload for creating a new secret via the REST API.

type Secret added in v0.0.6 

type Secret struct {
	// Name is the unique name of the secret
	Name string `json:"name"`
	// Size is the size of the secret data in bytes
	Size int64 `json:"size"`
	// Permissions specifies the file permissions for the secret (e.g., "0600")
	Permissions string `json:"permissions"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`

	// ModifiedAt is the time the secret was last modified
	ModifiedAt *time.Time `json:"modified_at,omitempty"`
}

Secret represents a secret stored in the slicer system. Secrets can be used to store sensitive configuration data, keys, or other private information that can be mounted into nodes or used by services.

type SlicerClient 

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

SlicerClient handles all HTTP communication with the Slicer API

func NewSlicerClient 

func NewSlicerClient(baseURL, token string, userAgent string, httpClient *http.Client) *SlicerClient

NewSlicerClient creates a new Slicer API client

func (*SlicerClient) CreateNode 

func (c *SlicerClient) CreateNode(ctx context.Context, groupName string, request SlicerCreateNodeRequest) (*SlicerCreateNodeResponse, error)

CreateNode creates a new node in the specified host group

func (*SlicerClient) CreateSecret added in v0.0.6 

func (c *SlicerClient) CreateSecret(ctx context.Context, request CreateSecretRequest) error

CreateSecret creates a new secret. Returns ErrSecretExists if a secret with the same name already exists. An error is returned if creation fails.

func (*SlicerClient) DeleteNode 

func (c *SlicerClient) DeleteNode(groupName, nodeName string) error

DeleteNode deletes a node from the specified host group

func (*SlicerClient) DeleteSecret added in v0.0.6 

func (c *SlicerClient) DeleteSecret(ctx context.Context, secretName string) error

DeleteSecret removes a secret. Returns an error if the secret doesn't exist or if the deletion fails.

func (*SlicerClient) Exec added in v0.0.9 

func (c *SlicerClient) Exec(ctx context.Context, nodeName string, execReq SlicerExecRequest) (chan SlicerExecWriteResult, error)

Exec executes a command on the specified node and streams the output. The channel is unbuffered so the caller should read from it promptly to avoid blocking.

func (*SlicerClient) GetHostGroupNodes 

func (c *SlicerClient) GetHostGroupNodes(ctx context.Context, groupName string) ([]SlicerNode, error)

GetHostGroupNodes fetches nodes for a specific host group

func (*SlicerClient) GetHostGroups 

func (c *SlicerClient) GetHostGroups(ctx context.Context) ([]SlicerHostGroup, error)

GetHostGroups fetches all host groups from the API

func (*SlicerClient) ListSecrets added in v0.0.6 

func (c *SlicerClient) ListSecrets(ctx context.Context) ([]Secret, error)

ListSecrets retrieves all secrets. Note: The actual secret data is not returned for security reasons.

func (*SlicerClient) PatchSecret added in v0.0.6 

func (c *SlicerClient) PatchSecret(ctx context.Context, secretName string, request UpdateSecretRequest) error

PatchSecret updates an existing secret with new data and/or metadata. Only the fields provided in the UpdateSecretRequest will be modified. Returns an error if the secret doesn't exist or if the update fails.

type SlicerCreateNodeRequest 

type SlicerCreateNodeRequest struct {
	RamGB      int      `json:"ram_gb"`
	CPUs       int      `json:"cpus"`
	Tags       []string `json:"tags,omitempty"`
	ImportUser string   `json:"import_user"`
	Userdata   string   `json:"userdata,omitempty"`
	SSHKeys    []string `json:"ssh_keys,omitempty"`
	Secrets    []string `json:"secrets,omitempty"`
}

SlicerCreateNodeRequest is the payload for creating a node via the REST API.

type SlicerCreateNodeResponse 

type SlicerCreateNodeResponse struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
}

SlicerCreateNodeResponse is the response from the REST API when creating a node.

func (*SlicerCreateNodeResponse) IPAddress 

func (n *SlicerCreateNodeResponse) IPAddress() net.IP

type SlicerExecRequest added in v0.0.9 

type SlicerExecRequest struct {
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	UID     uint32   `json:"uid,omitempty"`
	GID     uint32   `json:"gid,omitempty"`
	Stdin   bool     `json:"stdin,omitempty"`
	Stdout  bool     `json:"stdout,omitempty"`
	Stderr  bool     `json:"stderr,omitempty"`
	Shell   string   `json:"shell,omitempty"`
}

SlicerExecRequest contains parameters for invoking a command within a VM.

type SlicerExecWriteResult added in v0.0.9 

type SlicerExecWriteResult struct {
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
	ExitCode int    `json:"exit_code,omitempty"`
	Error    string `json:"error,omitempty"`
}

ExecWriteResult represents output from commands executing within a microVM.

type SlicerHostGroup 

type SlicerHostGroup struct {
	Name     string `json:"name"`
	Count    int    `json:"count"`
	RamGB    int    `json:"ram_gb"`
	CPUs     int    `json:"cpus"`
	Arch     string `json:"arch,omitempty"`
	GPUCount int    `json:"gpu_count,omitempty"`
}

SlicerHostGroup represents a host group from the /hostgroup endpoint.

type SlicerNode 

type SlicerNode struct {
	Hostname  string    `json:"hostname"`
	IP        string    `json:"ip"`
	CreatedAt time.Time `json:"created_at"`
	Arch      string    `json:"arch,omitempty"`
	Tags      []string  `json:"tags,omitempty"`
}

SlicerNode represents a node managed by the slicer REST API.

type UpdateSecretRequest added in v0.0.6 

type UpdateSecretRequest struct {
	// Data is the updated secret content
	Data string `json:"data"`
	// Permissions specifies the file permissions
	Permissions string `json:"permissions,omitempty"`

	// GID is the user ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	UID uint32 `json:"uid,omitempty"`

	// GID is the group ID that should own the secret file. If not set, the default for
	// a uint32 will be used i.e root.
	GID uint32 `json:"gid,omitempty"`
}

UpdateSecretRequest is the payload for updating an existing secret via the REST API. All fields are optional - only provided fields will be updated.

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.