util

Documentation

Overview

Package util implements various utility functions used in both testing and implementation of Kubernetes. Package util may not depend on any other package in the Kubernetes package tree.

Index

• Variables
• func AllPtrFieldsNil(obj interface{}) bool
• func ApplyRLimitForSelf(maxOpenFiles uint64)
• func CertPoolFromFile(filename string) (*x509.CertPool, error)
• func CertsFromPEM(pemCerts []byte) ([]*x509.Certificate, error)
• func CompileRegexps(regexpStrings []string) ([]*regexp.Regexp, error)
• func DeadlockWatchdog(lock sync.Locker, name string, maxLockPeriod time.Duration)
• func DeadlockWatchdogReadLock(lock *sync.RWMutex, name string, maxLockPeriod time.Duration)
• func EncodePrivateKey(private *rsa.PrivateKey) []byte
• func EncodePublicKey(public *rsa.PublicKey) ([]byte, error)
• func EncodeSSHKey(public *rsa.PublicKey) ([]byte, error)
• func ExecuteTemplate(w io.Writer, templateText string, data interface{}) error
• func ExecuteTemplateToString(templateText string, data interface{}) (string, error)
• func FileExists(filename string) (bool, error)
• func FlushLogs()
• func Forever(f func(), period time.Duration)
• func GenerateKey(bits int) (*rsa.PrivateKey, *rsa.PublicKey, error)
• func GenerateSelfSignedCert(host, certPath, keyPath string, alternateIPs []net.IP, alternateDNS []string) error
• func GetIntOrPercentValue(intOrStr *intstr.IntOrString) (int, bool, error)
• func GetValueFromPercent(percent int, value int) int
• func InitFlags()
• func InitLogs()
• func IntPtr(i int) *int
• func IntPtrDerefOr(ptr *int, def int) int
• func MakePrivateKeySignerFromBytes(buffer []byte) (ssh.Signer, error)
• func MakePrivateKeySignerFromFile(key string) (ssh.Signer, error)
• func NewCRLFWriter(w io.Writer) io.Writer
• func NewLogger(prefix string) *log.Logger
• func NewUUID() types.UID
• func ObjectDiff(a, b interface{}) string
• func ObjectGoPrintDiff(a, b interface{}) string
• func ObjectGoPrintSideBySide(a, b interface{}) string
• func ParsePublicKeyFromFile(keyFile string) (*rsa.PublicKey, error)
• func ReadDirNoExit(dirname string) ([]os.FileInfo, []error, error)
• func RunInResourceContainer(containerName string) error
• func RunSSHCommand(cmd, user, host string, signer ssh.Signer) (string, string, int, error)
• func StringDiff(a, b string) string
• func Umask(mask int) (old int, err error)
• func Until(f func(), period time.Duration, stopCh <-chan struct{})
• func UsingSystemdInitSystem() bool
• func WarnWordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName
• func WordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName
• type Backoff
  • func NewBackOff(initial, max time.Duration) *Backoff
  • func (p *Backoff) GC()
  • func (p *Backoff) Get(id string) time.Duration
  • func (p *Backoff) IsInBackOffSince(id string, eventTime time.Time) bool
  • func (p *Backoff) IsInBackOffSinceUpdate(id string, eventTime time.Time) bool
  • func (p *Backoff) Next(id string, eventTime time.Time)
  • func (p *Backoff) Reset(id string)
• type BoolFlag
  • func (f *BoolFlag) Default(value bool)
  • func (f BoolFlag) Provided() bool
  • func (f *BoolFlag) Set(value string) error
  • func (f BoolFlag) String() string
  • func (f *BoolFlag) Type() string
  • func (f BoolFlag) Value() bool
• type Cache
  • func NewCache(maxSize int) Cache
  • func (c *Cache) Add(index uint64, obj interface{}) bool
  • func (c *Cache) Get(index uint64) (obj interface{}, found bool)
• type Clock
• type ConfigurationMap
  • func (m *ConfigurationMap) Set(value string) error
  • func (m *ConfigurationMap) String() string
  • func (*ConfigurationMap) Type() string
• type FakeClock
  • func (f *FakeClock) Now() time.Time
  • func (f *FakeClock) Since(ts time.Time) time.Duration
  • func (f *FakeClock) Step(d time.Duration)
• type GlogWriter
  • func (writer GlogWriter) Write(data []byte) (n int, err error)
• type IntervalClock
  • func (i *IntervalClock) Now() time.Time
  • func (i *IntervalClock) Since(ts time.Time) time.Duration
• type LineDelimiter
  • func NewLineDelimiter(output io.Writer, delimiter string) *LineDelimiter
  • func (ld *LineDelimiter) Flush() (err error)
  • func (ld *LineDelimiter) Write(buf []byte) (n int, err error)
• type RateLimiter
  • func NewFakeRateLimiter() RateLimiter
  • func NewTokenBucketRateLimiter(qps float32, burst int) RateLimiter
• type RealClock
  • func (r RealClock) Now() time.Time
  • func (r RealClock) Since(ts time.Time) time.Duration
• type Runner
  • func NewRunner(f ...func(stop chan struct{})) *Runner
  • func (r *Runner) Start()
  • func (r *Runner) Stop()
• type SSHTunnel
  • func NewSSHTunnel(user, keyfile, host string) (*SSHTunnel, error)
  • func NewSSHTunnelFromBytes(user string, privateKey []byte, host string) (*SSHTunnel, error)
  • func (s *SSHTunnel) Close() error
  • func (s *SSHTunnel) Dial(network, address string) (net.Conn, error)
  • func (s *SSHTunnel) Open() error
• type SSHTunnelEntry
• type SSHTunnelList
  • func MakeSSHTunnels(user, keyfile string, addresses []string) *SSHTunnelList
  • func (l *SSHTunnelList) Close()
  • func (l *SSHTunnelList) Has(addr string) bool
  • func (l *SSHTunnelList) Len() int
  • func (l *SSHTunnelList) Open() error
  • func (l *SSHTunnelList) PickRandomTunnel() (SSHTunnelEntry, error)
• type StringFlag
  • func NewStringFlag(defaultVal string) StringFlag
  • func (f *StringFlag) Default(value string)
  • func (f StringFlag) Provided() bool
  • func (f *StringFlag) Set(value string) error
  • func (f StringFlag) String() string
  • func (f *StringFlag) Type() string
  • func (f StringFlag) Value() string
• type Trace
  • func NewTrace(name string) *Trace
  • func (t *Trace) Log()
  • func (t *Trace) LogIfLong(threshold time.Duration)
  • func (t *Trace) Step(msg string)
  • func (t *Trace) TotalTime() time.Duration

Variables

var ForeverTestTimeout = time.Second * 30

For any test of the style:

...
<- time.After(timeout):
   t.Errorf("Timed out")

The value for timeout should effectively be "forever." Obviously we don't want our tests to truly lock up forever, but 30s is long enough that it is effectively forever for the things that can slow down a run on a heavily contended machine (GC, seeks, etc), but not so long as to make a developer ctrl-c a test run if they do happen to break that test.

var NeverStop <-chan struct{} = make(chan struct{})

NeverStop may be passed to Until to make it never stop.

Functions

func AllPtrFieldsNil

func AllPtrFieldsNil(obj interface{}) bool

Tests whether all pointer fields in a struct are nil. This is useful when, for example, an API struct is handled by plugins which need to distinguish "no plugin accepted this spec" from "this spec is empty".

This function is only valid for structs and pointers to structs. Any other type will cause a panic. Passing a typed nil pointer will return true.

func ApplyRLimitForSelf

func ApplyRLimitForSelf(maxOpenFiles uint64)

func CertPoolFromFile

func CertPoolFromFile(filename string) (*x509.CertPool, error)

CertPoolFromFile returns an x509.CertPool containing the certificates in the given PEM-encoded file. Returns an error if the file could not be read, a certificate could not be parsed, or if the file does not contain any certificates

func CertsFromPEM

func CertsFromPEM(pemCerts []byte) ([]*x509.Certificate, error)

CertsFromPEM returns the x509.Certificates contained in the given PEM-encoded byte array Returns an error if a certificate could not be parsed, or if the data does not contain any certificates

func CompileRegexps

func CompileRegexps(regexpStrings []string) ([]*regexp.Regexp, error)

Takes a list of strings and compiles them into a list of regular expressions

func DeadlockWatchdog

func DeadlockWatchdog(lock sync.Locker, name string, maxLockPeriod time.Duration)

func DeadlockWatchdogReadLock

func DeadlockWatchdogReadLock(lock *sync.RWMutex, name string, maxLockPeriod time.Duration)

DeadlockWatchdogReadLock creates a watchdog on read/write mutex. If the mutex can not be acquired for read access within 'maxLockPeriod', the program exits via glog.Exitf() or os.Exit() if that fails 'name' is a semantic name that is useful for the user and is printed on exit.

func EncodePrivateKey

func EncodePrivateKey(private *rsa.PrivateKey) []byte

func EncodePublicKey

func EncodePublicKey(public *rsa.PublicKey) ([]byte, error)

func EncodeSSHKey

func EncodeSSHKey(public *rsa.PublicKey) ([]byte, error)

func ExecuteTemplate

func ExecuteTemplate(w io.Writer, templateText string, data interface{}) error

ExecuteTemplate executes templateText with data and output written to w.

func ExecuteTemplateToString

func ExecuteTemplateToString(templateText string, data interface{}) (string, error)

func FileExists

func FileExists(filename string) (bool, error)

func FlushLogs

func FlushLogs()

FlushLogs flushes logs immediately.

func Forever

func Forever(f func(), period time.Duration)

Forever is syntactic sugar on top of Until

func GenerateKey

func GenerateKey(bits int) (*rsa.PrivateKey, *rsa.PublicKey, error)

func GenerateSelfSignedCert

func GenerateSelfSignedCert(host, certPath, keyPath string, alternateIPs []net.IP, alternateDNS []string) error

GenerateSelfSignedCert creates a self-signed certificate and key for the given host. Host may be an IP or a DNS name You may also specify additional subject alt names (either ip or dns names) for the certificate The certificate will be created with file mode 0644. The key will be created with file mode 0600. If the certificate or key files already exist, they will be overwritten. Any parent directories of the certPath or keyPath will be created as needed with file mode 0755.

func GetIntOrPercentValue

func GetIntOrPercentValue(intOrStr *intstr.IntOrString) (int, bool, error)

func GetValueFromPercent

func GetValueFromPercent(percent int, value int) int

func InitFlags

func InitFlags()

InitFlags normalizes and parses the command line flags

func InitLogs

func InitLogs()

InitLogs initializes logs the way we want for kubernetes.

func IntPtr

func IntPtr(i int) *int

IntPtr returns a pointer to an int

func IntPtrDerefOr

func IntPtrDerefOr(ptr *int, def int) int

IntPtrDerefOr derefrence the int ptr and returns it i not nil, else returns def.

func MakePrivateKeySignerFromBytes

func MakePrivateKeySignerFromBytes(buffer []byte) (ssh.Signer, error)

func MakePrivateKeySignerFromFile

func MakePrivateKeySignerFromFile(key string) (ssh.Signer, error)

func NewCRLFWriter

func NewCRLFWriter(w io.Writer) io.Writer

NewCRLFWriter implements a CR/LF line ending writer used for normalizing text for Windows platforms.

func NewLogger

func NewLogger(prefix string) *log.Logger

NewLogger creates a new log.Logger which sends logs to glog.Info.

func NewUUID

func NewUUID() types.UID

func ObjectDiff

func ObjectDiff(a, b interface{}) string

ObjectDiff writes the two objects out as JSON and prints out the identical part of the objects followed by the remaining part of 'a' and finally the remaining part of 'b'. For debugging tests.

