istio: istio.io/istio/pkg/envoy Index | Files

package envoy

import "istio.io/istio/pkg/envoy"

Index

Package Files

admin.go agent.go instance.go options.go proxy.go watcher.go

Constants

const (
    // InvalidBaseID used to indicate that the Envoy BaseID has not been set. Attempting
    // to Close this BaseID will have no effect.
    InvalidBaseID = BaseID(math.MaxUint32)
)

func GetConfigDump Uses

func GetConfigDump(adminPort uint32) (*envoyAdmin.ConfigDump, error)

GetConfigDump polls Envoy admin port for the config dump and returns the response.

func GetServerInfo Uses

func GetServerInfo(adminPort uint32) (*envoyAdmin.ServerInfo, error)

GetServerInfo returns a structure representing a call to /server_info

func Shutdown Uses

func Shutdown(adminPort uint32) error

Shutdown initiates a graceful shutdown of Envoy.

type Agent Uses

type Agent interface {
    // Run starts the agent control loop and awaits for a signal on the input
    // channel to exit the loop.
    Run(ctx context.Context) error

    // Restart triggers a hot restart of envoy, applying the given config to the new process
    Restart(config interface{})
}

Agent manages the restarts and the life cycle of a proxy binary. Agent keeps track of all running proxy epochs and their configurations. Hot restarts are performed by launching a new proxy process with a strictly incremented restart epoch. It is up to the proxy to ensure that older epochs gracefully shutdown and carry over all the necessary state to the latest epoch. The agent does not terminate older epochs. The initial epoch is 0.

The restart protocol matches Envoy semantics for restart epochs: to successfully launch a new Envoy process that will replace the running Envoy processes, the restart epoch of the new process must be exactly 1 greater than the highest restart epoch of the currently running Envoy processes. See https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/hot_restart.html for more information about the Envoy hot restart protocol.

Agent requires two functions "run" and "cleanup". Run function is a call to start the proxy and must block until the proxy exits. Cleanup function is executed immediately after the proxy exits and must be non-blocking since it is executed synchronously in the main agent control loop. Both functions take the proxy epoch as an argument. A typical scenario would involve epoch 0 followed by a failed epoch 1 start. The agent then attempts to start epoch 1 again.

Whenever the run function returns an error, the agent assumes that the proxy failed to start and attempts to restart the proxy several times with an exponential back-off. The subsequent restart attempts may reuse the epoch from the failed attempt. Retry budgets are allocated whenever the desired configuration changes.

Agent executes a single control loop that receives notifications about scheduled configuration updates, exits from older proxy epochs, and retry attempt timers. The call to schedule a configuration update will block until the control loop is ready to accept and process the configuration update.

func NewAgent Uses

func NewAgent(proxy Proxy, terminationDrainDuration time.Duration) Agent

NewAgent creates a new proxy agent for the proxy start-up and clean-up functions.

type BaseID Uses

type BaseID uint32

BaseID is an Option that sets the --base-id flag. This is typically only needed when running multiple Envoys on the same machine (common in testing environments).

Envoy will allocate shared memory if provided with a BaseID. This shared memory is used during hot restarts. It is up to the caller to free this memory by calling Close() on the BaseID when appropriate.

func GenerateBaseID Uses

func GenerateBaseID() BaseID

GenerateBaseID is a method copied from Envoy server tests.

Computes a numeric ID to incorporate into the names of shared-memory segments and domain sockets, to help keep them distinct from other tests that might be running concurrently.

func (BaseID) Close Uses

func (bid BaseID) Close() error

Close removes the shared memory allocated by Envoy for this BaseID.

func (BaseID) FlagName Uses

func (bid BaseID) FlagName() FlagName

func (BaseID) FlagValue Uses

func (bid BaseID) FlagValue() string

func (BaseID) GetInternalEnvoyValue Uses

func (bid BaseID) GetInternalEnvoyValue() uint64

GetInternalEnvoyValue returns the value used internally by Envoy. Envoy internally multiplies the base ID from the command line by 10 so that they have spread of domain sockets.

type ComponentLogLevel Uses

type ComponentLogLevel struct {
    Name  string
    Level LogLevel
}

ComponentLogLevel defines the log level for a single component.

func (ComponentLogLevel) String Uses

func (l ComponentLogLevel) String() string

type ComponentLogLevels Uses

type ComponentLogLevels []ComponentLogLevel

ComponentLogLevels is an Option for multiple component log levels.

func ParseComponentLogLevels Uses

func ParseComponentLogLevels(value string) ComponentLogLevels

ParseComponentLogLevels parses the given envoy --component-log-level value string.

func (ComponentLogLevels) FlagName Uses

func (l ComponentLogLevels) FlagName() FlagName

func (ComponentLogLevels) FlagValue Uses

