dynamic_modulesv3

package
v1.38.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 26, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var File_envoy_extensions_dynamic_modules_v3_dynamic_modules_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type DynamicModuleConfig

type DynamicModuleConfig struct {

	// The name of the dynamic module.
	//
	// The client is expected to have some configuration indicating where to search for the module. In
	// Envoy, the search path can be configured via the environment variable
	// “ENVOY_DYNAMIC_MODULES_SEARCH_PATH“. The actual search path is
	// “${ENVOY_DYNAMIC_MODULES_SEARCH_PATH}/lib${name}.so“. If not set, the current working directory is
	// used as the search path. After Envoy fails to find the module in the search path, it will also
	// try to find the module from a standard system library path (e.g., “/usr/lib“) following the
	// platform's default behavior for “dlopen“.
	//
	// This field is optional if the “module“ field is set. When both “name“ and “module“ are
	// specified, the “module“ field takes precedence.
	//
	// .. note::
	//
	//	There is some remaining work to make the search path configurable via command line options.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// If true, prevents the module from being unloaded with “dlclose“.
	//
	// This is useful for modules that have global state that should not be unloaded. A module is
	// closed when no more references to it exist in the process. For example, no HTTP filters are
	// using the module (e.g. after configuration update).
	//
	// Defaults to “false“.
	DoNotClose bool `protobuf:"varint,3,opt,name=do_not_close,json=doNotClose,proto3" json:"do_not_close,omitempty"`
	// If “true“, the dynamic module is loaded with the “RTLD_GLOBAL“ flag.
	//
	// The dynamic module is loaded with the “RTLD_LOCAL“ flag by default to avoid symbol conflicts
	// when multiple modules are loaded. Set this to “true“ to load the module with the
	// “RTLD_GLOBAL“ flag. This is useful for modules that need to share symbols with other dynamic
	// libraries. For example, a module X may load another shared library Y that depends on some
	// symbols defined in module X. In this case, module X must be loaded with the “RTLD_GLOBAL“
	// flag so that the symbols defined in module X are visible to library Y.
	//
	// .. warning::
	//
	//	Use this option with caution as it may lead to symbol conflicts and undefined behavior if
	//	multiple modules define the same symbols and are loaded globally.
	//
	// Defaults to “false“.
	LoadGlobally bool `protobuf:"varint,4,opt,name=load_globally,json=loadGlobally,proto3" json:"load_globally,omitempty"`
	// The namespace prefix for metrics emitted by this dynamic module.
	//
	// This allows users to customize the prefix used for all metrics created by the dynamic module.
	// The prefix is prepended to all metric names. In prometheus output, metrics will appear with
	// the standard “envoy_“ prefix followed by this namespace. For example, if this is set to
	// “myapp“, a counter “requests“ would appear as “envoy_myapp_requests_total“.
	//
	// Defaults to “dynamicmodulescustom“.
	MetricsNamespace string `protobuf:"bytes,5,opt,name=metrics_namespace,json=metricsNamespace,proto3" json:"metrics_namespace,omitempty"`
	// The dynamic module binary to load. Supports local file paths via “local.filename“
	// and remote HTTP sources via “remote“.
	//
	// When using “remote“, the module is fetched asynchronously during listener initialization.
	// If the fetch fails (network error, SHA256 mismatch, invalid binary, etc.), the filter
	// is **not installed** and requests pass through unfiltered (fail-open).
	//
	// When both “name“ and “module“ are set, “module“ takes precedence.
	Module *v3.AsyncDataSource `protobuf:"bytes,6,opt,name=module,proto3" json:"module,omitempty"`
	// Controls how a cache miss for a remote module is handled.
	//
	// When true (NACK mode), a cache miss causes an immediate NACK of the xDS config update.
	// A background fetch is started and the module will be available on the next config push if
	// the fetch succeeds.
	//
	// When false (default, warming mode), the server blocks during initialization until the fetch
	// completes or exhausts retries. This mode requires an init manager and is not available in
	// ECDS or per-route configurations.
	//
	// When using “module.remote“ with ECDS or per-route configurations, this must be set to
	// “true“.
	//
	// Only applies when “module.remote“ is set.
	//
	// Defaults to “false“.
	NackOnCacheMiss bool `protobuf:"varint,7,opt,name=nack_on_cache_miss,json=nackOnCacheMiss,proto3" json:"nack_on_cache_miss,omitempty"`
	// contains filtered or unexported fields
}

