Documentation

Index

Constants

View Source
const (
	// JujuDbSnap is the snap of MongoDB that Juju uses.
	JujuDbSnap = "juju-db"

	// WiredTiger is a storage type introduced in 3
	WiredTiger StorageEngine = "wiredTiger"

	// SnapTrack is the track to get the juju-db snap from
	SnapTrack = "4.0"

	// SnapRisk is which juju-db snap to use i.e. stable or edge.
	SnapRisk = "stable"
)
View Source
const (
	// ServiceName is the name of the service that Juju's mongod instance
	// will be named.
	ServiceName = "juju-db"

	// SharedSecretFile is the name of the Mongo shared secret file
	// located within the Juju data directory.
	SharedSecretFile = "shared-secret"

	// ReplicaSetName is the name of the replica set that juju uses for its
	// controllers.
	ReplicaSetName = "juju"

	// LowCacheSize expressed in GB sets the max value Mongo WiredTiger cache can
	// reach, down to 256MB.
	LowCacheSize = 0.25

	// FileNameDBSSLKey is the file name of db ssl key file name.
	FileNameDBSSLKey = "server.pem"
)
View Source
const AdminUser = "admin"

    AdminUser is the name of the user that is initially created in mongo.

    View Source
    const SocketTimeout = time.Minute

      SocketTimeout should be long enough that even a slow mongo server will respond in that length of time, and must also be long enough to allow for completion of heavyweight queries.

      Note: 1 minute is mgo's default socket timeout value.

      Also note: We have observed mongodb occasionally getting "stuck" for over 30s in the field.

      Variables

      View Source
      var IsMaster = isMaster

        IsMaster returns a boolean that represents whether the given machine's peer address is the primary mongo host for the replicaset

        View Source
        var JujuDbSnapMongodPath = "/snap/bin/juju-db.mongod"

          JujuDbSnapMongodPath is the path that the juju-db snap makes mongod available at

          Functions

          func DialInfo

          func DialInfo(info Info, opts DialOpts) (*mgo.DialInfo, error)

            DialInfo returns information on how to dial the state's mongo server with the given info and dial options.

            func DialWithInfo

            func DialWithInfo(info MongoInfo, opts DialOpts) (*mgo.Session, error)

              DialWithInfo establishes a new session to the cluster identified by info, with the specified options. If either Tag or Password are specified, then a Login call on the admin database will be made.

              func EnsureServer

              func EnsureServer(args EnsureServerParams) error

                EnsureServer ensures that the MongoDB server is installed, configured, and ready to run.

                This method will remove old versions of the mongo init service as necessary before installing the new version.

                func GenerateSSLKey

                func GenerateSSLKey(cert, privateKey string) string

                  GenerateSSLKey combines cert and private key to generate the ssl key - server.pem.

                  func GenerateSharedSecret

                  func GenerateSharedSecret() (string, error)

                    GenerateSharedSecret generates a pseudo-random shared secret (keyfile) for use with Mongo replica sets.

                    func GetOplog

                    func GetOplog(session *mgo.Session) *mgo.Collection

                      GetOplog returns the the oplog collection in the local database.

                      func Login

                      func Login(session *mgo.Session, user, password string) error

                        Login logs in to the mongodb admin database.

                        func MaybeUnauthorizedf

                        func MaybeUnauthorizedf(err error, message string, args ...interface{}) error

                          MaybeUnauthorizedf checks if the cause of the given error is a Mongo authorization error, and if so, wraps the error with errors.Unauthorizedf.

                          func NewMongoTimestamp

                          func NewMongoTimestamp(t time.Time) bson.MongoTimestamp

                            NewMongoTimestamp returns a bson.MongoTimestamp repesentation for the time.Time given. Note that these timestamps are not the same the usual MongoDB time fields. These are an internal format used only in a few places such as the replication oplog.

                            See: http://docs.mongodb.org/manual/reference/bson-types/#timestamps

                            func NewOplogSession

                            func NewOplogSession(collection *mgo.Collection, query bson.D) *oplogSession

                              NewOplogSession defines a new OplogSession.

                              Arguments: - "collection" is the collection to use for the oplog. Typically this

                              would be the result of GetOpLog.
                              

                              - "query" can be used to limit the returned oplog entries. A

                              typical filter would limit based on ns ("<database>.<collection>")
                              and o (object).
                              

                              The returned session should be `Close`d when it's no longer needed.

                              func SelectPeerAddress

                              func SelectPeerAddress(addrs network.ProviderAddresses) string

                                SelectPeerAddress returns the address to use as the mongo replica set peer address by selecting it from the given addresses. If no addresses are available an empty string is returned.

                                func SetAdminMongoPassword

                                func SetAdminMongoPassword(session *mgo.Session, user, password string) error

                                  SetAdminMongoPassword sets the administrative password to access a mongo database. If the password is non-empty, all subsequent attempts to access the database must be authorized; otherwise no authorization is required.

                                  func UpdateSSLKey

                                  func UpdateSSLKey(dataDir, cert, privateKey string) error

                                    UpdateSSLKey writes a new SSL key used by mongo to validate connections from Juju controller(s)

                                    Types

                                    type Collection

                                    type Collection interface {
                                    
                                    	// Name returns the name of the collection.
                                    	Name() string
                                    
                                    	// Count, Find, and FindId methods act as documented for *mgo.Collection.
                                    	Count() (int, error)
                                    	Find(query interface{}) Query
                                    	FindId(id interface{}) Query
                                    	Pipe(pipeline interface{}) *mgo.Pipe
                                    
                                    	// Writeable gives access to methods that enable direct DB access. It
                                    	// should be used with judicious care, and for only the best of reasons.
                                    	Writeable() WriteCollection
                                    }

                                      Collection imperfectly insulates clients from the capacity to write to MongoDB. Query results can still be used to write; and the Writeable method exposes the underlying *mgo.Collection when absolutely required; but the general expectation in juju is that writes will occur only via mgo/txn, and any layer-skipping is done only in exceptional and well- supported circumstances.

                                      func CollectionFromName

                                      func CollectionFromName(db *mgo.Database, coll string) (Collection, func())

                                        CollectionFromName returns a named collection on the specified database, initialised with a new session. Also returned is a close function which must be called when the collection is no longer required.

                                        func WrapCollection

                                        func WrapCollection(coll *mgo.Collection) Collection

                                          WrapCollection returns a Collection that wraps the supplied *mgo.Collection.

                                          type ConfigArgs

                                          type ConfigArgs struct {
                                          	Clock clock.Clock
                                          
                                          	DataDir    string
                                          	DBDir      string
                                          	ReplicaSet string
                                          
                                          	// connection params
                                          	BindIP      string
                                          	BindToAllIP bool
                                          	Port        int
                                          	OplogSizeMB int
                                          
                                          	// auth
                                          	AuthKeyFile    string
                                          	PEMKeyFile     string
                                          	PEMKeyPassword string
                                          
                                          	// network params
                                          	IPv6             bool
                                          	TLSOnNormalPorts bool
                                          	TLSMode          string
                                          
                                          	// logging
                                          	Syslog    bool
                                          	LogAppend bool
                                          	LogPath   string
                                          
                                          	// db kernel
                                          	MemoryProfile         MemoryProfile
                                          	WiredTigerCacheSizeGB float32
                                          
                                          	// misc
                                          	Quiet bool
                                          }

                                            ConfigArgs holds the attributes of a service configuration for mongo.

                                            type DialOpts

                                            type DialOpts struct {
                                            	// Timeout is the amount of time to wait contacting
                                            	// a controller.
                                            	Timeout time.Duration
                                            
                                            	// SocketTimeout is the amount of time to wait for a
                                            	// non-responding socket to the database before it is forcefully
                                            	// closed. If this is zero, the value of the SocketTimeout const
                                            	// will be used.
                                            	SocketTimeout time.Duration
                                            
                                            	// Direct informs whether to establish connections only with the
                                            	// specified seed servers, or to obtain information for the whole
                                            	// cluster and establish connections with further servers too.
                                            	Direct bool
                                            
                                            	// PostDial, if non-nil, is called by DialWithInfo with the
                                            	// mgo.Session after a successful dial but before DialWithInfo
                                            	// returns to its caller.
                                            	PostDial func(*mgo.Session) error
                                            
                                            	// PostDialServer, if non-nil, is called by DialWithInfo after
                                            	// dialing a MongoDB server connection, successfully or not.
                                            	// The address dialed and amount of time taken are included,
                                            	// as well as the error if any.
                                            	PostDialServer func(addr string, _ time.Duration, _ error)
                                            
                                            	// PoolLimit defines the per-server socket pool limit
                                            	PoolLimit int
                                            }

                                              DialOpts holds configuration parameters that control the Dialing behavior when connecting to a controller.

                                              func DefaultDialOpts

                                              func DefaultDialOpts() DialOpts

                                                DefaultDialOpts returns a DialOpts representing the default parameters for contacting a controller.

                                                NOTE(axw) these options are inappropriate for tests in CI, as CI tends to run on machines with slow I/O (or thrashed I/O with limited IOPs). For tests, use mongotest.DialOpts().

                                                type EnsureServerParams

                                                type EnsureServerParams struct {
                                                	// APIPort is the port to connect to the api server.
                                                	APIPort int
                                                
                                                	// StatePort is the port to connect to the mongo server.
                                                	StatePort int
                                                
                                                	// Cert is the certificate.
                                                	Cert string
                                                
                                                	// PrivateKey is the certificate's private key.
                                                	PrivateKey string
                                                
                                                	// CAPrivateKey is the CA certificate's private key.
                                                	CAPrivateKey string
                                                
                                                	// SharedSecret is a secret shared between mongo servers.
                                                	SharedSecret string
                                                
                                                	// SystemIdentity is the identity of the system.
                                                	SystemIdentity string
                                                
                                                	// DataDir is the machine agent data directory.
                                                	DataDir string
                                                
                                                	// ConfigDir is where mongo config goes.
                                                	ConfigDir string
                                                
                                                	// Namespace is the machine agent's namespace, which is used to
                                                	// generate a unique service name for Mongo.
                                                	Namespace string
                                                
                                                	// OplogSize is the size of the Mongo oplog.
                                                	// If this is zero, then EnsureServer will
                                                	// calculate a default size according to the
                                                	// algorithm defined in Mongo.
                                                	OplogSize int
                                                
                                                	// SetNUMAControlPolicy preference - whether the user
                                                	// wants to set the numa control policy when starting mongo.
                                                	SetNUMAControlPolicy bool
                                                
                                                	// MemoryProfile determines which value is going to be used by
                                                	// the cache and future memory tweaks.
                                                	MemoryProfile MemoryProfile
                                                
                                                	// The channel for installing the mongo snap in focal and later.
                                                	JujuDBSnapChannel string
                                                }

                                                  EnsureServerParams is a parameter struct for EnsureServer.

                                                  type Info

                                                  type Info struct {
                                                  	// Addrs gives the addresses of the MongoDB servers for the state.
                                                  	// Each address should be in the form address:port.
                                                  	Addrs []string
                                                  
                                                  	// CACert holds the CA certificate that will be used
                                                  	// to validate the controller's certificate, in PEM format.
                                                  	CACert string
                                                  
                                                  	// DisableTLS controls whether the connection to MongoDB servers
                                                  	// is made using TLS (the default), or not.
                                                  	DisableTLS bool
                                                  }

                                                    Info encapsulates information about cluster of mongo servers and can be used to make a connection to that cluster.

                                                    type Iterator

                                                    type Iterator interface {
                                                    	Next(interface{}) bool
                                                    	Timeout() bool
                                                    	Close() error
                                                    }

                                                      Iterator defines the parts of the mgo.Iter that we use - this interface allows us to switch out the querying for testing.

                                                      type MemoryProfile

                                                      type MemoryProfile string

                                                        MemoryProfile represents a type of meory configuration for Mongo.

                                                        const (
                                                        	// MemoryProfileLow will use as little memory as possible in mongo.
                                                        	MemoryProfileLow MemoryProfile = "low"
                                                        	// MemoryProfileDefault will use mongo config ootb.
                                                        	MemoryProfileDefault MemoryProfile = "default"
                                                        )

                                                        func NewMemoryProfile

                                                        func NewMemoryProfile(m string) (MemoryProfile, error)

                                                          NewMemoryProfile returns a Memory Profile from the passed value.

                                                          func (MemoryProfile) String

                                                          func (m MemoryProfile) String() string

                                                            String returns a string representation of this profile value.

                                                            func (MemoryProfile) Validate

                                                            func (m MemoryProfile) Validate() error

                                                            type MongoInfo

                                                            type MongoInfo struct {
                                                            	// mongo.Info contains the addresses and cert of the mongo cluster.
                                                            	Info
                                                            
                                                            	// Tag holds the name of the entity that is connecting.
                                                            	// It should be nil when connecting as an administrator.
                                                            	Tag names.Tag
                                                            
                                                            	// Password holds the password for the connecting entity.
                                                            	Password string
                                                            }

                                                              MongoInfo encapsulates information about cluster of servers holding juju state and can be used to make a connection to that cluster.

                                                              type MongodFinder

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

                                                                MongodFinder searches expected paths to find a version of Mongo and determine what version it is.

                                                                func NewMongodFinder

                                                                func NewMongodFinder() *MongodFinder

                                                                  NewMongodFinder returns a type that will help search for mongod, using normal OS tools.

                                                                  func (*MongodFinder) InstalledAt

                                                                  func (m *MongodFinder) InstalledAt() (string, error)

                                                                    InstalledAt tries to find an installed mongo snap.

                                                                    type OSSearchTools

                                                                    type OSSearchTools struct{}

                                                                    func (OSSearchTools) Exists

                                                                    func (OSSearchTools) Exists(name string) bool

                                                                    func (OSSearchTools) GetCommandOutput

                                                                    func (OSSearchTools) GetCommandOutput(name string, arg ...string) (string, error)

                                                                    type OplogDoc

                                                                    type OplogDoc struct {
                                                                    	Timestamp    bson.MongoTimestamp `bson:"ts"`
                                                                    	OperationId  int64               `bson:"h"`
                                                                    	MongoVersion int                 `bson:"v"`
                                                                    	Operation    string              `bson:"op"` // "i" - insert, "u" - update, "d" - delete
                                                                    	Namespace    string              `bson:"ns"`
                                                                    	Object       *bson.Raw           `bson:"o"`
                                                                    	UpdateObject *bson.Raw           `bson:"o2"`
                                                                    }

                                                                      OplogDoc represents a document in the oplog.rs collection. See: http://www.kchodorow.com/blog/2010/10/12/replication-internals/

                                                                      The Object and UpdateObject fields are returned raw to allow unmarshalling into arbitrary types. Use the UnmarshalObject and UnmarshalUpdate methods to unmarshall these fields.

                                                                      func (*OplogDoc) UnmarshalObject

                                                                      func (d *OplogDoc) UnmarshalObject(out interface{}) error

                                                                        UnmarshalObject unmarshals the Object field into out. The out argument should be a pointer or a suitable map.

                                                                        func (*OplogDoc) UnmarshalUpdate

                                                                        func (d *OplogDoc) UnmarshalUpdate(out interface{}) error

                                                                          UnmarshalUpdate unmarshals the UpdateObject field into out. The out argument should be a pointer or a suitable map.

                                                                          type OplogSession

                                                                          type OplogSession interface {
                                                                          	NewIter(bson.MongoTimestamp, []int64) Iterator
                                                                          	Close()
                                                                          }

                                                                            OplogSession represents a connection to the oplog store, used to create an iterator to get oplog documents (and recreate it if it gets killed or times out).

                                                                            type OplogTailer

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

                                                                              OplogTailer tails MongoDB's replication oplog.

                                                                              func NewOplogTailer

                                                                              func NewOplogTailer(
                                                                              	session OplogSession,
                                                                              	initialTs time.Time,
                                                                              ) *OplogTailer

                                                                                NewOplogTailer returns a new OplogTailer.

                                                                                Arguments: - "session" determines the collection and filtering on records that

                                                                                should be returned.
                                                                                

                                                                                - "initialTs" sets the operation timestamp to start returning

                                                                                results from. This can be used to avoid an expensive initial search
                                                                                through the oplog when the tailer first starts.
                                                                                

                                                                                Remember to call Stop on the returned OplogTailer when it is no longer needed.

                                                                                func (*OplogTailer) Dying

                                                                                func (t *OplogTailer) Dying() <-chan struct{}

                                                                                  Dying returns a channel that will be closed with the OplogTailer is shutting down.

                                                                                  func (*OplogTailer) Err

                                                                                  func (t *OplogTailer) Err() error

                                                                                    Err returns the error that caused the OplogTailer to stop. If it finished normally or hasn't stopped then nil will be returned.

                                                                                    func (*OplogTailer) Out

                                                                                    func (t *OplogTailer) Out() <-chan *OplogDoc

                                                                                      Out returns a channel that reports the oplog entries matching the query passed to NewOplogTailer as they appear.

                                                                                      func (*OplogTailer) Stop

                                                                                      func (t *OplogTailer) Stop() error

                                                                                        Stop shuts down the OplogTailer. It will block until shutdown is complete.

                                                                                        type Query

                                                                                        type Query interface {
                                                                                        	All(result interface{}) error
                                                                                        	Apply(change mgo.Change, result interface{}) (info *mgo.ChangeInfo, err error)
                                                                                        	Batch(n int) Query
                                                                                        	Comment(comment string) Query
                                                                                        	Count() (n int, err error)
                                                                                        	Distinct(key string, result interface{}) error
                                                                                        	Explain(result interface{}) error
                                                                                        	For(result interface{}, f func() error) error
                                                                                        	Hint(indexKey ...string) Query
                                                                                        	Iter() Iterator
                                                                                        	Limit(n int) Query
                                                                                        	LogReplay() Query
                                                                                        	MapReduce(job *mgo.MapReduce, result interface{}) (info *mgo.MapReduceInfo, err error)
                                                                                        	One(result interface{}) (err error)
                                                                                        	Prefetch(p float64) Query
                                                                                        	Select(selector interface{}) Query
                                                                                        	SetMaxScan(n int) Query
                                                                                        	SetMaxTime(d time.Duration) Query
                                                                                        	Skip(n int) Query
                                                                                        	Snapshot() Query
                                                                                        	Sort(fields ...string) Query
                                                                                        	Tail(timeout time.Duration) *mgo.Iter
                                                                                        }

                                                                                          Query allows access to a portion of a MongoDB collection.

                                                                                          type SearchTools

                                                                                          type SearchTools interface {
                                                                                          	// GetCommandOutput execs the given command, and returns the CombinedOutput, or any error that occurred.
                                                                                          	GetCommandOutput(name string, arg ...string) (string, error)
                                                                                          
                                                                                          	// Exists just returns if a given path is available (eg os.Stat() has a value)
                                                                                          	Exists(string) bool
                                                                                          }

                                                                                            SearchTools represents the OS functionality we need to find the correct MongoDB executable. The mock for this (used in testing) is automatically generated by 'go generate' from the following line

                                                                                            type StorageEngine

                                                                                            type StorageEngine string

                                                                                              StorageEngine represents the storage used by mongo.

                                                                                              type WithAddresses

                                                                                              type WithAddresses interface {
                                                                                              	Addresses() network.SpaceAddresses
                                                                                              }

                                                                                                WithAddresses represents an entity that has a set of addresses. e.g. a state Machine object

                                                                                                type WriteCollection

                                                                                                type WriteCollection interface {
                                                                                                	Collection
                                                                                                
                                                                                                	// Underlying returns the underlying *mgo.Collection.
                                                                                                	Underlying() *mgo.Collection
                                                                                                
                                                                                                	// All other methods act as documented for *mgo.Collection.
                                                                                                	Insert(docs ...interface{}) error
                                                                                                	Upsert(selector interface{}, update interface{}) (info *mgo.ChangeInfo, err error)
                                                                                                	UpsertId(id interface{}, update interface{}) (info *mgo.ChangeInfo, err error)
                                                                                                	Update(selector interface{}, update interface{}) error
                                                                                                	UpdateId(id interface{}, update interface{}) error
                                                                                                	Remove(sel interface{}) error
                                                                                                	RemoveId(id interface{}) error
                                                                                                	RemoveAll(sel interface{}) (*mgo.ChangeInfo, error)
                                                                                                }

                                                                                                  WriteCollection allows read/write access to a MongoDB collection.

                                                                                                  Directories

                                                                                                  Path Synopsis
                                                                                                  Package mongometrics contains MongodB-related Prometheus metric collectors.
                                                                                                  Package mongometrics contains MongodB-related Prometheus metric collectors.