apiserver

Documentation

Index

• Constants
• Variables
• func AdminFacadeDetails() []facade.Details
• func AllFacades() *facade.Registry
• func DescribeFacades(registry *facade.Registry) []params.FacadeVersions
• func GetWatcherByID(watcherRegistry facade.WatcherRegistry, resources facade.Resources, id string) (worker.Worker, error)
• func IsAnonymousFacade(facadeName string) bool
• func IsControllerFacade(facadeName string) bool
• func IsMethodAllowedDuringMigration(facadeName, methodName string) bool
• func IsMethodAllowedDuringUpgrade(facadeName, methodName string) bool
• func IsModelFacade(facadeName string) bool
• type AccessService
• type ApplicationService
• type BakeryConfigService
• type Collector
  • func NewMetricsCollector() *Collector
  • func (c *Collector) Collect(ch chan<- prometheus.Metric)
  • func (c *Collector) Describe(ch chan<- *prometheus.Desc)
• type ControllerConfigService
• type EntitiesWatcher
• type ExecEmbeddedCommandFunc
• type LogSinkConfig
  • func DefaultLogSinkConfig() LogSinkConfig
  • func (cfg LogSinkConfig) Validate() error
• type MacaroonService
• type ModelInfoService
• type PingRootHandler
• type ProxyService
• type Server
  • func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error)
  • func (srv *Server) Dead() <-chan struct{}
  • func (srv *Server) GetAuditConfig() auditlog.Config
  • func (srv *Server) GetCentralHub() *pubsub.StructuredHub
  • func (srv *Server) Kill()
  • func (srv *Server) Report() map[string]interface{}
  • func (srv *Server) Stop() error
  • func (srv *Server) Wait() error
• type ServerConfig
  • func (c ServerConfig) Validate() error
• type SharedHub
• type SrvModelSummaryWatcher
  • func NewModelSummaryWatcher(context facade.ModelContext) (*SrvModelSummaryWatcher, error)
  • func (w *SrvModelSummaryWatcher) Next(ctx context.Context) (params.SummaryWatcherNextResults, error)
  • func (w *SrvModelSummaryWatcher) Stop() error
• type UserService

Constants

const (
	// MetricLabelEndpoint defines a constant for the APIConnections and
	// PingFailureCount Labels
	MetricLabelEndpoint = "endpoint"

	// MetricLabelModelUUID defines a constant for the PingFailureCount and
	// LogWriteCount Labels
	// Note: prometheus doesn't allow hyphens only underscores
	MetricLabelModelUUID = "model_uuid"

	// MetricLabelState defines a constant for the state Label
	MetricLabelState = "state"

	// MetricLabelHost defines a host constant for the Requests Label
	MetricLabelHost = "host"

	// MetricLabelStatus defines a status constant for the Requests Label
	MetricLabelStatus = "status"

	// MetricLabelVersion is the metric for the Juju Version of the controller
	MetricLabelVersion = "version"
)

Variables

var MaintenanceNoLoginError = errors.New("login failed - maintenance in progress")

var MetricAPIConnectionsLabelNames = []string{
	MetricLabelEndpoint,
}

MetricAPIConnectionsLabelNames defines a series of labels for the APIConnections metric.

var MetricLogLabelNames = []string{
	MetricLabelModelUUID,
	MetricLabelState,
}

MetricLogLabelNames defines a series of labels for the LogWrite and LogRead metric

var MetricPingFailureLabelNames = []string{
	MetricLabelModelUUID,
	MetricLabelEndpoint,
}

MetricPingFailureLabelNames defines a series of labels for the PingFailure metric.

var MetricTotalRequestsLabelNames = []string{
	MetricLabelModelUUID,
	MetricLabelHost,
}

MetricTotalRequestsLabelNames defines a series of labels for the TotalRequests metric.

var MetricTotalRequestsWithStatusLabelNames = []string{
	MetricLabelModelUUID,
	MetricLabelHost,
	MetricLabelStatus,
}

MetricTotalRequestsWithStatusLabelNames defines a series of labels for the TotalRequests metric.

Functions

func AdminFacadeDetails

func AdminFacadeDetails() []facade.Details

AdminFacadeDetails returns information on the Admin facade provided at login time. The Facade field of the returned slice elements will be nil.

