configapi

package
v1.2.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package configapi implements the optional KubeSolo configuration API.

It serves the configuration document over a unix socket: read it, replace it, patch it, reset it, or check a candidate without saving. The socket's file permissions are the authorisation model — there is no token and no TLS, because there is no network listener to protect. On an edge device, a mutating endpoint that is not reachable over the network is worth more than one that is reachable and authenticated.

The API manages desired state, not live state. Almost every setting is read once during bootstrap and baked into types.Embedded, which each service is constructed from by value, so a change takes effect when KubeSolo restarts. Responses say so rather than implying otherwise.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError added in v1.2.2

type APIError struct {
	Status  int
	Message string
}

APIError is a request the API answered with an error status.

func (*APIError) Error added in v1.2.2

func (e *APIError) Error() string

type Client

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

Client talks to a running KubeSolo's configuration API over its unix socket.

It exists so that kubesoloctl can go through the API when KubeSolo is running, rather than editing the file underneath it. Doing so gets validation against the real host, the restart-required report, and the concurrency protection — none of which a direct file edit can offer.

func NewClient

func NewClient(socketPath string) *Client

NewClient returns a client for the socket at socketPath. It does not connect; use Available for that.

func (*Client) Available

func (c *Client) Available() bool

Available reports whether something is listening on the socket.

The socket file outliving its process is the normal case after an unclean shutdown, so its presence is not evidence of a running KubeSolo — only a successful connection is.

func (*Client) Get

func (c *Client) Get(showSecrets bool) (*Response, error)

Get reads the configuration. Secrets are redacted unless showSecrets is set.

func (*Client) Patch

func (c *Client) Patch(patch []byte) (*Response, error)

Patch applies an RFC 7386 merge patch.

func (*Client) Put

func (c *Client) Put(cfg *types.Config) (*Response, error)

Put replaces the configuration wholesale.

func (*Client) Reset

func (c *Client) Reset() (*Response, error)

Reset restores every setting to its default.

func (*Client) Rollback added in v1.2.2

func (c *Client) Rollback(healthTimeoutSeconds int) (*upgrade.Accepted, error)

Rollback asks KubeSolo to restore the version before the last upgrade.

func (*Client) Status added in v1.2.2

func (c *Client) Status() (*upgrade.Status, error)

Status reads the running version, health and upgrade record.

func (*Client) Upgrade added in v1.2.2

func (c *Client) Upgrade(req upgrade.Request) (*upgrade.Accepted, error)

Upgrade asks KubeSolo to upgrade itself. It returns once the upgrade has been accepted; follow it with Status.

func (*Client) Validate

func (c *Client) Validate(cfg *types.Config) (*Response, error)

Validate checks a candidate configuration without saving it.

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`

	// Field names the setting at fault, where one is identifiable.
	Field string `json:"field,omitempty"`
}

ErrorResponse is the body of every failed request.

type Lifecycle added in v1.2.2

type Lifecycle struct {
	// Version and Commit identify the running binary.
	Version string
	Commit  string

	// DataDir is KubeSolo's data directory.
	DataDir string

	// ContainerMode is set when KubeSolo runs in a container, which cannot
	// replace its own image.
	ContainerMode bool

	// Spawn starts the upgrade executor on a job file, detached from the
	// KubeSolo service.
	Spawn func(jobFile string) error

	// Health reports whether KubeSolo is working.
	Health func(ctx context.Context) upgrade.Health

	// AgentImage returns the image the Portainer agent Deployment runs, or ""
	// when there is no such Deployment.
	AgentImage func(ctx context.Context) (string, error)
}

Lifecycle is what the upgrade, rollback and status endpoints need from the running KubeSolo. The functions are fields so tests can replace them; main supplies the real ones.

type Options

type Options struct {
	// SocketPath is where the unix socket is created.
	SocketPath string

	// ConfigPath is the configuration file served and updated.
	ConfigPath string

	// Host describes the machine, for validating candidate configurations.
	Host config.Host

	// Lifecycle enables the upgrade, rollback and status endpoints. Nil leaves
	// them out.
	Lifecycle *Lifecycle

	// AgentSocketPath, when set, is a second socket serving the same API, for
	// the Portainer agent. It sits in a directory of its own, which is what is
	// mounted into the agent's pod.
	AgentSocketPath string
}

Options is everything the service needs.

Unlike the metrics service it does not take types.Embedded: it reads and writes the configuration file, and needs neither the PKI nor the containerd layout to do it.

type Response

type Response struct {
	Config *types.Config `json:"config"`

	// Changed lists the settings this request altered, by config path.
	Changed []string `json:"changed,omitempty"`

	// RequiresRestart is the subset of Changed that cannot take effect until
	// KubeSolo restarts. Today that is all of them.
	RequiresRestart []string `json:"requiresRestart,omitempty"`
	RestartRequired bool     `json:"restartRequired"`

	Warnings []string `json:"warnings,omitempty"`
}

Response is what every endpoint returns. It is exported so that a client — kubesoloctl — shares one definition of the wire format with the server.

RestartRequired is stated rather than implied. Almost every setting is read once during bootstrap and baked into types.Embedded, so a write here changes desired state and nothing else until KubeSolo restarts.

type Service

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

Service is the configuration API. It follows the same NewService/Run + readyCh shape as the other KubeSolo components.

func NewService

func NewService(ctx context.Context, cancel context.CancelFunc, readyCh chan struct{}, opts Options) *Service

NewService creates the configuration API service.

It does not block any other component on its own readiness: readyCh exists so that main can join the goroutine on shutdown. The API failing must never stop KubeSolo from running.

func (*Service) Run

func (s *Service) Run() error

Run starts the configuration API and blocks until the context is done.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL