LocalStack Extensions

LocalStack Extensions allows developers to extend and customize LocalStack.

With LocalStack 1.0 we have introduced LocalStack Extensions that allow developers to extend and customize LocalStack. Both the feature and the API are currently experimental and may be subject to change.

Using Extensions

Extensions are a LocalStack Pro feature. To use and install extensions, use the CLI to first log in to your account

  1. $ localstack login
  2. Please provide your login credentials below
  3. Username: ...
  1. $ localstack extensions --help
  3. Usage: localstack extensions [OPTIONS] COMMAND [ARGS]...
  5.   Manage LocalStack extensions (beta)
  7. Options:
  8.   --help  Show this message and exit.
  10. Commands:
  11.   init       Initialize the LocalStack extensions environment
  12.   install    Install a LocalStack extension
  13.   uninstall  Remove a LocalStack extension

To install an extension, specify the name of the pip dependency that contains the extension. For example, for the official Stripe extension, you can either use the package distributed on pypi:

  1. $ localstack extensions install localstack-extensions-stripe

or you can install it directly from this git repository

  1. $ localstack extensions install "git+https://github.com/localstack/localstack-extensions/#egg=localstack-extensions-stripe&subdirectory=stripe"

Developing Extensions

The extensions API

LocalStack exposes a Python API for building extensions that can be found in the core codebase in localstack.extensions.api.

The basic interface to implement is as follows:

  1. class Extension(BaseExtension):
  2.     """
  3.     An extension that is loaded into LocalStack dynamically. The method
  4.     execution order of an extension is as follows:
  6.     - on_extension_load
  7.     - on_platform_start
  8.     - update_gateway_routes
  9.     - update_request_handlers
  10.     - update_response_handlers
  11.     - on_platform_ready
  12.     """
  14.     namespace: str = "localstack.extensions"
  15.     """The namespace of all basic localstack extensions."""
  17.     name: str
  18.     """The unique name of the extension set by the implementing class."""
  20.     def on_extension_load(self):
  21.         """
  22.         Called when LocalStack loads the extension.
  23.         """
  24.         pass
  26.     def on_platform_start(self):
  27.         """
  28.         Called when LocalStack starts the main runtime.
  29.         """
  30.         pass
  32.     def update_gateway_routes(self, router: Router[RouteHandler]):
  33.         """
  34.         Called with the Router attached to the LocalStack gateway. Overwrite this to add or update routes.
  35.         :param router: the Router attached in the gateway
  36.         """
  37.         pass
  39.     def update_request_handlers(self, handlers: CompositeHandler):
  40.         """
  41.         Called with the custom request handlers of the LocalStack gateway. Overwrite this to add or update handlers.
  42.         :param handlers: custom request handlers of the gateway
  43.         """
  44.         pass
  46.     def update_response_handlers(self, handlers: CompositeResponseHandler):
  47.         """
  48.         Called with the custom response handlers of the LocalStack gateway. Overwrite this to add or update handlers.
  49.         :param handlers: custom response handlers of the gateway
  50.         """
  51.         pass
  53.     def on_platform_ready(self):
  54.         """
  55.         Called when LocalStack is ready and the Ready marker has been printed.
  56.         """
  57.         pass

A minimal example would look like this:

  1. import logging
  2. from localstack.extensions.api import Extension
  4. LOG = logging.getLogger(__name__)
  6. class ReadyAnnoucerExtension(Extension):
  7.     name = "my_ready_annoucer"
  9.     def on_platform_ready(self):
  10.         LOG.info("my plugin is laded and localstack is ready to roll!")

Package your Extension

Your extensions needs to be packaged as a Python distribution with a setup.cfg or setup.py config. LocalStack uses the Plux code loading framework to load your code from a Python entry point.

You can either use Plux to discover the entrypoints from your code when building and publishing your distribution, or manually define them as in the example below.

A minimal setup.cfg for the extension above could look like this:

  1. [metadata]
  2. name = localstack-extension-ready-announcer
  3. description = LocalStack extension that logs when LocalStack is ready to receive requests
  4. author = Your Name
  5. author_email = your@email.com
  6. url = https://link-to-your-project
  8. [options]
  9. zip_safe = False
  10. packages = find:
  11. install_requires =
  12.     localstack>=1.0.0
  14. [options.entry_points]
  15. localstack.extensions =
  16.     my_ready_annoucer = localstack_annoucer.extension:ReadyAnnoucerExtension

The entry point group is the Plux namespace locastack.extensions, and the entry point name is the plugin name my_ready_announcer. The object reference points to the plugin class.

Last modified July 19, 2022: add LocalStack Extensions to developer guide (#209) (1e8855a2)