func ObjectGoPrintDiff

func ObjectGoPrintDiff(a, b interface{}) string

ObjectGoPrintDiff is like ObjectDiff, but uses go-spew to print the objects, which shows absolutely everything by recursing into every single pointer (go's %#v formatters OTOH stop at a certain point). This is needed when you can't figure out why reflect.DeepEqual is returning false and nothing is showing you differences. This will.

func ObjectGoPrintSideBySide

func ObjectGoPrintSideBySide(a, b interface{}) string

ObjectGoPrintSideBySide prints a and b as textual dumps side by side, enabling easy visual scanning for mismatches.

func ParsePublicKeyFromFile

func ParsePublicKeyFromFile(keyFile string) (*rsa.PublicKey, error)

func ReadDirNoExit

func ReadDirNoExit(dirname string) ([]os.FileInfo, []error, error)

borrowed from ioutil.ReadDir ReadDir reads the directory named by dirname and returns a list of directory entries, minus those with lstat errors

func RunInResourceContainer

func RunInResourceContainer(containerName string) error

Creates resource-only containerName if it does not already exist and moves the current process to it.

containerName must be an absolute container name.

func RunSSHCommand

func RunSSHCommand(cmd, user, host string, signer ssh.Signer) (string, string, int, error)

RunSSHCommand returns the stdout, stderr, and exit code from running cmd on host as specific user, along with any SSH-level error. If user=="", it will default (like SSH) to os.Getenv("USER")

func StringDiff

func StringDiff(a, b string) string

StringDiff diffs a and b and returns a human readable diff.

func Umask

func Umask(mask int) (old int, err error)

func Until

func Until(f func(), period time.Duration, stopCh <-chan struct{})

Until loops until stop channel is closed, running f every period. Catches any panics, and keeps going. f may not be invoked if stop channel is already closed. Pass NeverStop to Until if you don't want it stop.

func UsingSystemdInitSystem

func UsingSystemdInitSystem() bool

Detects if using systemd as the init system Please note that simply reading /proc/1/cmdline can be misleading because some installation of various init programs can automatically make /sbin/init a symlink or even a renamed version of their main program. TODO(dchen1107): realiably detects the init system using on the system: systemd, upstart, initd, etc.

func WarnWordSepNormalizeFunc

func WarnWordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName

WarnWordSepNormalizeFunc changes and warns for flags that contain "_" separators

func WordSepNormalizeFunc

func WordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName

WordSepNormalizeFunc changes all flags that contain "_" separators

Types

type Backoff

type Backoff struct {
	sync.Mutex
	Clock Clock
	// contains filtered or unexported fields
}

func NewBackOff

func NewBackOff(initial, max time.Duration) *Backoff

func (*Backoff) GC

func (p *Backoff) GC()

Garbage collect records that have aged past maxDuration. Backoff users are expected to invoke this periodically.

func (*Backoff) Get

func (p *Backoff) Get(id string) time.Duration

Get the current backoff Duration

func (*Backoff) IsInBackOffSince

func (p *Backoff) IsInBackOffSince(id string, eventTime time.Time) bool

Returns True if the elapsed time since eventTime is smaller than the current backoff window

func (*Backoff) IsInBackOffSinceUpdate

func (p *Backoff) IsInBackOffSinceUpdate(id string, eventTime time.Time) bool

Returns True if time since lastupdate is less than the current backoff window.

func (*Backoff) Next

func (p *Backoff) Next(id string, eventTime time.Time)

move backoff to the next mark, capping at maxDuration

func (*Backoff) Reset

func (p *Backoff) Reset(id string)

Reset forces clearing of all backoff data for a given key.

type BoolFlag

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

BoolFlag is a boolean flag compatible with flags and pflags that keeps track of whether it had a value supplied or not. Getting this flag to act like a normal bool, where true/false are not required needs a little bit of extra code, example:

f := cmd.Flags().VarPF(&BoolFlagVar, "flagname", "", "help about the flag")
f.NoOptDefVal = "true"

func (*BoolFlag) Default

func (f *BoolFlag) Default(value bool)

func (BoolFlag) Provided

func (f BoolFlag) Provided() bool

func (*BoolFlag) Set

func (f *BoolFlag) Set(value string) error

func (BoolFlag) String

func (f BoolFlag) String() string

func (*BoolFlag) Type

func (f *BoolFlag) Type() string

func (BoolFlag) Value

func (f BoolFlag) Value() bool

type Cache

type Cache []*cacheShard

func NewCache

func NewCache(maxSize int) Cache

func (*Cache) Add

func (c *Cache) Add(index uint64, obj interface{}) bool

Returns true if object already existed, false otherwise.

func (*Cache) Get

func (c *Cache) Get(index uint64) (obj interface{}, found bool)

type Clock

type Clock interface {
	Now() time.Time
	Since(time.Time) time.Duration
}

Clock allows for injecting fake or real clocks into code that needs to do arbitrary things based on time.

type ConfigurationMap

type ConfigurationMap map[string]string

func (*ConfigurationMap) Set

func (m *ConfigurationMap) Set(value string) error

func (*ConfigurationMap) String

func (m *ConfigurationMap) String() string

func (*ConfigurationMap) Type

func (*ConfigurationMap) Type() string

type FakeClock

type FakeClock struct {
	Time time.Time
}

FakeClock implements Clock, but returns an arbitrary time.

func (*FakeClock) Now

func (f *FakeClock) Now() time.Time

Now returns f's time.

func (*FakeClock) Since

func (f *FakeClock) Since(ts time.Time) time.Duration

Since returns time since the time in f.

func (*FakeClock) Step

func (f *FakeClock) Step(d time.Duration)

Move clock by Duration

type GlogWriter

type GlogWriter struct{}

GlogWriter serves as a bridge between the standard log package and the glog package.

func (GlogWriter) Write

func (writer GlogWriter) Write(data []byte) (n int, err error)

Write implements the io.Writer interface.

type IntervalClock

type IntervalClock struct {
	Time     time.Time
	Duration time.Duration
}

IntervalClock implements Clock, but each invocation of Now steps the clock forward the specified duration

func (*IntervalClock) Now

func (i *IntervalClock) Now() time.Time

Now returns i's time.

func (*IntervalClock) Since

func (i *IntervalClock) Since(ts time.Time) time.Duration

Since returns time since the time in i.

type LineDelimiter

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

A Line Delimiter is a filter that will

func NewLineDelimiter

func NewLineDelimiter(output io.Writer, delimiter string) *LineDelimiter

NewLineDelimiter allocates a new io.Writer that will split input on lines and bracket each line with the delimiter string. This can be useful in output tests where it is difficult to see and test trailing whitespace.

func (*LineDelimiter) Flush

func (ld *LineDelimiter) Flush() (err error)

Flush all lines up until now. This will assume insert a linebreak at the current point of the stream.

func (*LineDelimiter) Write

func (ld *LineDelimiter) Write(buf []byte) (n int, err error)

Write writes buf to the LineDelimiter ld. The only errors returned are ones encountered while writing to the underlying output stream.

type RateLimiter

type RateLimiter interface {
	// TryAccept returns true if a token is taken immediately. Otherwise,
	// it returns false.
	TryAccept() bool
	// Accept returns once a token becomes available.
	Accept()
	// Stop stops the rate limiter, subsequent calls to CanAccept will return false
	Stop()
	// Saturation returns a percentage number which describes how saturated
	// this rate limiter is.
	// Usually we use token bucket rate limiter. In that case,
	// 1.0 means no tokens are available; 0.0 means we have a full bucket of tokens to use.
	Saturation() float64
}

func NewFakeRateLimiter

func NewFakeRateLimiter() RateLimiter

func NewTokenBucketRateLimiter

func NewTokenBucketRateLimiter(qps float32, burst int) RateLimiter

NewTokenBucketRateLimiter creates a rate limiter which implements a token bucket approach. The rate limiter allows bursts of up to 'burst' to exceed the QPS, while still maintaining a smoothed qps rate of 'qps'. The bucket is initially filled with 'burst' tokens, and refills at a rate of 'qps'. The maximum number of tokens in the bucket is capped at 'burst'.

type RealClock

type RealClock struct{}

RealClock really calls time.Now()

func (RealClock) Now

func (r RealClock) Now() time.Time

Now returns the current time.

func (RealClock) Since

func (r RealClock) Since(ts time.Time) time.Duration

Since returns time since the specified timestamp.

type Runner

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

Runner is an abstraction to make it easy to start and stop groups of things that can be described by a single function which waits on a channel close to exit.

func NewRunner

func NewRunner(f ...func(stop chan struct{})) *Runner

NewRunner makes a runner for the given function(s). The function(s) should loop until the channel is closed.

func (*Runner) Start

func (r *Runner) Start()

Start begins running.

func (*Runner) Stop

func (r *Runner) Stop()

Stop stops running.

type SSHTunnel

type SSHTunnel struct {
	Config  *ssh.ClientConfig
	Host    string
	SSHPort string
	// contains filtered or unexported fields
}

TODO: Unit tests for this code, we can spin up a test SSH server with instructions here: https://godoc.org/golang.org/x/crypto/ssh#ServerConn

func NewSSHTunnel

func NewSSHTunnel(user, keyfile, host string) (*SSHTunnel, error)

func NewSSHTunnelFromBytes

func NewSSHTunnelFromBytes(user string, privateKey []byte, host string) (*SSHTunnel, error)

func (*SSHTunnel) Close

func (s *SSHTunnel) Close() error

func (*SSHTunnel) Dial

func (s *SSHTunnel) Dial(network, address string) (net.Conn, error)

func (*SSHTunnel) Open

func (s *SSHTunnel) Open() error

type SSHTunnelEntry

type SSHTunnelEntry struct {
	Address string
	Tunnel  *SSHTunnel
}

Should be thread safe.

type SSHTunnelList

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

Not thread safe!

func MakeSSHTunnels

func MakeSSHTunnels(user, keyfile string, addresses []string) *SSHTunnelList

func (*SSHTunnelList) Close

func (l *SSHTunnelList) Close()

Close asynchronously closes all tunnels in the list after waiting for 1 minute. Tunnels will still be open upon this function's return, but should no longer be used.

func (*SSHTunnelList) Has

func (l *SSHTunnelList) Has(addr string) bool

func (*SSHTunnelList) Len

func (l *SSHTunnelList) Len() int

func (*SSHTunnelList) Open

func (l *SSHTunnelList) Open() error

Open attempts to open all tunnels in the list, and removes any tunnels that failed to open.

func (*SSHTunnelList) PickRandomTunnel

func (l *SSHTunnelList) PickRandomTunnel() (SSHTunnelEntry, error)

Returns a random tunnel, xor an error if there are none.

type StringFlag

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

StringFlag is a string flag compatible with flags and pflags that keeps track of whether it had a value supplied or not.

func NewStringFlag

func NewStringFlag(defaultVal string) StringFlag

func (*StringFlag) Default

func (f *StringFlag) Default(value string)

func (StringFlag) Provided

func (f StringFlag) Provided() bool

func (*StringFlag) Set

func (f *StringFlag) Set(value string) error

func (StringFlag) String

func (f StringFlag) String() string

func (*StringFlag) Type

func (f *StringFlag) Type() string

func (StringFlag) Value

func (f StringFlag) Value() string

type Trace

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

func NewTrace

func NewTrace(name string) *Trace

func (*Trace) Log

func (t *Trace) Log()

func (*Trace) LogIfLong

func (t *Trace) LogIfLong(threshold time.Duration)

func (*Trace) Step

func (t *Trace) Step(msg string)

func (*Trace) TotalTime

func (t *Trace) TotalTime() time.Duration