local

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Overview

Package local manages local Podplane cluster VMs and their support server.

Index

Constants

View Source 
const LocalClusterConfigFilename = "cluster.jsonc"

Variables

This section is empty.

Functions

func AppIngressRoutePort added in v0.2.3 

func AppIngressRoutePort(runtimeDir, host, clusterID string) int

AppIngressRoutePort returns the browser-facing local ingress HTTPS port when host belongs to clusterID's app ingress namespace and the local server is running.

func CheckRuntimeDependencies 

func CheckRuntimeDependencies(arch string) error

CheckRuntimeDependencies checks whether the local VM runtime dependencies are installed for arch.

func CheckServerRuntimeDependencies 

func CheckServerRuntimeDependencies() error

CheckServerRuntimeDependencies checks whether local server runtime dependencies are installed.

func ClusterConfigPath 

func ClusterConfigPath(dataDir, clusterID string) string

ClusterConfigPath returns the generated cluster config path for a local cluster.

func ClusterDataDir 

func ClusterDataDir(dataDir, clusterID string) string

ClusterDataDir returns the users data directory for a local cluster.

func IsAppIngressHostname added in v0.2.3 

func IsAppIngressHostname(host string) bool

IsAppIngressHostname reports whether host is in the local app ingress namespace. App ingress uses <cluster-id>.localhost or <host>.<cluster-id>.localhost; <cluster-id>.k8s.localhost is reserved for the Kubernetes API.

func LocalIngressClusterID added in v0.2.3 

func LocalIngressClusterID(host string) (string, error)

LocalIngressClusterID extracts the local cluster ID from a browser-facing local app ingress hostname.

func LocalKubernetesAPIHostname 

func LocalKubernetesAPIHostname(clusterID string) string

LocalKubernetesAPIHostname returns the reserved host routed by the local ingress proxy to a cluster's Kubernetes API server.

func MkcertTrustInstalled added in v0.1.2 

func MkcertTrustInstalled() (bool, error)

MkcertTrustInstalled reports whether mkcert's local CA is trusted by the host system trust store.

func SSHPrivateKeyPath added in v0.1.2 

func SSHPrivateKeyPath(dataDir string) (string, error)

SSHPrivateKeyPath returns the private key path for Podplane-managed local VM SSH access, generating the key pair if necessary.

func SSHPublicKey added in v0.1.2 

func SSHPublicKey(dataDir string) (string, error)

SSHPublicKey returns the Podplane-managed public key for the VM's authorized_keys file, generating the key pair if necessary.

func ServerKill 

func ServerKill(pidFile pid.PIDFile) error

ServerKill stops the local server if it is running and removes the PID file.

func ServerLogPath 

func ServerLogPath(runtimeDir string) string

ServerLogPath returns the local server stdout/stderr log path.

func ServerPIDFile 

func ServerPIDFile(runtimeDir string) (pid.PIDFile, error)

ServerPIDFile loads (or initializes) the PID file used to track the background `podplane local server` process. runtimeDir is the directory in which the file is stored (typically <Config.RuntimeDirectory()>).

Types

type APIReadinessOptions 

type APIReadinessOptions struct {
	Quiet bool
}

APIReadinessOptions configures Kubernetes API readiness output.

type ConfigSource 

type ConfigSource interface {
	ConfigDirectory() string
	CacheDirectory() string
	DataDirectory() string
	RuntimeDirectory() string
	DepsBaseURL() string
	DepsCacheDir() string
	InstanceKind() string
	Arch() string
}

ConfigSource is the subset of CLI config needed to build local options.

type Local 

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

Local handles local cluster lifecycles

func NewManager 

func NewManager(c ConfigSource, clusterID string) *Local

NewManager creates a new local cluster manager.

func (*Local) CloudInitServerURL 

func (l *Local) CloudInitServerURL(hostMachineAddr, clusterID string) (string, error)

CloudInitServerURL returns the URL to the local server cloud-init base URL for a given cluster.

func (*Local) Console 

func (m *Local) Console() error

Console attaches to the running local cluster VM's serial console.

func (*Local) Delete 

func (m *Local) Delete() error

Delete deletes the local cluster VM and cluster data if it is the last VM

func (*Local) DepsServerURL 

func (l *Local) DepsServerURL(hostAddr, port string) (string, error)

DepsServerURL returns the URL to the local server deps cache base URL.

If hostAddr is set and port is not, it will use the local server HTTP port. If hostAddr is not set, it will default to the local server URL.

func (*Local) Exists 

func (m *Local) Exists() (bool, error)

Exists reports whether the local cluster VM has already been created.

func (*Local) HostOIDCIssuerURL 

func (m *Local) HostOIDCIssuerURL() (string, error)

HostOIDCIssuerURL returns the OIDC issuer URL as reachable from the host machine (where the CLI itself runs), not from inside the guest VM.

func (*Local) LocalIngressURL 

func (l *Local) LocalIngressURL() (string, error)

LocalIngressURL returns the browser-facing local ingress proxy URL for this cluster.

func (*Local) LocalKubernetesAPIURL 

func (l *Local) LocalKubernetesAPIURL() (string, error)

LocalKubernetesAPIURL returns the host-facing Kubernetes API URL routed through the reserved local ingress proxy hostname <cluster-id>.k8s.localhost

func (*Local) LocalServerHTTPSPort 

func (l *Local) LocalServerHTTPSPort() (string, error)

LocalServerHTTPSPort returns the HTTPS port of the local server.

func (*Local) LocalServerPort 

func (l *Local) LocalServerPort() (string, error)

LocalServerPort returns the HTTP port of the local server.

func (*Local) LocalServerURL 

func (l *Local) LocalServerURL() (string, error)

LocalServerURL returns the HTTP URL to the local server.

func (*Local) OIDCCACertPath 

func (l *Local) OIDCCACertPath() string

OIDCCACertPath returns the local server CA certificate path for the fake HTTPS OIDC issuer.

func (*Local) OIDCKeyPath 

func (l *Local) OIDCKeyPath() string

OIDCKeyPath returns the local server's OIDC signing key path. The key is shared between the running local server and any in-process callers that need to mint tokens (e.g. the apiserver readiness probe).

func (*Local) OIDCServerURL 

func (l *Local) OIDCServerURL(hostAddr string) (string, error)

OIDCServerURL returns the URL to the local server fake HTTPS OIDC issuer.

func (*Local) ProbeAPIServerLive 

func (m *Local) ProbeAPIServerLive(ctx context.Context) error

ProbeAPIServerLive mints a local-OIDC token and issues an authenticated GET /livez, returning nil only when the apiserver reports itself alive (HTTP 200). It proves the apiserver process is up and serving — but not that bootstrap post-start hooks have completed; use ProbeAPIServerReady for that.

func (*Local) ProbeAPIServerReady 

func (m *Local) ProbeAPIServerReady(ctx context.Context) error

ProbeAPIServerReady mints a local-OIDC token and issues an authenticated GET /readyz, returning nil only when the apiserver reports itself ready (HTTP 200). Ready implies live. Writes (e.g. CRD creation) before this returns can fail with connection resets even though TLS handshakes succeed.

func (*Local) ProbeCloudInit 

func (m *Local) ProbeCloudInit(ctx context.Context) (string, error)

ProbeCloudInit returns the current cloud-init status string (e.g. "done", "running", "error", "not started") from the VM. Unlike WaitForReadiness it does not block — it runs `cloud-init status` once and returns immediately.

func (*Local) Running 

func (m *Local) Running() (bool, error)

Running reports whether the local cluster VM currently exists and is running.

func (*Local) S3CacheServerURL 

func (l *Local) S3CacheServerURL(hostAddr string) (string, error)

S3CacheServerURL returns the local fake S3 endpoint for cache-backed buckets.

func (*Local) S3DataServerURL 

func (l *Local) S3DataServerURL(hostAddr string) (string, error)

S3DataServerURL returns the local fake S3 endpoint for durable data buckets.

func (*Local) SeedConfig added in v0.2.4 

func (m *Local) SeedConfig() (clusterconfig.Seed, error)

SeedConfig returns cluster.seed from this local cluster's config.

func (*Local) ServerCleanup 

func (m *Local) ServerCleanup() error

ServerCleanup check if any local VMs are still running. If not, it will check if a pid exists in the config file and if the process is running and kill it/remove the PID file via the ServerKill function above.

func (*Local) ServerEnsure 

func (m *Local) ServerEnsure(output io.Writer) error

