Help us shape the future of Go! Take the 2026 Go Developer Survey

stack

package
v0.15.0-rc3 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// BackendK3d is the k3d backend (Docker-based, default)
	BackendK3d = "k3d"
	// BackendK3s is the standalone k3s backend (bare-metal)
	BackendK3s = "k3s"
)
View Source 
const (
	LinkRoot       = ""
	LinkOffer      = "offer"
	LinkStorefront = "storefront"
	LinkPurchases  = "purchases"
	LinkListings   = "listings"
	LinkAgent      = "agent"
)

Dashboard link kinds understood by DashboardURL.

View Source 
const (
	// MarkerUIOpened is written after the dashboard was auto-opened on the
	// first successful `obol stack up`.
	MarkerUIOpened = ".ui-opened"
	// MarkerFirstOfferOpened is written after the browser was auto-opened for
	// the first offer created on this stack.
	MarkerFirstOfferOpened = ".first-offer-opened"
)

First-run marker files (in cfg.ConfigDir) gating one-time browser opens.

Variables

This section is empty.

Functions

func ConfirmRunningServicesLoss added in v0.10.0 

func ConfirmRunningServicesLoss(cfg *config.Config, u *ui.UI, action string, skipConfirm bool) (bool, error)

ConfirmRunningServicesLoss warns the operator when a destructive action (`obol stack down` / `obol stack purge`) is about to tear down a cluster that is currently serving traffic, and asks whether to proceed.

Returns true when the caller should continue. The rules:

  • No live offers and no live gateways -> pass through (no prompt).
  • skipConfirm (operator passed --yes) -> pass through.
  • Interactive TTY -> render the list and ask `ui.Confirm` (default N).
  • Non-interactive without --yes -> return a non-nil error so the caller fails closed. This is the safety bar that prevents a stray `ssh host '<obol stack down>'` from a non-prod worktree wiping the production stack without an explicit operator decision.

func DashboardURL added in v0.15.0 

func DashboardURL(base, kind, ns, name string) string

DashboardURL builds a link into the local obol-stack front-end on top of base (normally LocalIngressURL). It only emits routes that exist in the front-end today: 

root        /
offer       /marketplace/<ns%2Fname>   ([slug] route: ONE path segment,
                                       "ns/name" percent-encoded; the
                                       page renders once the offer is
                                       Ready and in the published catalog)
storefront  /storefront
purchases   /marketplace/purchases
listings    /marketplace/listings      (all of this stack's offers,
                                       incl. not-yet-Ready ones)
agent       /                          (AgentInstanceCard ids are
                                       #agent-<runtime>-<id>, but cards
                                       render after a client fetch and
                                       nothing scrolls to the hash on
                                       load, so a deep anchor would be a
                                       no-op)

TODO(lean-stack §5): switch to the planned routes once the front-end ships them — /agents/<ns>/<name>, /marketplace/listings/<ns>/<name>, /marketplace/purchases/<ns>/<name>, /networks/<name>/<id>, /models.

func DetectExistingBackend added in v0.3.1 

func DetectExistingBackend(cfg *config.Config) string

DetectExistingBackend reads the persisted backend choice without falling back to a default. Returns empty string if no backend file exists, which lets Init() apply its own default.

func Down 

func Down(cfg *config.Config, u *ui.UI, skipConfirm bool) error

Down stops the cluster and the DNS resolver container.

func Init 

func Init(cfg *config.Config, u *ui.UI, force bool, backendName string, skipConfirm bool) error

Init initializes the stack configuration. skipConfirm (--yes) bypasses the live-services confirmation prompt when --force switches backends and would otherwise destroy a cluster serving live traffic (mirrors Down/Purge).

func LocalIngressURL added in v0.8.0 

func LocalIngressURL(cfg *config.Config) string

LocalIngressURL returns the best local HTTP base URL for the current stack. For k3d, it prefers the first host port mapped to container port 80 in the generated k3d config. For historical/default setups it falls back to http://obol.stack or http://obol.stack:8080.

func MarkerExists added in v0.15.0 

func MarkerExists(cfg *config.Config, name string) bool

MarkerExists reports whether the named first-run marker is present.

func OnFirstRun added in v0.15.0 

func OnFirstRun(cfg *config.Config, marker string, open func() bool) bool

OnFirstRun runs open unless the marker exists, and writes the marker only when open reports success — so a first run where no browser could be opened (SSH, headless, CI) does not burn the one-time open. Returns whether open ran and succeeded.

func PrintReady added in v0.15.0 

func PrintReady(cfg *config.Config, u *ui.UI)

PrintReady prints the "stack is up" banner. Callers print it after any post-Up work (recorded-state replay) so it is the last thing the user sees.

func Purge 

func Purge(cfg *config.Config, u *ui.UI, force, skipConfirm bool) error

Purge deletes the cluster config and optionally data

func SaveBackend added in v0.3.1 

func SaveBackend(cfg *config.Config, name string) error

SaveBackend persists the backend choice

func Up 

func Up(cfg *config.Config, u *ui.UI, wildcardDNS bool) error

Up starts the cluster using the configured backend

func WriteMarker added in v0.15.0 

func WriteMarker(cfg *config.Config, name string) error

WriteMarker records the named first-run marker. Best-effort: a failure only means the one-time action may repeat.

Types

type Backend added in v0.3.1 