Configuration of a dynamic module. A dynamic module is a shared object file that can be loaded via “dlopen“ by various Envoy extension points.

How a module is loaded is determined by the extension point that uses it. For example, the HTTP filter loads the module when Envoy receives a configuration that references the module. If loading the module fails, the configuration will be rejected.

A module is uniquely identified by its file path and the file's inode, depending on the platform. Notably, if the file path and the content of the file are the same, the shared object will be reused.

A module must be compatible with the ABI specified in :repo:`abi.h <source/extensions/dynamic_modules/abi/abi.h>`. Currently, compatibility is only guaranteed by an exact version match between the Envoy codebase and the dynamic module SDKs. In the future, after the ABI is stabilized, this restriction will be revisited. Until then, Envoy checks the hash of the ABI header files to ensure that the dynamic modules are built against the same version of the ABI. [#next-free-field: 8]

func (*DynamicModuleConfig) Descriptor deprecated

func (*DynamicModuleConfig) Descriptor() ([]byte, []int)

Deprecated: Use DynamicModuleConfig.ProtoReflect.Descriptor instead.

func (*DynamicModuleConfig) GetDoNotClose

func (x *DynamicModuleConfig) GetDoNotClose() bool

func (*DynamicModuleConfig) GetLoadGlobally added in v1.37.0

func (x *DynamicModuleConfig) GetLoadGlobally() bool

func (*DynamicModuleConfig) GetMetricsNamespace added in v1.38.0

func (x *DynamicModuleConfig) GetMetricsNamespace() string

func (*DynamicModuleConfig) GetModule added in v1.38.0

func (x *DynamicModuleConfig) GetModule() *v3.AsyncDataSource

func (*DynamicModuleConfig) GetNackOnCacheMiss added in v1.38.0

func (x *DynamicModuleConfig) GetNackOnCacheMiss() bool

func (*DynamicModuleConfig) GetName

func (x *DynamicModuleConfig) GetName() string

func (*DynamicModuleConfig) ProtoMessage

func (*DynamicModuleConfig) ProtoMessage()

func (*DynamicModuleConfig) ProtoReflect

func (x *DynamicModuleConfig) ProtoReflect() protoreflect.Message

func (*DynamicModuleConfig) Reset

func (x *DynamicModuleConfig) Reset()

func (*DynamicModuleConfig) String

func (x *DynamicModuleConfig) String() string

func (*DynamicModuleConfig) Validate

func (m *DynamicModuleConfig) Validate() error

Validate checks the field values on DynamicModuleConfig with the rules defined in the proto definition for this message. If any rules are violated, the first error encountered is returned, or nil if there are no violations.

func (*DynamicModuleConfig) ValidateAll

func (m *DynamicModuleConfig) ValidateAll() error

ValidateAll checks the field values on DynamicModuleConfig with the rules defined in the proto definition for this message. If any rules are violated, the result is a list of violation errors wrapped in DynamicModuleConfigMultiError, or nil if none found.

type DynamicModuleConfigMultiError

type DynamicModuleConfigMultiError []error

DynamicModuleConfigMultiError is an error wrapping multiple validation errors returned by DynamicModuleConfig.ValidateAll() if the designated constraints aren't met.

func (DynamicModuleConfigMultiError) AllErrors

func (m DynamicModuleConfigMultiError) AllErrors() []error

AllErrors returns a list of validation violation errors.

func (DynamicModuleConfigMultiError) Error

Error returns a concatenation of all the error messages it wraps.

type DynamicModuleConfigValidationError

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

DynamicModuleConfigValidationError is the validation error returned by DynamicModuleConfig.Validate if the designated constraints aren't met.

func (DynamicModuleConfigValidationError) Cause

Cause function returns cause value.

func (DynamicModuleConfigValidationError) Error

Error satisfies the builtin error interface

func (DynamicModuleConfigValidationError) ErrorName

ErrorName returns error name.

func (DynamicModuleConfigValidationError) Field

Field function returns field value.

func (DynamicModuleConfigValidationError) Key

Key function returns key value.

func (DynamicModuleConfigValidationError) Reason

Reason function returns reason value.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL