.. _config_bootstrap_extensions_dynamic_modules:

Dynamic Modules
===============

* :ref:`v3 API reference <envoy_v3_api_msg_extensions.bootstrap.dynamic_modules.v3.DynamicModuleBootstrapExtension>`

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 :ref:`DynamicModuleBootstrapExtension <envoy_v3_api_msg_extensions.bootstrap.dynamic_modules.v3.DynamicModuleBootstrapExtension>` message.

Example Configuration
---------------------

.. code-block:: yaml

  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 :ref:`architecture overview <arch_overview_dynamic_modules>`.