func (l ComponentLogLevels) FlagValue() string

type Config Uses

type Config struct {
    // Options provides the command-line options to be passed to Envoy.
    Options Options

    // Name of the envoy instance, used for logging only. If not provided, defaults to "envoy".
    Name string

    // BinaryPath the path to the Envoy binary.
    BinaryPath string

    // WorkingDir to be used when running Envoy. If not set, the current working directory is used.
    WorkingDir string

    // AdminPort specifies the administration port for the Envoy server. If not set, will
    // be determined by parsing the Envoy bootstrap configuration file.
    AdminPort uint32

    // SkipBaseIDClose skips calling Close on the BaseID, if one was specified.
    SkipBaseIDClose bool
}

Config for an Envoy Instance.

type DrainConfig Uses

type DrainConfig struct{}

DrainConfig is used to signal to the Proxy that it should start draining connections

type Epoch Uses

type Epoch uint32

Epoch sets the --restart-epoch flag, which specifies the epoch used for hot restart.

func (Epoch) FlagName Uses

func (e Epoch) FlagName() FlagName

func (Epoch) FlagValue Uses

func (e Epoch) FlagValue() string

type FactoryFunc Uses

type FactoryFunc func(cfg Config) (Instance, error)

FactoryFunc is a function that manufactures Envoy Instances.

type FlagName Uses

type FlagName string

FlagName is the raw flag name passed to envoy.

func (FlagName) String Uses

func (n FlagName) String() string

type IPVersion Uses

type IPVersion string

IPVersion is an enumeration for IP versions for the --local-address-ip-version flag.

const (
    IPV4 IPVersion = "v4"
    IPV6 IPVersion = "v6"
)

type Instance Uses

type Instance interface {
    // Config returns the configuration for this Instance.
    Config() Config

    // BaseID used to start Envoy. If not set, returns InvalidBaseID.
    BaseID() BaseID

    // Epoch used to start Envoy. If it was not set, defaults to 0.
    Epoch() Epoch

    // Start the Envoy Instance. The process will be killed if the given context is canceled.
    //
    // If this Instance was created via NewInstanceForHotRestart, this method will block until the parent
    // Instance terminates or goes "live". This is due to the fact that hot restart will fail if the previous
    // envoy process is still initializing.
    Start(ctx context.Context) Instance

    // NewInstanceForHotRestart creates a new Envoy Instance that is configured for a hot restart of this
    // Instance (i.e. epoch is incremented). During a hot restart of Envoy, the old process is drained and
    // traffic is shifted over to the new process.
    //
    // The caller must Start the returned instance to initiate the hot restart.
    //
    // If a new Instance is successfully created, it assumes ownership of the Envoy shared memory segment
    // used for hot restart. This means that when this Instance exits, it will no longer destroy
    // the shared memory segment, regardless of the value of SkipBaseIDClose.
    //
    // If this Instance hasn't been started, calling this method does nothing and simply returns
    // this Instance since there is nothing to restart.
    //
    // This method may only be called once on a given Instance. Subsequent calls will return an error.
    NewInstanceForHotRestart() (Instance, error)

    // WaitUntilLive polls the Envoy ServerInfo endpoint and waits for it to transition to "live". If the
    // wait times out, returns the last known error or context.DeadlineExceeded if no error occurred within the
    // specified duration.
    WaitLive() Waitable

    // AdminPort gets the administration port for Envoy.
    AdminPort() uint32

    // GetServerInfo returns a structure representing a call to /server_info
    GetServerInfo() (*envoyAdmin.ServerInfo, error)

    // GetConfigDump polls Envoy admin port for the config dump and returns the response.
    GetConfigDump() (*envoyAdmin.ConfigDump, error)

    // Wait for the Instance to terminate.
    Wait() Waitable

    // Kill the process, if running.
    Kill() error

    // KillAndWait is a helper that calls Kill and then waits for the process to terminate.
    KillAndWait() Waitable

    // Shutdown initiates the graceful termination of Envoy. Returns immediately and does not
    // wait for the process to exit.
    Shutdown() error

    // ShutdownAndWait is a helper that calls Shutdown and waits for the process to terminate.
    ShutdownAndWait() Waitable
}

Instance of an Envoy process.

func New Uses

func New(cfg Config) (Instance, error)

New creates a new Envoy Instance with the given options.

type LogLevel Uses

type LogLevel string

LogLevel is an Option that sets the Envoy log level.

const (
    LogLevelTrace    LogLevel = "trace"
    LogLevelDebug    LogLevel = "debug"
    LogLevelInfo     LogLevel = "info"
    LogLevelWarning  LogLevel = "warning"
    LogLevelCritical LogLevel = "critical"
    LogLevelOff      LogLevel = "off"
)

func (LogLevel) FlagName Uses

