diff --git a/g3doc/user_guide/sdk/BUILD b/g3doc/user_guide/sdk/BUILD new file mode 100644 index 0000000000..86f1b24837 --- /dev/null +++ b/g3doc/user_guide/sdk/BUILD @@ -0,0 +1,25 @@ +load("//website:defs.bzl", "doc") + +package( + default_applicable_licenses = ["//:license"], + default_visibility = ["//website:__pkg__"], + licenses = ["notice"], +) + +doc( + name = "go", + src = "go.md", + category = "SDK/API Reference", + permalink = "/docs/sdk/go/", + subcategory = "Go", + weight = "10", +) + +doc( + name = "quickstart", + src = "quickstart.md", + category = "SDK/API Reference", + permalink = "/docs/sdk/go/quickstart/", + subcategory = "Go", + weight = "20", +) diff --git a/g3doc/user_guide/sdk/go.md b/g3doc/user_guide/sdk/go.md new file mode 100644 index 0000000000..f124e87733 --- /dev/null +++ b/g3doc/user_guide/sdk/go.md @@ -0,0 +1,136 @@ +# API Reference + +> [!WARNING] **EXPERIMENTAL:** The APIs and tools described here are +> experimental and are **not meant for production use**. + +The gVisor Go SDK (package `sandbox`) provides a simple API for creating gVisor +sandboxes and executing commands inside them. + +To use the SDK, you must have `runsc` installed on your system. Refer to the +[Installation Guide](/docs/user_guide/install/) for instructions. + +## Import + +```go +import "gvisor.dev/gvisor/sandboxexec/sandbox" +``` + +## Functions + +### New + +```go +func New(ctx context.Context, opts ...Option) (*Sandbox, error) +``` + +Spawns a new sandbox as a subprocess. The sandbox will be started and running in +detached mode. + +**Parameters:** + +* `ctx`: Context for the execution. +* `opts`: Variadic list of options to configure the sandbox. + +**Returns:** + +* `*Sandbox`: A pointer to the created `Sandbox` object. +* `error`: An error if the sandbox creation fails. + +## Types + +### Sandbox + +`Sandbox` represents a running gVisor sandbox. + +#### Exec + +```go +func (s *Sandbox) Exec(ctx context.Context, cmd string, opts ...string) (stdout string, stderr string, err error) +``` + +Runs commands inside the running sandbox as long as the Sandbox is running. + +**Parameters:** + +* `ctx`: Context for the execution. +* `cmd`: The command to execute (e.g., `"uname"`, `"ls"`). +* `opts`: Arguments for the command. + +**Returns:** + +* `stdout`: Standard output of the command. +* `stderr`: Standard error of the command. +* `err`: Error if the execution fails. + +#### Close + +```go +func (s *Sandbox) Close(ctx context.Context) error +``` + +Kills the sandbox processes and cleans up the state directory. + +**Parameters:** + +* `ctx`: Context for the execution. + +**Returns:** + +* `error`: An error if cleanup fails. + +#### Bundle + +```go +func (s *Sandbox) Bundle() string +``` + +Returns the path to the OCI bundle directory for this sandbox. + +### Option + +`Option` is a function type used to configure a sandbox. + +```go +type Option func(*Options) +``` + +### Options + +`Options` holds the configuration for a Sandbox. + +```go +type Options struct { + // Has unexported fields +} +``` + +### WithRuntimeDir + +```go +func WithRuntimeDir(runtimeDir string) Option +``` + +Sets a custom runtime directory where bundle and state files are written. + +### WithID + +```go +func WithID(id string) Option +``` + +Sets a specific sandbox ID. If not set, a unique ID will be generated +automatically. + +### WithNetworking + +```go +func WithNetworking(enabled bool) Option +``` + +Configures whether networking is enabled inside the sandbox. + +> [!IMPORTANT] Enabling networking requires running as root. + +-------------------------------------------------------------------------------- + +For a practical example, see the [Quickstart](/docs/sdk/go/quickstart/). diff --git a/g3doc/user_guide/sdk/quickstart.md b/g3doc/user_guide/sdk/quickstart.md new file mode 100644 index 0000000000..46c9ca6df6 --- /dev/null +++ b/g3doc/user_guide/sdk/quickstart.md @@ -0,0 +1,92 @@ +# Quickstart + +> [!WARNING] **EXPERIMENTAL:** The APIs and tools described here are +> experimental and are **not meant for production use**. + +This guide shows you how to get started with the gVisor Go SDK to run commands +inside a sandboxed environment. + +## Prerequisites + +1. **gVisor (runsc) Installed**: You must have `runsc` installed and available + in your `PATH`. See the [Installation Guide](/docs/user_guide/install/) for + details. +2. **Go Environment**: Ensure you have Go installed (version 1.16+ + recommended). + +## Example + +Here is a complete example of creating a sandbox, executing a command (`uname +-a`), and cleaning up the sandbox resources. + +```go +package main + +import ( + "context" + "fmt" + "log" + + "gvisor.dev/gvisor/sandboxexec/sandbox" +) + +func main() { + ctx := context.Background() + + // Initialize a new sandbox. + // Note: WithNetworking(true) requires running as root. + // For this quickstart, we disable networking to allow running as non-root. + sb, err := sandbox.New(ctx, sandbox.WithNetworking(false)) + if err != nil { + log.Fatalf("Failed to create sandbox: %v", err) + } + defer func() { + if err := sb.Close(ctx); err != nil { + log.Fatalf("Failed to close sandbox: %v", err) + } + }() + + // Execute a command inside the sandbox. + stdout, stderr, err := sb.Exec(ctx, "uname", "-a") + if err != nil { + log.Fatalf("Exec failed: %v, stderr: %s", err, stderr) + } + + fmt.Printf("Stdout: %s", stdout) +} +``` + +## Running the Example + +1. Save the code above as `main.go`. +2. Initialize a Go module: + + ```bash + go mod init gvisor-quickstart + ``` + +3. Add the dependency (replace with the actual public import path when + available): + + ```bash + go get gvisor.dev/gvisor/sandboxexec/sandbox + ``` + +4. Run the application: + + ```bash + go run main.go + ``` + +You should see output similar to: + +``` +Stdout: Linux 5.15.0-gvisor +``` + +This indicates the command successfully ran inside the gVisor sandbox, which +emulates a Linux kernel. + +-------------------------------------------------------------------------------- + +For detailed API documentation, see the [API Reference](/docs/sdk/go/). diff --git a/website/BUILD b/website/BUILD index 738b5a11c6..527cb376f1 100644 --- a/website/BUILD +++ b/website/BUILD @@ -180,6 +180,8 @@ docs( "//g3doc/user_guide/quick_start:docker", "//g3doc/user_guide/quick_start:kubernetes", "//g3doc/user_guide/quick_start:oci", + "//g3doc/user_guide/sdk:go", + "//g3doc/user_guide/sdk:quickstart", "//g3doc/user_guide/tutorials:cni", "//g3doc/user_guide/tutorials:docker", "//g3doc/user_guide/tutorials:docker_compose", diff --git a/website/_layouts/docs.html b/website/_layouts/docs.html index 5b95dc0711..7234e829cd 100644 --- a/website/_layouts/docs.html +++ b/website/_layouts/docs.html @@ -3,6 +3,7 @@ categories: - Project - User Guide + - SDK/API Reference - Architecture Guide - Compatibility --- @@ -20,8 +21,8 @@