func AllFacades

func AllFacades() *facade.Registry

AllFacades returns a registry containing all known API facades.

This will panic if facade registration fails, but there is a unit test to guard against that.

func DescribeFacades

func DescribeFacades(registry *facade.Registry) []params.FacadeVersions

DescribeFacades returns the list of available Facades and their Versions

func GetWatcherByID

func GetWatcherByID(watcherRegistry facade.WatcherRegistry, resources facade.Resources, id string) (worker.Worker, error)

GetWatcherByID returns the watcher with the given ID. Deprecated: This only exists to support the old watcher API, once resources have been removed, this can be removed too.

func IsAnonymousFacade

func IsAnonymousFacade(facadeName string) bool

IsAnonymousFacade reports whether the given facade name can be accessed using an anonymous connection.

func IsControllerFacade

func IsControllerFacade(facadeName string) bool

IsControllerFacade reports whether the given facade name can be accessed using a controller connection.

func IsMethodAllowedDuringMigration

func IsMethodAllowedDuringMigration(facadeName, methodName string) bool

func IsMethodAllowedDuringUpgrade

func IsMethodAllowedDuringUpgrade(facadeName, methodName string) bool

func IsModelFacade

func IsModelFacade(facadeName string) bool

IsModelFacade reports whether the given facade name can be accessed using a model connection.

Types

type AccessService

type AccessService interface {
	// ReadUserAccessLevelForTarget returns the subject's (user) access level
	// for the given user on the given target.
	// If the access level of a user cannot be found then
	// accesserrors.AccessNotFound is returned.
	ReadUserAccessLevelForTarget(ctx context.Context, subject user.Name, target permission.ID) (permission.Access, error)
}

AccessService provides information about users and permissions.

type ApplicationService

type ApplicationService interface {
	// GetApplicationDisplayStatus returns the display status of the specified application.
	// The display status is equal to the application status if it is set, otherwise it is
	// derived from the unit display statuses.
	// If no application is found, an error satisfying [applicationerrors.ApplicationNotFound]
	// is returned.
	GetApplicationDisplayStatus(context.Context, coreapplication.ID) (*corestatus.StatusInfo, error)

	// GetApplicationIDByName returns an application ID by application name. It
	// returns an error if the application can not be found by the name.
	//
	// Returns [applicationerrors.ApplicationNotFound] if the application is not found.
	GetApplicationIDByName(context.Context, string) (coreapplication.ID, error)
}

type BakeryConfigService

type BakeryConfigService interface {
	// GetOffersThirdPartyKey returns the key pair used with the cross-model
	// offers bakery.
	GetOffersThirdPartyKey(ctx context.Context) (*bakery.KeyPair, error)
	// GetExternalUsersThirdPartyKey returns the third party key pair used with
	// the external users bakery.
	GetExternalUsersThirdPartyKey(ctx context.Context) (*bakery.KeyPair, error)
}

BakeryConfigService manages macaroon bakery config storage.

type Collector

type Collector struct {
	BuildInfo        prometheus.Gauge
	TotalConnections prometheus.Counter

	LoginAttempts      prometheus.Gauge
	APIConnections     *prometheus.GaugeVec
	APIRequestDuration *prometheus.SummaryVec

	PingFailureCount *prometheus.CounterVec

	LogWriteCount *prometheus.CounterVec
	LogReadCount  *prometheus.CounterVec

	TotalRequests         *prometheus.CounterVec
	TotalRequestErrors    *prometheus.CounterVec
	TotalRequestsDuration *prometheus.SummaryVec
}

Collector is a prometheus.Collector that collects metrics based on apiserver status.

func NewMetricsCollector

func NewMetricsCollector() *Collector

NewMetricsCollector returns a new Collector.

func (*Collector) Collect

func (c *Collector) Collect(ch chan<- prometheus.Metric)

Collect is part of the prometheus.Collector interface.

func (*Collector) Describe

func (c *Collector) Describe(ch chan<- *prometheus.Desc)

Describe is part of the prometheus.Collector interface.

type ControllerConfigService

type ControllerConfigService interface {
	// ControllerConfig returns the config values for the controller.
	ControllerConfig(context.Context) (controller.Config, error)
}

ControllerConfigService defines the methods required to get the controller configuration.

type EntitiesWatcher

