← 返回首页
Developing extensions | DocsSkip to content
Docs
Search
Select themeDarkLightAutoGet Started for Free
MenuAWSSnowflakeAzure
Select themeDarkLightAutoGet Started for Free
On this page

On this page

Included in Plans
HobbyBaseUltimate

Developing extensions

Copy page

Introduction

Section titled “Introduction”

This section provides a brief overview of how to develop your own extensions.

Extensions API

Section titled “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:

class Extension(BaseExtension):
"""
An extension that is loaded into LocalStack dynamically. The method
execution order of an extension is as follows:
- on_extension_load
- on_platform_start
- update_gateway_routes
- update_request_handlers
- update_response_handlers
- on_platform_ready
- on_platform_shutdown
"""
namespace: str = "localstack.extensions"
"""The namespace of all basic localstack extensions."""
name: str
"""The unique name of the extension set by the implementing class."""
def on_extension_load(self):
"""
Called when LocalStack loads the extension.
"""
pass
def on_platform_start(self):
"""
Called when LocalStack starts the main runtime.
"""
pass
def update_gateway_routes(self, router: Router[RouteHandler]):
"""
Called with the Router attached to the LocalStack gateway. Overwrite this to add or update routes.
:param router: the Router attached in the gateway
"""
pass
def update_request_handlers(self, handlers: CompositeHandler):
"""
Called with the custom request handlers of the LocalStack gateway. Overwrite this to add or update handlers.
:param handlers: custom request handlers of the gateway
"""
pass
def update_response_handlers(self, handlers: CompositeResponseHandler):
"""
Called with the custom response handlers of the LocalStack gateway. Overwrite this to add or update handlers.
:param handlers: custom response handlers of the gateway
"""
pass
def on_platform_ready(self):
"""
Called when LocalStack is ready and the Ready marker has been printed.
"""
pass
def on_platform_shutdown(self):
"""
Called when LocalStack is shutting down. Can be used to close any resources (threads, processes, sockets, etc.).
Added in v1.4
"""
pass

A minimal example would look like this:

import logging
from localstack.extensions.api import Extension
LOG = logging.getLogger(__name__)
class ReadyAnnouncerExtension(Extension):
name = "my_ready_announcer"
def on_platform_ready(self):
LOG.setLevel(logging.INFO)
LOG.info("my plugin is loaded and localstack is ready to roll!")

A note on importing LocalStack modules: since extensions run in the same Python process as the LocalStack runtime, you can also import other LocalStack modules outside the localstack.extensions.api module, and work with them. However, be aware that these modules are not part of our public API, and can change even with patch versions any time. Your extension may break in unexpected ways, and we cannot provide support for internal APIs.

Packaging extensions

Section titled “Packaging extensions”

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:

[metadata]
name = localstack-extension-ready-announcer
description = LocalStack extension that logs when LocalStack is ready to receive requests
author = Your Name
author_email = your@email.com
url = https://link-to-your-project
[options]
zip_safe = False
packages = find:
install_requires =
localstack>=1.0.0
[options.entry_points]
localstack.extensions =
my_ready_announcer = localstack_announcer.extension:ReadyAnnouncerExtension

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.

Using the extensions developer CLI

Section titled “Using the extensions developer CLI”

The extensions CLI has a set of developer commands that allow you to create new extensions, and toggle local dev mode for extensions. Extensions that are toggled for developer mode will be mounted into the localstack container so you don’t need to re-install them every time you change something.

Terminal window
Usage: localstack extensions dev [OPTIONS] COMMAND [ARGS]...
Developer tools for developing Localstack extensions
Options:
--help Show this message and exit.
Commands:
disable Disables an extension on the host for developer mode.
enable Enables an extension on the host for developer mode.
list List LocalStack extensions for which dev mode is enabled.
new Create a new LocalStack extension from the official extension...

Creating your first extension

Section titled “Creating your first extension”

Creating an extension from a template

Section titled “Creating an extension from a template”

First, create a new extension from a template. To use localstack extensions dev new, you will also need to install cookiecutter via pip install cookiecutter.

LocalStack provides two extension templates to help you get started:

  • Basic template (default): A minimal extension template with Python backend code
  • React template: An extension template that includes a React-based UI component

Using the basic template

Section titled “Using the basic template”

To create an extension using the basic template, run:

Terminal window
localstack extensions dev new
project_name [My LocalStack Extension]:
project_short_description [All the boilerplate you need to create a LocalStack extension.]:
project_slug [my-localstack-extension]:
module_name [my_localstack_extension]:
full_name [Jane Doe]:
email [jane@example.com]:
github_username [janedoe]:
version [0.1.0]:

This will create a new Python project with the following layout:

  • my-localstack-extension - Makefile - my_localstack_extension - extension.py
  • init .py - README.md - setup.cfg - setup.py

Then run make install in the newly created project to make a distribution package.

Using the React template

Section titled “Using the React template”

To create an extension with a React-based UI, use the --template react flag:

Terminal window
localstack extensions dev new --template react
project_name [My LocalStack Extension]:
project_short_description [All the boilerplate you need to create a LocalStack extension.]:
project_slug [my-localstack-extension]:
module_name [my_localstack_extension]:
full_name [Jane Doe]:
email [jane@example.com]:
github_username [janedoe]:
version [0.1.0]:

The React template provides a small app with multiple pages to demonstrate how to use multiple pages in the same extension. When you start the LocalStack container with your React-based extension enabled, the extension UI will be automatically available through the LocalStack Web Application.

  • my-localstack-extension - Makefile - README.md - backend - my_localstack_extension - backend.pth - frontend - __init__.py - package.json - public - src - tsconfig.json - pyproject.toml

The extension UI will be available at http://localhost.localstack.cloud:4566/_extension/my-localstack-extension/#/dashboard when LocalStack is running.

Then run make install in the newly created project to make a distribution package.

Start LocalStack with the extension

Section titled “Start LocalStack with the extension”

To start LocalStack with the extension in dev mode, first enable it by running:

Terminal window
localstack extensions dev enable ./my-localstack-extension

Then, start LocalStack with EXTENSION_DEV_MODE=1

Terminal window
EXTENSION_DEV_MODE=1 LOCALSTACK_AUTH_TOKEN=...
localstack start

In the LocalStack logs you should then see something like:

Terminal window
==================================================
👷 LocalStack extension developer mode enabled 🏗
- mounting extension /opt/code/extensions/my-localstack-extension
Resuming normal execution, ...
==================================================

Now, when you make changes to your extensions, you just need to restart LocalStack and the changes will be picked up by LocalStack automatically.

Section titled “Advertise your extension”

Once your extension is ready to be used, release it on a public GitHub repository. To make your extension easily installable for everyone generate an extension badge for your extension on this page. The resulting badge should look like this:

You can create a one-click installer for your extension using our Extension Installer.

Was this page helpful?
YesNo
Edit page