Dynamic Modules

The Dynamic Modules bootstrap extension allows you to write bootstrap extensions in a dynamic module. This can be used to implement:

  • Server initialization logic when Envoy starts.

  • Per-worker-thread initialization logic when worker threads start.

  • Singleton patterns for configuration loading from external services.

  • Global state management across filters.

  • Background tasks that run on the main thread.

The extension is configured using the DynamicModuleBootstrapExtension message.

Example Configuration

bootstrap_extensions:
- name: envoy.bootstrap.dynamic_modules
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.bootstrap.dynamic_modules.v3.DynamicModuleBootstrapExtension
    dynamic_module_config:
      name: my_module
    extension_name: my_bootstrap_extension
    extension_config:
      "@type": type.googleapis.com/google.protobuf.StringValue
      value: "my_config"

Lifecycle Hooks

Bootstrap extensions have two lifecycle hooks:

onServerInitialized

Called when the server is fully initialized, on the main thread. This is where you can:

  • Load configuration from external services.

  • Initialize global state.

  • Register singleton resources.

  • Start background tasks.

onWorkerThreadInitialized

Called once per worker thread when it starts. This is where you can:

  • Initialize per-worker-thread state.

  • Set up thread-local storage.

  • Prepare resources for use by filters on this thread.

Use Cases

Dynamic Configuration Loading

Use the onServerInitialized hook to fetch configuration from an external service (e.g., a config server) at startup. Store the configuration in shared state that filters can access.

Singleton Pattern

Implement a singleton that is initialized once and shared across all filters. For example, a connection pool to an external service, or a cache that is shared across all requests.

Global Metrics

Initialize custom metrics in the onServerInitialized hook that can be updated by filters throughout the request lifecycle.

For more details on dynamic modules, see the architecture overview.