diff --git a/public/_redirects b/public/_redirects index 1faafa5fa..d1c6bb8af 100644 --- a/public/_redirects +++ b/public/_redirects @@ -218,7 +218,7 @@ /user-guide/integrations/terraform/ /aws/connecting/infrastructure-as-code/terraform/ 301 /user-guide/aws/es/ /aws/services/es/ 301 /references/coverage/coverage_dms/ /aws/services/dms/ 301 -/user-guide/extensions/developing-extensions/ /aws/customization/integrations/extensions/developing-extensions/ 301 +/user-guide/extensions/developing-extensions/ /aws/customization/integrations/extensions/ 301 /user-guide/security-testing/explainable-iam/ /aws/developer-tools/security-testing/explainable-iam/ 301 /user-guide/aws/ram/ /aws/services/ram/ 301 /references/coverage/coverage_ssm/ /aws/services/ssm/ 301 @@ -618,7 +618,7 @@ /user-guide/integrations/terraform /aws/connecting/infrastructure-as-code/terraform/ 301 /user-guide/aws/es /aws/services/es/ 301 /references/coverage/coverage_dms /aws/services/dms/ 301 -/user-guide/extensions/developing-extensions /aws/customization/integrations/extensions/developing-extensions/ 301 +/user-guide/extensions/developing-extensions /aws/customization/integrations/extensions/ 301 /user-guide/security-testing/explainable-iam /aws/developer-tools/security-testing/explainable-iam/ 301 /user-guide/aws/ram /aws/services/ram/ 301 /references/coverage/coverage_ssm /aws/services/ssm/ 301 @@ -910,8 +910,10 @@ /aws/tooling/extensions/ /aws/customization/integrations/extensions/ 301 /aws/tooling/extensions/mailhog /aws/customization/integrations/extensions/mailhog/ 301 /aws/tooling/extensions/mailhog/ /aws/customization/integrations/extensions/mailhog/ 301 -/aws/tooling/extensions/developing-extensions /aws/customization/integrations/extensions/developing-extensions/ 301 -/aws/tooling/extensions/developing-extensions/ /aws/customization/integrations/extensions/developing-extensions/ 301 +/aws/tooling/extensions/developing-extensions /aws/customization/integrations/extensions/ 301 +/aws/tooling/extensions/developing-extensions/ /aws/customization/integrations/extensions/ 301 +/aws/customization/integrations/extensions/developing-extensions /aws/customization/integrations/extensions/ 301 +/aws/customization/integrations/extensions/developing-extensions/ /aws/customization/integrations/extensions/ 301 /aws/tooling/extensions/managing-extensions /aws/customization/integrations/extensions/managing-extensions/ 301 /aws/tooling/extensions/managing-extensions/ /aws/customization/integrations/extensions/managing-extensions/ 301 /aws/capabilities/web-app/app-inspector /aws/developer-tools/app-inspector/ 301 diff --git a/public/images/aws/extension-installer.png b/public/images/aws/extension-installer.png deleted file mode 100644 index d5e1b5e81..000000000 Binary files a/public/images/aws/extension-installer.png and /dev/null differ diff --git a/scripts/generate_extensions_docs.py b/scripts/generate_extensions_docs.py index 392ef721c..e2ad2ba9a 100644 --- a/scripts/generate_extensions_docs.py +++ b/scripts/generate_extensions_docs.py @@ -161,7 +161,7 @@ def generate_documentation(extensions: list[Extension]) -> str: "localstack extensions install ", "```", "", - "See [Managing extensions](/aws/tooling/extensions/managing-extensions) for more details " + "See [Managing extensions](/aws/customization/integrations/extensions/managing-extensions/) for more details " "on installing, listing, and removing extensions.", "", ":::note", diff --git a/scripts/redirects/_redirects b/scripts/redirects/_redirects index 213b5ab6c..1bdb586b1 100644 --- a/scripts/redirects/_redirects +++ b/scripts/redirects/_redirects @@ -220,7 +220,7 @@ /user-guide/integrations/terraform/ /aws/integrations/infrastructure-as-code/terraform 301 /user-guide/aws/es/ /aws/services/es 301 /references/coverage/coverage_dms/ /aws/services/dms 301 -/user-guide/extensions/developing-extensions/ /aws/tooling/extensions/developing-extensions 301 +/user-guide/extensions/developing-extensions/ /aws/customization/integrations/extensions/ 301 /user-guide/security-testing/explainable-iam/ /aws/capabilities/security-testing/explainable-iam 301 /user-guide/aws/ram/ /aws/services/ram 301 /references/coverage/coverage_ssm/ /aws/services/ssm 301 diff --git a/scripts/redirects/redirects_config.json b/scripts/redirects/redirects_config.json index 3c9ed2db1..e50c96e2a 100644 --- a/scripts/redirects/redirects_config.json +++ b/scripts/redirects/redirects_config.json @@ -1106,7 +1106,7 @@ }, { "old_link": "/user-guide/extensions/developing-extensions/", - "new_link": "/aws/tooling/extensions/developing-extensions", + "new_link": "/aws/customization/integrations/extensions/", "status_code": 301 }, { diff --git a/src/content/docs/aws/customization/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index bf641a972..0baa1b704 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -423,7 +423,6 @@ To learn more about these configuration options, see [Cloud Pods](/aws/developer | Variable | Example Values | Description | | - | - | - | | `EXTENSION_AUTO_INSTALL` | | Install a list of extensions automatically at startup. Comma-separated list of extensions directives which will be installed automatically at startup (see [managing extensions](/aws/customization/integrations/extensions/managing-extensions#automating-extensions-installation))| -| `EXTENSION_DEV_MODE` | `0` (default) \| `1` | Enables development mode for extensions. Refer to the [Extensions Development Guide](/aws/customization/integrations/extensions/developing-extensions) for more information. | ## Miscellaneous diff --git a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx deleted file mode 100644 index 8a9aa5c6f..000000000 --- a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: Developing extensions -description: How to develop your own extensions. -template: doc -sidebar: - order: 3 -tags: ['Hobby'] ---- - -import { FileTree } from '@astrojs/starlight/components'; - -## Introduction - -This section provides a brief overview of how to develop your own extensions. - -## Extensions API - -LocalStack exposes a Python API for building extensions that can be found in the core codebase in [`localstack.extensions.api`](https://github.com/localstack/localstack/tree/main/localstack-core/localstack/extensions/api). - -The basic interface to implement is as follows: - -```python showLineNumbers -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: - -```python showLineNumbers -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!") -``` - -:::note -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 - -Your extensions needs to be packaged as a Python distribution with a -`setup.cfg` or `setup.py` config. -LocalStack uses the -[Plux](https://github.com/localstack/plux) code loading framework to load your -code from a Python [entry point](https://packaging.python.org/en/latest/specifications/entry-points/). -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: - -```toml showLineNumbers -[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 - -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. - -```console -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 - -### 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](https://github.com/cookiecutter/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 - -To create an extension using the basic template, run: - -```bash showLineNumbers -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 - -To create an extension with a React-based UI, use the `--template react` flag: - -```bash showLineNumbers -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 - -To start LocalStack with the extension in dev mode, first enable it by running: - -```bash -localstack extensions dev enable ./my-localstack-extension -``` - -Then, start LocalStack with `EXTENSION_DEV_MODE=1` - -```bash -EXTENSION_DEV_MODE=1 LOCALSTACK_AUTH_TOKEN=... -localstack start -``` - -In the LocalStack logs you should then see something like: - -```bash -================================================== -👷 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. - -## 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: - -![Extension badge](https://localstack.cloud/gh/extension-badge.svg) - -You can create a one-click installer for your extension using our [Extension Installer](https://app.localstack.cloud/extensions/remote). - -![Extension Installer](/images/aws/extension-installer.png) diff --git a/src/content/docs/aws/customization/integrations/extensions/index.md b/src/content/docs/aws/customization/integrations/extensions/index.md index 102905a2d..0fd4193ad 100644 --- a/src/content/docs/aws/customization/integrations/extensions/index.md +++ b/src/content/docs/aws/customization/integrations/extensions/index.md @@ -8,27 +8,12 @@ sidebar: tags: ['Hobby'] --- -LocalStack Extensions let you customize and extend LocalStack's core functionality by running additional logic and services inside the same container. This feature is available across all LocalStack plans, and is ideal for teams that want deeper control over how LocalStack behaves during development or testing. +LocalStack Extensions add services and integrations to your LocalStack container. This feature is available across all LocalStack plans. -You can use LocalStack Extensions to: - -- Start custom services alongside LocalStack in the same container (see our [Cloudflare Workers Extension](https://localstack.cloud/blog/2023-06-26-develop-your-cloudflare-workers-aws-apps-locally-with-localstack-miniflare/)) - -- Intercept AWS requests with additional information before they reach your Lambda functions - -- Log API calls to custom external backends or monitoring systems - -The Extensions API makes it easy to integrate your own logic or extend existing services, all within LocalStack’s runtime. - -Officially supported extensions are available in our [Official Extensions Library](https://app.localstack.cloud/extensions/library). +You can find supported extensions in the [Official Extensions Library](https://app.localstack.cloud/extensions/library). :::tip Want to try out a common LocalStack extension? Our [MailHog tutorial](/aws/customization/integrations/extensions/mailhog) teaches you how to install and use the official MailHog extension. It’s a quick way to explore how extensions work in LocalStack. ::: - -:::note -The feature and the API are currently in preview stage and may be subject to change. -Please report any issues or feature requests on [LocalStack Extension's GitHub repository](https://github.com/localstack/localstack-extensions). -::: diff --git a/src/content/docs/aws/customization/integrations/extensions/mailhog.md b/src/content/docs/aws/customization/integrations/extensions/mailhog.md index 8858dbff4..756f7d5a0 100644 --- a/src/content/docs/aws/customization/integrations/extensions/mailhog.md +++ b/src/content/docs/aws/customization/integrations/extensions/mailhog.md @@ -77,5 +77,3 @@ You should see the email you sent in the MailHog UI. - Explore our collection of official extensions, along with a growing ecosystem of third-party extensions, in our [Extensions Library](https://app.localstack.cloud/extensions/library). - Learn about the various methods for extension management and automating their installation when using LocalStack in a CI environment. Get detailed insights from our [Managing Extensions](/aws/customization/integrations/extensions/managing-extensions) guide. -- Want to create your own extensions? - Dive into our guide on [Developing Extensions](/aws/customization/integrations/extensions/developing-extensions) for step-by-step instructions. diff --git a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx index 1e0bb5df5..e43716999 100644 --- a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx +++ b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx @@ -48,7 +48,6 @@ Options: -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 diff --git a/src/content/docs/aws/customization/integrations/index.mdx b/src/content/docs/aws/customization/integrations/index.mdx index 8a0bb1202..c6a47b9d5 100644 --- a/src/content/docs/aws/customization/integrations/index.mdx +++ b/src/content/docs/aws/customization/integrations/index.mdx @@ -1,17 +1,17 @@ --- title: Overview -description: Integrate LocalStack with third-party software and extend it with your own extensions and SDKs. +description: Integrate LocalStack with supported extensions, SDKs, application frameworks, and testing tools. template: doc editUrl: false --- import SectionCards from '../../../../../components/SectionCards.astro'; -LocalStack integrates with a wide range of third-party software from the cloud development ecosystem, and can be extended to fit your own tooling. This section is mostly useful to platform teams who need to wire LocalStack into existing development and testing workflows. +LocalStack integrates with a wide range of third-party software from the cloud development ecosystem. This section is mostly useful to platform teams who need to wire LocalStack into existing development and testing workflows. ## The Cloud Development Ecosystem -Whether you’re adding an extension, driving LocalStack from the Java or Python SDKs, or wiring it into an application framework, this section shows how to integrate LocalStack with the tools you already use. +Whether you’re installing a supported extension, driving LocalStack from the Java or Python SDKs, or wiring it into an application framework, this section shows how to integrate LocalStack with the tools you already use. ![Sample of supported integrations](/images/aws/integrations-overview.png)