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 ¶
- type APIError
- type Client
- func (c *Client) Available() bool
- func (c *Client) Get(showSecrets bool) (*Response, error)
- func (c *Client) Patch(patch []byte) (*Response, error)
- func (c *Client) Put(cfg *types.Config) (*Response, error)
- func (c *Client) Reset() (*Response, error)
- func (c *Client) Rollback(healthTimeoutSeconds int) (*upgrade.Accepted, error)
- func (c *Client) Status() (*upgrade.Status, error)
- func (c *Client) Upgrade(req upgrade.Request) (*upgrade.Accepted, error)
- func (c *Client) Validate(cfg *types.Config) (*Response, error)
- type ErrorResponse
- type Lifecycle
- type Options
- type Response
- type Service
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 ¶
NewClient returns a client for the socket at socketPath. It does not connect; use Available for that.
func (*Client) Available ¶
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) Rollback ¶ added in v1.2.2
Rollback asks KubeSolo to restore the version before the last upgrade.
func (*Client) Status ¶ added in v1.2.2
Status reads the running version, health and upgrade record.
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
// StartedWith is the configuration file as KubeSolo read it at start,
// before flags and the environment were applied over it. A restart is
// refused when the file now changes a setting KubeSolo would not apply.
StartedWith *types.Config
// 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, restart 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, restart 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.