ServerEnsure ensures the local server is running by running `podplane local server` in the background and waiting for it to start. Note that this command already handles detection of duplicate PIDs and will not start a new process if one is already running (and instead exit (immediately). Here we just run the command in the background and expect the user will stop the server via the `podplane local stop` or `podplane local server -q` commands.

func (*Local) Shell 

func (m *Local) Shell(command string) error

Shell opens a shell into the running local cluster VM If command is provided, executes that command instead of opening interactive shell.

func (*Local) Start 

func (m *Local) Start(opts StartOptions) (string, error)

Start is used to create a cluster, create a VM, and start a VM. Each cluster requires: 1.a. The package files to be downloaded to cache 1.b. The VM machine image to be downloaded to cache 2. CLI to be running a fake S3 and OIDC and package cache server in the background 3. The VM to be created 4. The VM to be started Start brings up the local cluster VM and writes a .cluster.jsonc config file describing how to log in to it. The returned path is the absolute location of that config (empty string on early failure paths). Callers (specifically `podplane local start`) use it to drive an in-process `podplane login --headless` against the local fake OIDC.

func (*Local) Status 

func (m *Local) Status() error

Status checks and displays the status of the local cluster VM

func (*Local) Stop 

func (m *Local) Stop() error

Stop stops the local cluster VM and supporting processes

func (*Local) Sync 

func (m *Local) Sync(from, to, chown string, excludes []string) error

Sync rsync's files into the running local cluster VM.

func (*Local) UserdataDir 

func (l *Local) UserdataDir(clusterID string) string

UserdataDir returns the directory in which the rendered user-data file is written for a given cluster.

@see: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html#source-files

func (*Local) UserdataPath 

func (l *Local) UserdataPath(clusterID string) string

UserdataPath returns the path to the user-data file for a given cluster. The file lives at <UserdataDir>/user-data.

func (*Local) WaitForAPIServer 

func (m *Local) WaitForAPIServer(ctx context.Context) error

WaitForAPIServer waits until the local cluster's kube-apiserver is ready to serve API requests. It first waits for /livez (process up and serving TLS), then for /readyz (post-start hooks like RBAC bootstrap and priority classes have completed). Hitting workloads before /readyz passes can produce 5xx / connection resets even though TLS handshakes succeed.

func (*Local) WaitForAPIServerWithOptions 

func (m *Local) WaitForAPIServerWithOptions(ctx context.Context, opts APIReadinessOptions) error

WaitForAPIServerWithOptions waits until the local cluster's kube-apiserver is live and ready with caller-controlled output.

func (*Local) WaitForNetsyHealth 

func (m *Local) WaitForNetsyHealth(ctx context.Context, opts WaitOptions) error

WaitForNetsyHealth waits until the Netsy HTTP health endpoint reports a healthy node state. This follows the systemd check because the netsy service can be active while Netsy is still loading its persisted state.

func (*Local) WaitForNstanceAgentRegistration 

func (m *Local) WaitForNstanceAgentRegistration(ctx context.Context, opts WaitOptions) error

WaitForNstanceAgentRegistration waits until nstance-agent has registered with the local fake Nstance server. systemd can report nstance-agent as active before the one-time registration handshake finishes, so this is a separate readiness boundary from WaitForSystemServices.

func (*Local) WaitForReadiness 

func (m *Local) WaitForReadiness(ctx context.Context, opts ReadinessOptions) error

WaitForReadiness waits for the local VM's first-boot user-data script to complete successfully. It intentionally does not wait for Kubernetes here: local vmconfig development images may stop after user-data setup and before install.sh/configure.sh have been synced and run.

func (*Local) WaitForSystemServices 

func (m *Local) WaitForSystemServices(ctx context.Context, opts WaitOptions) error

WaitForSystemServices waits for core guest services that kube-apiserver depends on. It intentionally does not check kube-apiserver itself; WaitForAPIServer performs the subsequent /livez and /readyz probes.

func (*Local) WriteLocalClusterConfig 

func (m *Local) WriteLocalClusterConfig(clusterID, oidcIssuerURL, oidcCACertPath, apiHostname string, apiPort int, seed clusterconfig.Seed, componentsSource *clusterconfig.ComponentsSource) (string, error)

WriteLocalClusterConfig writes a JSONC cluster config to <dataDir>/local/<clusterID>/cluster.jsonc and returns its absolute path. It describes how the host CLI can reach the local cluster's OIDC issuer and (eventually) Kubernetes API.

type ReadinessOptions 

type ReadinessOptions struct {
	StreamUserdataLogs bool
	Quiet              bool
}

ReadinessOptions configures optional output while waiting for first-boot user-data to finish.

type Server 

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

Server represents the local cluster background server.

func NewServer 

func NewServer(pidFile pid.PIDFile, c ConfigSource, addr string, port int) (*Server, error)

NewServer starts local HTTP and HTTPS servers on specific (if specified) or fixed available ports and serves sibling endpoints to local VMs and clients: 

/deps/        — file server over <DepsCacheDir>
/cloud-init/  — NoCloud user-data + static datasource files
/oidc/        — fake OIDC issuer (discovery, JWKS, /token)
/s3/data/     — fake S3 for durable local-cluster buckets
/s3/cache/    — fake S3 for cache-backed buckets
fake Nstance gRPC services on dedicated random ports, published via PID metadata

It also creates a PID file to prevent multiple local servers from running and to allow other CLI processes to ensure the server is running and determine its port numbers.

func (*Server) HTTPPort 

func (w *Server) HTTPPort() int

HTTPPort returns the HTTP server port.

func (*Server) HTTPSPort 

func (w *Server) HTTPSPort() int

HTTPSPort returns the HTTPS server port.

func (*Server) Stop 

func (w *Server) Stop(timeout time.Duration) error

Stop stops the local HTTP, HTTPS, and ingress servers.

type StartOptions 

type StartOptions struct {
	CPUs                string
	Memory              string
	StreamUserdataLogs  bool
	Components          string
	RunDownloadProgress func(run func(progress func(deps.DownloadEvent)) error) error
	Progress            tui.TaskProgress
}

StartOptions controls local cluster startup.

type WaitOptions 

type WaitOptions struct {
	Quiet bool
}

WaitOptions configures output for simple local readiness waits.

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.