func (l LogLevel) FlagName() FlagName

func (LogLevel) FlagValue Uses

func (l LogLevel) FlagValue() string

type Option Uses

type Option interface {
    // FlagName returns the flag name used on the command line.
    FlagName() FlagName

    // FlagValue returns the flag value used on the command line. Can be empty for boolean flags.
    FlagValue() string
    // contains filtered or unexported methods
}

Option for an Envoy Instance.

func Concurrency Uses

func Concurrency(concurrency uint16) Option

Concurrency sets the --concurrency flag, which sets the number of worker threads to run.

func ConfigPath Uses

func ConfigPath(path string) Option

ConfigPath sets the --config-path flag, which provides Envoy with the to the v2 bootstrap configuration file. If not set, ConfigYaml is required.

func ConfigYaml Uses

func ConfigYaml(yaml string) Option

ConfigYaml sets the --config-yaml flag, which provides Envoy with the a YAML string for a v2 bootstrap configuration. If ConfigPath is also set, the values in this YAML string will override and merge with the bootstrap loaded from ConfigPath.

func DisableHotRestart Uses

func DisableHotRestart(disable bool) Option

DisableHotRestart sets the --disable-hot-restart flag.

func DrainDuration Uses

func DrainDuration(duration time.Duration) Option

DrainDuration sets the --drain-time-s flag, which defines the amount of time that Envoy will drain connections during a hot restart.

func LocalAddressIPVersion Uses

func LocalAddressIPVersion(v IPVersion) Option

LocalAddressIPVersion sets the --local-address-ip-version flag, which sets the IP address version used for the local IP address. The default is V4.

func LogFormat Uses

func LogFormat(format string) Option

LogFormat sets the --log-format flag, which specifies the format string to use for log messages.

func LogPath Uses

func LogPath(path string) Option

LogPath sets the --log-path flag, which specifies the output file for logs. If not set logs will be written to stderr.

func ParentShutdownDuration Uses

func ParentShutdownDuration(duration time.Duration) Option

ParentShutdownDuration sets the --parent-shutdown-time-s flag, which defines the amount of time that Envoy will wait before shutting down the parent process during a hot restart

func ServiceCluster Uses

func ServiceCluster(c string) Option

ServiceCluster sets the --service-cluster flag, which defines the local service cluster name where Envoy is running

func ServiceNode Uses

func ServiceNode(n string) Option

ServiceNode sets the --service-node flag, which defines the local service node name where Envoy is running

type Options Uses

type Options []Option

func NewOptions Uses

func NewOptions(args ...string) (Options, error)

NewOptions creates new Options from the given raw Envoy arguments. Returns an error if a problem was encountered while parsing the arguments.

func (Options) ToArgs Uses

func (options Options) ToArgs() []string

ToArgs creates the command line arguments for the list of options.

func (Options) Validate Uses

func (options Options) Validate() error

Validate the Options.

type Proxy Uses

type Proxy interface {
    // IsLive returns true if the server is up and running (i.e. past initialization).
    IsLive() bool

    // Run command for a config, epoch, and abort channel
    Run(interface{}, int, <-chan error) error

    // Cleanup command for an epoch
    Cleanup(int)
}

Proxy defines command interface for a proxy

func NewProxy Uses

func NewProxy(cfg ProxyConfig) Proxy

NewProxy creates an instance of the proxy control commands

type ProxyConfig Uses

type ProxyConfig struct {
    Config              meshconfig.ProxyConfig
    Node                string
    LogLevel            string
    ComponentLogLevel   string
    PilotSubjectAltName []string
    MixerSubjectAltName []string
    NodeIPs             []string
    DNSRefreshRate      string
    PodName             string
    PodNamespace        string
    PodIP               net.IP
    SDSUDSPath          string
    SDSTokenPath        string
    ControlPlaneAuth    bool
    DisableReportCalls  bool
}

type Waitable Uses

type Waitable interface {
    // WithTimeout specifies an upper bound on the wait time.
    WithTimeout(timeout time.Duration) Waitable

    // Do performs the wait. By default, waits indefinitely. To specify an upper bound on
    // the wait time, use WithTimeout. If the wait times out, returns the last known error
    // for retried operations or context.DeadlineExceeded if no previous error was encountered.
    Do() error
}

Waitable specifies a waitable operation.

type Watcher Uses

type Watcher interface {
    // Run the watcher loop (blocking call)
    Run(context.Context)
}

Watcher triggers reloads on changes to the proxy config

func NewWatcher Uses

func NewWatcher(certs []string, updates func(interface{})) Watcher

NewWatcher creates a new watcher instance from a proxy agent and a set of monitored certificate file paths

Package envoy imports 33 packages (graph) and is imported by 3 packages. Updated 2019-10-21. Refresh now. Tools for package owners.