Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 125 Commits
.github/workflows		.github/workflows
aws-proxy		aws-proxy
bin		bin
diagnosis-viewer		diagnosis-viewer
hello-world		hello-world
httpbin		httpbin
mailhog		mailhog
miniflare		miniflare
openai		openai
prometheus		prometheus
stripe		stripe
template		template
templates		templates
terraform-init		terraform-init
.gitignore		.gitignore
CODEOWNERS		CODEOWNERS
LICENSE		LICENSE
README.md		README.md

Repository files navigation

LocalStack Extensions (Preview)

With LocalStack 1.0 we have introduced LocalStack Extensions that allowdevelopers to extend and customize LocalStack. Both the feature and the APIare currently in preview 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

$localstack auth loginPlease provide your login credentials belowUsername: ...

$localstack extensions --helpUsage: localstack extensions [OPTIONS] COMMAND [ARGS]...  (Preview) Manage LocalStack extensions.  LocalStack Extensions allow developers to extend and customize LocalStack.  The feature and the API are currently in a preview stage and may be subject to change.  Visit https://docs.localstack.cloud/references/localstack-extensions/  for more information on LocalStack Extensions.Options:  -v, --verbose  Print more output  -h, --help     Show this message and exit.Commands:  dev        Developer tools for developing LocalStack extensions.  init       Initialize the LocalStack extensions environment.  install    Install a LocalStack extension.  list       List installed extension.  uninstall  Remove a LocalStack extension.

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

$localstack extensions install localstack-extension-httpbin

or you can install the latest version directly from this Git repository

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

Official LocalStack Extensions

Here is the current list of extensions developed by the LocalStack team and their support status.You can install the respective extension by callinglocalstack install <Install name>.

Extension	Install name	Version	Support status
AWS Proxy	localstack-extension-aws-proxy	0.2.1	Experimental
Diagnosis Viewer	localstack-extension-diagnosis-viewer	0.1.0	Stable
Hello World	localstack-extension-hello-world	0.1.0	Stable
httpbin	localstack-extension-httpbin	0.1.0	Stable
MailHog	localstack-extension-mailhog	0.1.0	Stable
Miniflare	localstack-extension-miniflare	0.1.0	Experimental
Stripe	localstack-extension-stripe	0.2.0	Stable
Terraform Init	localstack-extension-terraform-init	0.2.0	Experimental

Developing Extensions

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

The extensions API

LocalStack exposes a Python API for building extensions that can be found inthe core codebase inlocalstack.extensions.api.

The basic interface to implement is as follows:

classExtension(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."""defon_extension_load(self):""" Called when LocalStack loads the extension. """passdefon_platform_start(self):""" Called when LocalStack starts the main runtime. """passdefon_platform_shutdown(self):""" Called when LocalStack is shutting down. Can be used to close any resources (threads, processes, sockets, etc.). """passdefupdate_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 """passdefupdate_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 """passdefupdate_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 """passdefon_platform_ready(self):""" Called when LocalStack is ready and the Ready marker has been printed. """pass

A minimal example would look like this:

importloggingfromlocalstack.extensions.apiimportExtensionLOG=logging.getLogger(__name__)classReadyAnnouncerExtension(Extension):name="my_ready_announcer"defon_platform_ready(self):LOG.info("my plugin is loaded and localstack is ready to roll!")

Package your Extension

Your extensions needs to be packaged as a Python distribution with asetup.cfg orsetup.py config. LocalStack uses thePlux code loading framework to load yourcode from a Pythonentry point.You can either use Plux to discover the entrypoints from your code whenbuilding and publishing your distribution, or manually define them as in theexample below.

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

[metadata]name = localstack-extension-ready-announcerdescription = LocalStack extension that logs when LocalStack is ready to receive requestsauthor = Your Nameauthor_email = your@email.comurl = https://link-to-your-project[options]zip_safe = Falsepackages = 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 namespacelocastack.extensions, and theentry point name is the plugin namemy_ready_announcer. The objectreference points to the plugin class.

Using the extensions 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.

Usage: localstack extensions dev [OPTIONS] COMMAND [ARGS]...  Developer tools for developing Localstack extensionsOptions:  --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 a new extensions

First, create a new extensions from a template:

 % localstack extensions dev newproject_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 runmake install in the newly created project to make a distribution package.

Start LocalStack with the extension

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

localstack extensions dev enable ./my-localstack-extension

Then, start LocalStack withEXTENSION_DEV_MODE=1

EXTENSION_DEV_MODE=1 LOCALSTACK_API_KEY=... localstack start

In the LocalStack logs you should then see something like:

==================================================👷 LocalStack extension developer mode enabled 🏗- mounting extension /opt/code/extensions/my-localstack-extensionResuming 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.