type EntitiesWatcher interface {
	corewatcher.StringsWatcher

	// MapChanges maps the received strings to their according tag strings.
	// The EntityFinder interface representing state or a mock has to be
	// upcasted into the needed sub-interface of state for the real mapping.
	MapChanges(in []string) ([]string, error)
}

EntitiesWatcher defines an interface based on the StringsWatcher but also providing a method for the mapping of the received strings to the tags of the according entities.

type ExecEmbeddedCommandFunc

type ExecEmbeddedCommandFunc func(ctx *cmd.Context, store jujuclient.ClientStore, whitelist []string, cmdPlusArgs string) int

ExecEmbeddedCommandFunc defines a function which runs a named Juju command with the whitelisted sub commands.

type LogSinkConfig

type LogSinkConfig struct {
	// RateLimitBurst defines the number of log messages that will be let
	// through before we start rate limiting.
	RateLimitBurst int64

	// RateLimitRefill defines the rate at which log messages will be let
	// through once the initial burst amount has been depleted.
	RateLimitRefill time.Duration
}

LogSinkConfig holds parameters to control the API server's logsink endpoint behaviour.

func DefaultLogSinkConfig

func DefaultLogSinkConfig() LogSinkConfig

DefaultLogSinkConfig returns a LogSinkConfig with default values.

func (LogSinkConfig) Validate

func (cfg LogSinkConfig) Validate() error

Validate validates the logsink endpoint configuration.

type MacaroonService

type MacaroonService interface {
	dbrootkeystore.ContextBacking
	BakeryConfigService
}

MacaroonService defines the method required to manage macaroons.

type ModelInfoService

type ModelInfoService interface {
	// GetModelInfo returns the information for the current model.
	GetModelInfo(ctx context.Context) (model.ModelInfo, error)
}

ModelInfoService provides access to information about the current model.

type PingRootHandler

type PingRootHandler interface {
	WatcherRegistry() facade.WatcherRegistry
	CloseConn() error
}

PingRootHandler is the interface that the root handler must implement to allow the pinger to be registered.

type ProxyService

type ProxyService interface {
	// GetConnectionProxyInfo returns the proxy information for the controller.
	GetConnectionProxyInfo(context.Context) (proxy.Proxier, error)
}

ProxyService defines the methods required to get proxy details.

type Server

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

Server holds the server side of the API.

func NewServer

func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error)

NewServer serves API requests using the given configuration.

func (*Server) Dead

func (srv *Server) Dead() <-chan struct{}

Dead returns a channel that signals when the server has exited.

func (*Server) GetAuditConfig

func (srv *Server) GetAuditConfig() auditlog.Config

GetAuditConfig returns a copy of the current audit logging configuration.

func (*Server) GetCentralHub

func (srv *Server) GetCentralHub() *pubsub.StructuredHub

GetCentralHub returns the central hub for the server.

func (*Server) Kill

func (srv *Server) Kill()

Kill implements worker.Worker.Kill.

func (*Server) Report

func (srv *Server) Report() map[string]interface{}

Report is shown in the juju_engine_report.

func (*Server) Stop

func (srv *Server) Stop() error

Stop stops the server and returns when all running requests have completed.

func (*Server) Wait

func (srv *Server) Wait() error

Wait implements worker.Worker.Wait.

type ServerConfig