type Backend interface {
	// Name returns the backend identifier (e.g., "k3d", "k3s")
	Name() string

	// Init generates backend-specific cluster configuration files.
	// force is true when the caller is about to tear down and recreate the
	// existing cluster (obol stack init --force); backends may use it to
	// treat ports currently held by that cluster as non-conflicting.
	Init(cfg *config.Config, u *ui.UI, stackID string, force bool) error

	// Up creates or starts the cluster and returns kubeconfig contents
	Up(cfg *config.Config, u *ui.UI, stackID string) (kubeconfigData []byte, err error)

	// IsRunning returns true if the cluster is currently running
	IsRunning(cfg *config.Config, stackID string) (bool, error)

	// Down stops the cluster without destroying configuration or data
	Down(cfg *config.Config, u *ui.UI, stackID string) error

	// Destroy removes the cluster entirely (containers/processes)
	Destroy(cfg *config.Config, u *ui.UI, stackID string) error

	// DataDir returns the storage path for the local-path-provisioner.
	// For k3d this is "/data" (Docker volume mount point).
	// For k3s this is the absolute host path to cfg.DataDir.
	DataDir(cfg *config.Config) string

	// Prerequisites checks that required software/permissions are available
	Prerequisites(cfg *config.Config) error
}

Backend abstracts the Kubernetes cluster runtime (k3d, k3s)

func LoadBackend added in v0.3.1 

func LoadBackend(cfg *config.Config) (Backend, error)

LoadBackend reads the persisted backend choice from .stack-backend file. Falls back to k3d if no file exists (backward compatibility).

func NewBackend added in v0.3.1 

func NewBackend(name string) (Backend, error)

NewBackend creates a Backend by name

type K3dBackend added in v0.3.1 

type K3dBackend struct{}

K3dBackend manages clusters via k3d (k3s inside Docker containers)

func (*K3dBackend) DataDir added in v0.3.1 

func (b *K3dBackend) DataDir(cfg *config.Config) string

func (*K3dBackend) Destroy added in v0.3.1 

func (b *K3dBackend) Destroy(cfg *config.Config, u *ui.UI, stackID string) error

func (*K3dBackend) Down added in v0.3.1 

func (b *K3dBackend) Down(cfg *config.Config, u *ui.UI, stackID string) error

func (*K3dBackend) Init added in v0.3.1 

func (b *K3dBackend) Init(cfg *config.Config, u *ui.UI, stackID string, force bool) error

func (*K3dBackend) IsRunning added in v0.3.1 

func (b *K3dBackend) IsRunning(cfg *config.Config, stackID string) (bool, error)

func (*K3dBackend) Name added in v0.3.1 

func (b *K3dBackend) Name() string

func (*K3dBackend) Prerequisites added in v0.3.1 

func (b *K3dBackend) Prerequisites(cfg *config.Config) error

func (*K3dBackend) Up added in v0.3.1 

func (b *K3dBackend) Up(cfg *config.Config, u *ui.UI, stackID string) ([]byte, error)

type K3sBackend added in v0.3.1 

type K3sBackend struct{}

K3sBackend manages a standalone k3s cluster (bare-metal)

func (*K3sBackend) DataDir added in v0.3.1 

func (b *K3sBackend) DataDir(cfg *config.Config) string

func (*K3sBackend) Destroy added in v0.3.1 

func (b *K3sBackend) Destroy(cfg *config.Config, u *ui.UI, stackID string) error

func (*K3sBackend) Down added in v0.3.1 

func (b *K3sBackend) Down(cfg *config.Config, u *ui.UI, stackID string) error

func (*K3sBackend) Init added in v0.3.1 

func (b *K3sBackend) Init(cfg *config.Config, u *ui.UI, stackID string, force bool) error

func (*K3sBackend) IsRunning added in v0.3.1 

func (b *K3sBackend) IsRunning(cfg *config.Config, stackID string) (bool, error)

func (*K3sBackend) Name added in v0.3.1 

func (b *K3sBackend) Name() string

func (*K3sBackend) Prerequisites added in v0.3.1 

func (b *K3sBackend) Prerequisites(cfg *config.Config) error

func (*K3sBackend) Up added in v0.3.1 

func (b *K3sBackend) Up(cfg *config.Config, u *ui.UI, stackID string) ([]byte, error)

type LiveHostGateway added in v0.10.0 

type LiveHostGateway struct {
	Name string
	PID  int
}

LiveHostGateway is a sell-inference offer with a still-running host gateway process (PID file present and alive). These survive `obol stack down` of the cluster and need a separate signal.

type LiveServiceOffer added in v0.10.0 

type LiveServiceOffer struct {
	Namespace string
	Name      string
	Type      string
	Model     string
	Path      string
	Price     string
}

LiveServiceOffer is the subset of a ServiceOffer relevant to the safety check: enough to render the prompt without pulling in monetizeapi.

type LiveServices added in v0.10.0 

type LiveServices struct {
	Offers   []LiveServiceOffer
	Gateways []LiveHostGateway
}

LiveServices captures the snapshot used by ConfirmRunningServicesLoss.

func DiscoverLiveServices added in v0.10.0 

func DiscoverLiveServices(cfg *config.Config) LiveServices

DiscoverLiveServices snapshots cluster-side ServiceOffers in a payment-gate-ready state and host-side sell-inference gateways with alive PID files. Errors are intentionally swallowed: a discovery failure must not block `obol stack down`. A best-effort empty snapshot is returned so the caller falls through to "no prompt needed" only when we have positive evidence of nothing live.

func (LiveServices) Empty added in v0.10.0 

func (s LiveServices) Empty() bool

Empty returns true when no live cluster services and no live host gateways were found. The caller treats this as "safe to proceed without prompting".

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.