import "github.com/juju/juju/core/cache"
Package cache is responsible for keeping an in memory representation of the controller's models.
The Controller is kept up to date with the database though a changes channel.
Instances in the cache package also provide watchers. These watchers are checking for changes in the in-memory representation and can be used to avoid excess database reads.
application.go branch.go changes.go charm.go charmconfigwatcher.go controller.go doc.go hash.go lxdprofilewatcher.go machine.go metrics.go model.go modelsummarywatcher.go modelwatcher.go relation.go resident.go unit.go watcher.go
const (
StatusRed = "red"
StatusYellow = "yellow" // amber?
StatusGreen = "green"
)Status values show a high level indicator of model health.
var (
// IdleFunc allows tests to be able to get callbacks when the controller
// hasn't been given any changes for a specified time.
IdleFunc func()
// IdleTime relates to how long the controller needs to wait with no changes
// to be considered idle.
IdleTime = 50 * time.Millisecond
)type Application struct {
// Resident identifies the application as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Application represents an application in a model.
func (a *Application) CharmURL() string
CharmURL returns the charm url string for this application.
func (a *Application) Config() map[string]interface{}
Config returns a copy of the current application config.
func (a *Application) DisplayStatus() status.StatusInfo
DisplayStatus is used from the status code in the apiserver, and is what we show to the user. For CAAS models, this is a synthetic status based on the application status and the operator status.
func (a *Application) ExpectsWorkload() bool
ExpectsWorkload only makes sense for CAAS applications. If a workload is expected, the charm would have set a podspec. Pod specs are never set for IAAS models.
func (a *Application) Status() status.StatusInfo
Status returns the application status if it is set, and if not it uses the derived status from the units.
func (a *Application) Units() []Unit
Units returns all the units for this application.
func (a *Application) WatchConfig(keys ...string) *ConfigWatcher
WatchConfig creates a watcher for the application config. Do not use this to watch config on behalf of a unit. It is not aware of branch-based config deltas and only deals with master settings.
type ApplicationChange struct {
ModelUUID string
Name string
Exposed bool
CharmURL string
Life life.Value
MinUnits int
Constraints constraints.Value
Annotations map[string]string
Config map[string]interface{}
Subordinate bool
Status status.StatusInfo
OperatorStatus status.StatusInfo // For CAAS applications.
WorkloadVersion string
PodSpec *PodSpec // For CAAS applications.
}ApplicationChange represents either a new application, or a change to an existing application in a model.
type Branch struct {
// Resident identifies the branch as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Branch represents an active branch in a cached model.
func (b *Branch) AppConfig(appName string) settings.ItemChanges
AppConfig returns the configuration changes that apply to the branch for a specific application.
AssignedUnits returns a map of the names of units tracking this branch, keyed by application names with changes made under the branch.
Completed returns a Unix timestamp indicating when this generation was committed.
CreatedBy returns user who committed the branch.
func (b *Branch) Config() map[string]settings.ItemChanges
Config returns the configuration changes that apply to the branch.
Created returns a Unix timestamp indicating when this generation was created.
CreatedBy returns user who created the branch.
Name returns the name of the branch. It is guaranteed to uniquely identify an active branch in the cache.
type BranchChange struct {
ModelUUID string
Id string
Name string
AssignedUnits map[string][]string
Config map[string]settings.ItemChanges
Created int64
CreatedBy string
Completed int64
CompletedBy string
GenerationId int
}BranchChange represents a change to an active model branch. Note that this corresponds to a multi-watcher BranchInfo payload, and that the cache behaviour differs from other entities; when a generation is completed (aborted or committed), it is no longer an active branch and will be removed from the cache.
type Charm struct {
// Resident identifies the charm as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Charm represents an charm in a model.
DefaultConfig returns the default configuration settings for the charm.
func (c *Charm) LXDProfile() lxdprofile.Profile
LXDProfile returns the lxd profile of this charm.
type CharmChange struct {
ModelUUID string
CharmURL string
CharmVersion string
LXDProfile lxdprofile.Profile
DefaultConfig map[string]interface{}
}CharmChange represents either a new charm, or a change to an existing charm in a model.
type CharmConfigWatcher struct {
CharmConfigHashCacheHitInc func()
CharmConfigHashCacheMissInc func()
// contains filtered or unexported fields
}CharmConfigWatcher watches application charm config on behalf of a unit. The watcher will notify if either of the following events cause a change to the unit's effective configuration: - Changes to the charm config settings for the unit's application. - Changes to a model branch being tracked by the unit.
Changes is part of the core watcher definition. The changes channel is never closed.
Err returns the inner tomb's error.
func (w CharmConfigWatcher) Kill()
Kill is part of the worker.Worker interface.
Stop is currently required by the Resources wrapper in the apiserver.
Wait is part of the worker.Worker interface.
Clock defines the clockish methods used by the controller.
type Collector struct {
// contains filtered or unexported fields
}Collector is a prometheus.Collector that collects metrics about the Juju global state.
func NewMetricsCollector(controller *Controller) *Collector
NewMetricsCollector returns a new Collector.
func (c *Collector) Collect(ch chan<- prometheus.Metric)
Collect is part of the prometheus.Collector interface.
func (c *Collector) Describe(ch chan<- *prometheus.Desc)
Describe is part of the prometheus.Collector interface.
type ConfigWatcher struct {
// contains filtered or unexported fields
}ConfigWatcher watches a single entity's configuration. If keys are specified the watcher only signals a change when at least one of those keys changes value. If no keys are specified, any change in the config will trigger the watcher to notify.
func (w ConfigWatcher) Changes() <-chan struct{}Changes is part of the core watcher definition.
func (w ConfigWatcher) Kill()
Kill is part of the worker.Worker interface.
Stop is currently required by the Resources wrapper in the apiserver.
Wait is part of the worker.Worker interface.
type Controller struct {
// contains filtered or unexported fields
}Controller is the primary cached object.
func NewController(config ControllerConfig) (*Controller, error)
NewController creates a new cached controller instance. The changes channel is what is used to supply the cache with the changes in order for the cache to be kept up to date.
func (c *Controller) Kill()
Kill is part of the worker.Worker interface.
func (c *Controller) Mark()
Mark updates all cached entities to indicate they are stale.
func (c *Controller) Model(uuid string) (*Model, error)
Model returns the model for the specified UUID. If the model isn't found, a NotFoundError is returned.
func (c *Controller) ModelUUIDs() []string
ModelUUIDs returns the UUIDs of the models in the cache.
func (c *Controller) Name() string
Name returns the controller-name from the controller config.
func (c *Controller) Report() map[string]interface{}
Report returns information that is used in the dependency engine report.
func (c *Controller) Sweep()
Sweep evicts any stale entities from the cache, cleaning up resources that they are responsible for.
func (c *Controller) Wait() error
Wait is part of the worker.Worker interface.
WaitForModel waits for a time for the specified model to appear in the cache.
func (c *Controller) WatchAllModels() ModelSummaryWatcher
WatchAllModels returns a watcher that will signal whenever there are changes in the summary for that model.
func (c *Controller) WatchModelsAsUser(username string) ModelSummaryWatcher
WatchModelsAsUser returns a watcher that will signal whenever there are changes in the summary for that model. Only models the user can see are included in the results.
type ControllerConfig struct {
// Changes from the event source come over this channel.
// The changes channel must be non-nil.
Changes chan interface{}
// Notify is a callback function used primarily for testing, and is
// called by the controller main processing loop after processing a change.
// The change processed is passed in as the arg to notify.
Notify func(interface{})
}ControllerConfig is a simple config value struct for the controller.
func (c *ControllerConfig) Validate() error
Validate ensures the controller has the right values to be created.
ControllerConfigChange represents the initial controller config, or a change initiated by an admin updating the controller config.
type ControllerGauges struct {
ModelConfigReads prometheus.Gauge
ModelHashCacheHit prometheus.Gauge
ModelHashCacheMiss prometheus.Gauge
ApplicationConfigReads prometheus.Gauge
ApplicationHashCacheHit prometheus.Gauge
ApplicationHashCacheMiss prometheus.Gauge
CharmConfigHashCacheHit prometheus.Gauge
CharmConfigHashCacheMiss prometheus.Gauge
LXDProfileChangeError prometheus.Gauge
LXDProfileChangeNotification prometheus.Gauge
LXDProfileNoChange prometheus.Gauge
}ControllerGauges holds the prometheus gauges for ever increasing values used by the controller.
func (c *ControllerGauges) Collect(ch chan<- prometheus.Metric)
Collect is part of the prometheus.Collector interface.
func (c *ControllerGauges) Describe(ch chan<- *prometheus.Desc)
Describe is part of the prometheus.Collector interface.
type Endpoint struct {
Application string
Name string
Role string
Interface string
Optional bool
Limit int
Scope string
}Endpoint holds all relevant information about a relation endpoint.
type Machine struct {
// Resident identifies the machine as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Machine represents a machine in a model.
CharmProfiles returns the cached list of charm profiles for the machine.
Config returns configuration settings for the machine.
func (m *Machine) ContainerType() instance.ContainerType
ContainerType returns the cached container type hosting this machine.
Id returns the id string of this machine.
InstanceId returns the provider specific instance id for this machine and returns not provisioned if instance ID is empty.
IsManual returns true if the machine was manually provisioned.
Units returns all the units that have been assigned to the machine including subordinates.
func (m *Machine) WatchContainers() (*PredicateStringsWatcher, error)
WatchContainers creates a PredicateStringsWatcher (strings watcher) to notify about added and removed containers on this machine. The initial event contains a slice of the current container machine ids.
func (m *Machine) WatchLXDProfileVerificationNeeded() (*MachineLXDProfileWatcher, error)
WatchLXDProfileVerificationNeeded notifies if any of the following happen relative to this machine:
1. A new unit whose charm has an LXD profile is added. 2. A unit being removed has a profile and other units exist on the machine. 3. The LXD profile of an application with a unit on this machine is added, removed, or exists. 4. The machine's instanceId is changed, indicating it has been provisioned.
type MachineAppModeler interface {
Application(string) (Application, error)
Charm(string) (Charm, error)
Unit(string) (Unit, error)
}MachineAppModeler is a point of use model for MachineLXDProfileWatcher to get Applications, Charms and Units.
type MachineChange struct {
ModelUUID string
Id string
InstanceId string
AgentStatus status.StatusInfo
InstanceStatus status.StatusInfo
Life life.Value
Annotations map[string]string
Config map[string]interface{}
Series string
ContainerType string
IsManual bool
SupportedContainers []instance.ContainerType
SupportedContainersKnown bool
HardwareCharacteristics *instance.HardwareCharacteristics
CharmProfiles []string
Addresses []network.ProviderAddress
HasVote bool
WantsVote bool
}MachineChange represents either a new machine, or a change to an existing machine in a model.
type MachineLXDProfileWatcher struct {
// contains filtered or unexported fields
}func (w MachineLXDProfileWatcher) Changes() <-chan struct{}Changes is part of the core watcher definition.
func (w MachineLXDProfileWatcher) Kill()
Kill is part of the worker.Worker interface.
Stop is currently required by the Resources wrapper in the apiserver.
Wait is part of the worker.Worker interface.
type MachineLXDProfileWatcherConfig struct {
// contains filtered or unexported fields
}type Model struct {
// Resident identifies the model as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Model is a cached model in the controller. The model is kept up to date with changes flowing into the cached controller.
func (m *Model) Application(appName string) (Application, error)
Application returns the application for the input name. If the application is not found, a NotFoundError is returned.
func (m *Model) Applications() map[string]Application
Applications makes a copy of the model's application collection and returns it.
Branch returns the branch with the input name. If the branch is not found, a NotFoundError is returned. All API-level logic identifies active branches by their name whereas they are managed in the cache by ID - we iterate over the map to locate them. We do not expect many active branches to exist at once, so the performance should be acceptable.
Branches returns all active branches in the model.
Charm returns the charm for the input charmURL. If the charm is not found, a NotFoundError is returned.
Config returns the current model config.
Machine returns the machine with the input id. If the machine is not found, a NotFoundError is returned.
Machines makes a copy of the model's machine collection and returns it.
func (m *Model) Metrics() *ControllerGauges
Metrics returns the metrics of the model
Name returns the current model's name.
Relation returns the relation with the specified key. If the relation is not found, a NotFoundError is returned.
Relations returns all relations in the model.
Report returns information that is used in the dependency engine report.
func (m *Model) Summary() (ModelSummary, string)
Summary returns a copy of the current summary, and its hash.
Type returns the model type for this model, either "iaas" or "caas".
UUID returns the model's model-uuid.
Unit returns the unit with the input name. If the unit is not found, a NotFoundError is returned.
Units returns all units in the model.
func (m *Model) WaitForUnit(name string, predicate func(*Unit) bool, cancel <-chan struct{}) <-chan struct{}
WaitForUnit is the second attempt at providing a genericish way to wait for the cache to be updated. The method subscribes to the hub with the topic "unit-change.<source>". The expected payload is a *Unit. The method effectively runs another goroutine that will close the result channel when the field is updated to the expected value, or the cancel channel is signalled. This method is not responsible for checking the current value, it only deals with changes.
func (m *Model) WatchConfig(keys ...string) *ConfigWatcher
WatchConfig creates a watcher for the model config.
func (m *Model) WatchMachines() (*PredicateStringsWatcher, error)
WatchMachines returns a PredicateStringsWatcher to notify about added and removed machines in the model. The initial event contains a slice of the current machine ids. Containers are excluded.
type ModelChange struct {
ModelUUID string
Name string
Type model.ModelType
Life life.Value
Owner string // tag maybe?
IsController bool
Cloud string
CloudRegion string
CloudCredential string
Annotations map[string]string
Config map[string]interface{}
Status status.StatusInfo
UserPermissions map[string]permission.Access
}ModelChange represents either a new model, or a change to an existing model.
type ModelSummary struct {
UUID string
// Removed indicates that the user can no longer see this model, because it has
// either been removed, or there access revoked.
Removed bool
Controller string
Namespace string
Name string
Admins []string
Status string
Annotations map[string]string
// Messages contain status message for any unit status in error.
Messages []ModelSummaryMessage
Cloud string
Region string
Credential string
LastModified time.Time // Currently missing in cache and underlying db model.
// MachineCount is just top level machines.
MachineCount int
ContainerCount int
ApplicationCount int
UnitCount int
RelationCount int
}ModelSummary represents a high level view of a model. Primary use case is to drive a dashboard with model level overview.
ModelSummaryMessage holds information about an error message from an agent, and when that message was set.
type ModelSummaryWatcher interface {
Watcher
Changes() <-chan []ModelSummary
}ModelSummaryWatcher will return a slice for all existing models
ModelWatcher will pass back models added to the cache.
NotifyWatcher will only say something changed.
PodSpec is used to determine whether or not a CAAS application has called the command to set the pod spec.
type PredicateStringsWatcher struct {
// contains filtered or unexported fields
}PredicateStringsWatcher notifies that something changed, with a slice of strings. The predicateFunc will test the values before notification. An initial event is sent with the input given at creation.
Changes is part of the core watcher definition. The changes channel is never closed.
Err returns the inner tomb's error.
func (w PredicateStringsWatcher) Kill()
Kill is part of the worker.Worker interface.
Stop is currently required by the Resources wrapper in the apiserver.
Wait is part of the worker.Worker interface.
type Relation struct {
// Resident identifies the relation as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Relation represents a relation in a cached model.
Endpoints returns the endpoints for this relation.
Key returns the key of this relation.
RelationChange represents either a new relation, or a change to an existing relation in a model.
RemoveApplication represents the situation when an application is removed from a model in the database.
RemoveBranch represents the situation when a branch is to be removed from the cache. This will rarely be a result of deletion from the database. It will usually be the result of the branch no longer being considered "in-flight" due to being committed or aborted.
RemoveCharm represents the situation when an charm is removed from a model in the database.
RemoveMachine represents the situation when a machine is removed from a model in the database.
RemoveModel represents the situation when a model is removed from the database.
RemoveRelation represents the situation when a relation is removed from a model in the database.
RemoveUnit represents the situation when a unit is removed from a model in the database.
type Resident struct {
// contains filtered or unexported fields
}Resident is the base class for entities managed in the cache.
CacheId returns the unique ID for this cache resident.
StringsWatcher will return what has changed.
type Unit struct {
// Resident identifies the unit as a type-agnostic cached entity
// and tracks resources that it is responsible for cleaning up.
*Resident
// contains filtered or unexported fields
}Unit represents a unit in a cached model.
func (u *Unit) AgentStatus() status.StatusInfo
AgentStatus returns the agent status of the unit.
Application returns the application name of this unit.
CharmURL returns the charm URL for this unit's application.
ConfigSettings returns the effective charm configuration for this unit taking into account whether it is tracking a model branch.
func (u *Unit) DisplayWorkloadStatus() status.StatusInfo
DisplayWorkloadStatus returns the workload status of the unit. For CAAS models, the cloud container status is used over the unit if the cloud container status in certain circumstances.
Life returns the current life of the unit.
MachineId returns the ID of the machine hosting this unit.
Name returns the name of this unit.
func (u *Unit) OpenPortRangesByEndpoint() network.GroupedPortRanges
OpenbPortRangesByEndpoint returns a map where keys are endpoint names and values are the port ranges opened by the unit for each endpoint.
Principal returns the name of the principal unit for the same application.
Subordinate returns a bool indicating whether this unit is a subordinate.
func (u *Unit) WatchConfigSettings() (*CharmConfigWatcher, error)
WatchConfigSettings returns a new watcher that will notify when the effective application charm config for this unit changes.
func (u *Unit) WorkloadStatus() status.StatusInfo
WorkloadStatus returns the workload status of the unit.
type UnitChange struct {
ModelUUID string
Name string
Application string
Series string
Annotations map[string]string
CharmURL string
Life life.Value
PublicAddress string
PrivateAddress string
MachineId string
OpenPortRangesByEndpoint network.GroupedPortRanges
Principal string
Subordinate bool
WorkloadStatus status.StatusInfo
AgentStatus status.StatusInfo
ContainerStatus status.StatusInfo // For CAAS models.
}UnitChange represents either a new unit, or a change to an existing unit in a model.
type Watcher interface {
worker.Worker
// Stop is currently needed by the apiserver until the resources
// work on workers instead of things that can be stopped.
Stop() error
}Watcher is the common methods
| Path | Synopsis |
|---|---|
| cachetest |
Package cache imports 29 packages (graph) and is imported by 37 packages. Updated 2020-09-24. Refresh now. Tools for package owners.