Documentation
¶
Overview ¶
Package k3sengine runs single-node k3s clusters in containers for the EKS and GKE emulators.
Index ¶
- Constants
- Variables
- func HTTPGet(ctx context.Context, addr, path, token string, tlsCfg *tls.Config) ([]byte, error)
- func Image(version, fallbackVersion string) (string, bool)
- func MinorKey(version string) (string, bool)
- func NormalizeAccess(host, token string) (string, string, error)
- func Probe(ctx context.Context, addr, token string, caPEM []byte) error
- func Script(servicelb bool) string
- func Tag(version string) (string, bool)
- func Tags() [8]string
- type CA
- type Config
- type Engine
- func (e *Engine) AcquirePort(name string) (int, error)
- func (e *Engine) Addr(port int) string
- func (e *Engine) Adopt(oc container.ManagedContainer) (*Instance, error)
- func (e *Engine) AwaitReady(ctx context.Context, addr string, ca []byte) ([]byte, error)
- func (e *Engine) Close()
- func (e *Engine) Exec(ctx context.Context, containerID string, cmd, env []string) (container.ExecResult, error)
- func (e *Engine) Host() string
- func (e *Engine) Launch(ctx context.Context, n Node, record func(*Instance) bool) (*Instance, error)
- func (e *Engine) Log(ctx context.Context) *slog.Logger
- func (e *Engine) ReleaseAll(port int, lbHost []int)
- func (e *Engine) ReleasePort(port int)
- func (e *Engine) Remove(containerID string, ports ...int)
- func (e *Engine) RemoveVolume(ctx context.Context, name string) error
- func (e *Engine) RotateCertificates(ctx context.Context, containerID, addr string) ([]byte, error)
- func (e *Engine) Runtime() Runtime
- func (e *Engine) ServingCA(ctx context.Context, containerID string) ([]byte, error)
- func (e *Engine) Start(ctx context.Context, containerID, addr string, ca []byte) ([]byte, error)
- func (e *Engine) Stop(ctx context.Context, containerID string) error
- func (e *Engine) Token() string
- func (e *Engine) UnusedVolumes(ctx context.Context) ([]string, error)
- type Instance
- type Node
- type Runtime
- type Stoppable
Constants ¶
const ( // ImageRepo is the image repository the engine runs. ImageRepo = "rancher/k3s" // DefaultToken is the static cluster-admin bearer token used when none is configured. DefaultToken = "gopherstack-eks-cluster-token" //nolint:gosec // documented default for a local emulator // APIPort is the k3s API server port inside the container. APIPort = 6443 // DataDir is the k3s state directory a persistent volume is mounted on. DataDir = "/var/lib/rancher/k3s" // CACertFile is where the node keeps the serving CA certificate. CACertFile = tlsDir + "/server-ca.crt" )
const VolumeLabel = "gopherstack.k3s-volume"
VolumeLabel marks the data volumes the engine creates.
Variables ¶
var ( // ErrInvalidConfig is returned when the engine host or token is unusable. ErrInvalidConfig = errors.New("invalid k3s cluster engine configuration") // ErrDefaultTokenExposed is returned when the public default token would be exposed off-host. ErrDefaultTokenExposed = errors.New("a cluster token must be set when the cluster host is not loopback") // ErrSuperseded is returned by Launch when the caller's record callback declined the new container. ErrSuperseded = errors.New("cluster was superseded while starting") // ErrNotAdoptable is returned when a leftover container cannot be taken over. ErrNotAdoptable = errors.New("container cannot be adopted") // ErrNodeExited is returned when the node container stops while the engine waits for its API server. ErrNodeExited = errors.New("node container exited") // ErrRotateFailed is returned when the node could not drop its certificates. ErrRotateFailed = errors.New("certificate rotation failed") // ErrStopUnsupported is returned by Stop and Start when the runtime cannot keep a stopped container. ErrStopUnsupported = errors.New("container runtime cannot stop and restart a container in place") )
var ErrNotReady = errors.New("readyz not ok")
ErrNotReady is returned while the API server has not answered /readyz with 200.
Functions ¶
func HTTPGet ¶
HTTPGet GETs https://addr/path with an optional bearer token and requires a 200.
func Image ¶
Image maps a Kubernetes version to its pinned k3s image; exact is false when it fell back to fallbackVersion.
func NormalizeAccess ¶
NormalizeAccess validates host and token and fills their defaults.
func Probe ¶
Probe requires /readyz to answer 200 for the bearer token over TLS verified against the pre-provisioned CA.
func Script ¶
Script builds the node command; servicelb stays on only when load-balancer ports are published.
Types ¶
type CA ¶
CA is the server CA pre-provisioned into k3s so the readiness probe never has to trust-on-first-use.
type Config ¶
type Config struct {
Runtime Runtime
Ports *portalloc.Allocator
Logger *slog.Logger
Probe func(ctx context.Context, addr, token string) ([]byte, error)
Prefix string
Host string
Token string
StartTimeout time.Duration
}
Config configures an Engine. Prefix names containers and port labels ("eks", "gke").
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine starts and stops single-node k3s containers.
func (*Engine) AcquirePort ¶
AcquirePort takes a host port labelled for name.
func (*Engine) Adopt ¶
func (e *Engine) Adopt(oc container.ManagedContainer) (*Instance, error)
Adopt takes over a running node container an earlier gopherstack left behind. The caller owns it afterwards.
func (*Engine) AwaitReady ¶
AwaitReady polls the API server until it answers or the start timeout passes; it returns the serving CA.
func (*Engine) Exec ¶
func (e *Engine) Exec(ctx context.Context, containerID string, cmd, env []string) (container.ExecResult, error)
Exec runs cmd in a running node; env entries are set on the process, never in argv.
func (*Engine) Launch ¶
func (e *Engine) Launch(ctx context.Context, n Node, record func(*Instance) bool) (*Instance, error)
Launch starts the container for n. record runs once the container exists and returns false when the caller no longer wants it, in which case the container is removed and ErrSuperseded returned.
func (*Engine) ReleaseAll ¶
ReleaseAll returns an API port and its load-balancer host ports.
func (*Engine) ReleasePort ¶
ReleasePort returns a port taken by AcquirePort.
func (*Engine) RemoveVolume ¶
RemoveVolume deletes a data volume; runtimes without volume support have nothing to delete.
func (*Engine) RotateCertificates ¶
RotateCertificates replaces the node's cluster CAs with freshly generated ones (k3s certificate rotate-ca) and restarts it, so k3s reissues every certificate under them. It returns the new serving CA.
func (*Engine) ServingCA ¶
ServingCA reads the node's serving CA certificate, which differs from the one generated for a launch when a reused data volume already held a CA. It waits for the node to write it.
func (*Engine) Start ¶
Start restarts a container kept by Stop and waits for its API server on addr; it returns the serving CA.
func (*Engine) Stop ¶
Stop stops the container but keeps it, so its filesystem (the cluster state) and published ports survive.
type Node ¶
type Node struct {
Name string
Image string
JoinToken string
// Resource is the owning service's key for the cluster: a restarted gopherstack can adopt the container by it.
Resource string
// Volume names a data volume mounted on DataDir, so cluster state outlives the container.
Volume string
// NodeName pins the Kubernetes node name; empty keeps the container hostname.
NodeName string
Mounts []string
LBPorts []int
}
Node describes one k3s server container.
Source Files