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

stack

package
v0.16.1-rc1 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: Apache-2.0 Imports: 39 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 ConfirmClusterDestroy added in v0.17.0 

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

ConfirmClusterDestroy gates an action that deletes the cluster (and with it every in-cluster resource, including sub-agent wallet Secrets).

Live services are always listed when found, and a discovery failure (cluster unreachable, listing error) is reported as "could not check what is running" and treated like live services: it needs an explicit yes. With always=true confirmation is required even when the cluster was positively checked and found idle. In every gated case: --yes proceeds with a warning, a TTY gets a default-No prompt, and a non-interactive run fails closed with an error naming --yes.

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 `obol stack down` is about to stop a cluster that is currently serving traffic, and asks whether to proceed. Stopping preserves config and data, so a failed discovery (cluster already unreachable) is not a reason to prompt here; commands that DESTROY a cluster use ConfirmClusterDestroy instead.

Returns true when the caller should continue. The rules:

  • No live offers -> 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. When --force switches backends the old cluster is destroyed, which always needs confirmation: a default-No prompt on a TTY, or skipConfirm (--yes) in non-interactive shells.

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, resetDefaults bool) error

Up starts the cluster using the configured backend. resetDefaults (--reset-defaults) overwrites hand-edited files in the defaults tree with the shipped defaults, backing them up first.

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 {
	// contains filtered or unexported fields
}

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 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
}

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. `obol sell inference` gateways are standalone processes that don't depend on the cluster, so they aren't tracked. Errors are swallowed (best-effort snapshot); callers that must distinguish "nothing live" from "could not check" use discoverLiveServicesChecked.

func (LiveServices) Empty added in v0.10.0 

func (s LiveServices) Empty() bool

Empty returns true when no live cluster services 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.