type ServerConfig struct {
	Clock     clock.Clock
	PingClock clock.Clock
	Tag       names.Tag
	DataDir   string
	LogDir    string
	Hub       *pubsub.StructuredHub
	Presence  presence.Recorder
	Mux       *apiserverhttp.Mux

	// ControllerUUID is the controller unique identifier.
	ControllerUUID string

	// ControllerModelUUID is the ID for the controller model.
	ControllerModelUUID model.UUID

	// LocalMacaroonAuthenticator is the request authenticator used for verifying
	// local user macaroons.
	LocalMacaroonAuthenticator macaroon.LocalMacaroonAuthenticator

	// JWTAuthenticator is the request authenticator used for validating jwt
	// tokens when the controller has been bootstrapped with a trusted token
	// provider.
	JWTAuthenticator jwt.Authenticator

	// StatePool is the StatePool used for looking up State
	// to pass to facades. StatePool will not be closed by the
	// server; it is the callers responsibility to close it
	// after the apiserver has exited.
	StatePool *state.StatePool

	// UpgradeComplete is a function that reports whether or not
	// the if the agent running the API server has completed
	// running upgrade steps. This is used by the API server to
	// limit logins during upgrades.
	UpgradeComplete func() bool

	// PublicDNSName is reported to the API clients who connect.
	PublicDNSName string

	// AllowModelAccess holds whether users will be allowed to
	// access models that they have access rights to even when
	// they don't have access to the controller.
	AllowModelAccess bool

	// NewObserver is a function which will return an observer. This
	// is used per-connection to instantiate a new observer to be
	// notified of key events during API requests.
	NewObserver observer.ObserverFactory

	// RegisterIntrospectionHandlers is a function that will
	// call a function with (path, http.Handler) tuples. This
	// is to support registering the handlers underneath the
	// "/introspection" prefix.
	RegisterIntrospectionHandlers func(func(string, http.Handler))

	// LogSinkConfig holds parameters to control the API server's
	// logsink endpoint behaviour. If this is nil, the values from
	// DefaultLogSinkConfig() will be used.
	LogSinkConfig *LogSinkConfig

	// LogSink is used to store log records received from connected agents.
	LogSink corelogger.ModelLogger

	// GetAuditConfig holds a function that returns the current audit
	// logging config. The function may return updated values, so
	// should be called every time a new login is handled.
	GetAuditConfig func() auditlog.Config

	// LeaseManager gives access to leadership and singular claimers
	// and checkers for use in API facades.
	LeaseManager lease.Manager

	// MetricsCollector defines all the metrics to be collected for the
	// apiserver
	MetricsCollector *Collector

	// ExecEmbeddedCommand is a function which creates an embedded Juju CLI instance.
	ExecEmbeddedCommand ExecEmbeddedCommandFunc

	// CharmhubHTTPClient is the HTTP client used for Charmhub API requests.
	CharmhubHTTPClient facade.HTTPClient

	// DomainServicesGetter provides access to the services.
	DomainServicesGetter services.DomainServicesGetter

	// DBGetter returns WatchableDB implementations based on namespace.
	DBGetter changestream.WatchableDBGetter

	// DBDeleter is used to delete databases by namespace.
	DBDeleter database.DBDeleter

	// TracerGetter returns a tracer for the given namespace, this is used
	// for opentelmetry tracing.
	TracerGetter trace.TracerGetter

	// ObjectStoreGetter returns an object store for the given namespace.
	// This is used for retrieving blobs for charms and agents.
	ObjectStoreGetter objectstore.ObjectStoreGetter
}

ServerConfig holds parameters required to set up an API server.

func (ServerConfig) Validate

func (c ServerConfig) Validate() error

Validate validates the API server configuration.

type SharedHub

type SharedHub interface {
	Publish(topic string, data interface{}) (func(), error)
	Subscribe(topic string, handler interface{}) (func(), error)
}

SharedHub represents the methods of the pubsub.StructuredHub that are used. The context uses an interface to allow mocking of the hub.

type SrvModelSummaryWatcher

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

SrvModelSummaryWatcher defines the API methods on a ModelSummaryWatcher.

func NewModelSummaryWatcher

func NewModelSummaryWatcher(context facade.ModelContext) (*SrvModelSummaryWatcher, error)

NewModelSummaryWatcher returns a new API server endpoint for interacting with a watcher created by the WatchModelSummaries and WatchAllModelSummaries API calls.

func (*SrvModelSummaryWatcher) Next

func (w *SrvModelSummaryWatcher) Next(ctx context.Context) (params.SummaryWatcherNextResults, error)

Next will return the current state of everything on the first call and subsequent calls will return just those model summaries that have changed.

func (*SrvModelSummaryWatcher) Stop

func (w *SrvModelSummaryWatcher) Stop() error

Stop stops the watcher.

type UserService

type UserService interface {
	// GetUserByName returns the user with the given name.
	GetUserByName(context.Context, user.Name) (user.User, error)
	// SetPasswordWithActivationKey will use the activation key from the user
	// to then apply the payload password.
	SetPasswordWithActivationKey(ctx context.Context, name user.Name, nonce, box []byte) (userservice.Sealer, error)
}

UserService defines the methods required to get user details.