revamp extensions docs (#854)

* revamp extension docs * Add basic reference guide for extensions linking to other resources
localstack · Oct 12, 2023 · 153251a · 153251a
1 parent abea751
commit 153251a
Show file tree

Hide file tree

Showing 22 changed files with 366 additions and 345 deletions.
diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md
@@ -20,7 +20,7 @@ hide_readingtime: true
 | [Lambda Hot Reloading]({{< ref "hot-reloading" >}})                       | The ability to make changes in Lambda handler files, and have them immediately reflected on each invocation of a Lambda function, without the need to redeploy the Lambda function.                                                                                                             |
 | [LocalStack API Key]({{< ref "api-key" >}})                               | An API key that can be configured via the LOCALSTACK_API_KEY environment variable, to enable advanced features in your LocalStack instance. We distinguish between individual developer keys, as well as CI keys for continuous integration environments (e.g., Github Actions, CircleCI, etc). |
 | [LocalStack Container]({{< ref "installation" >}})                        | The Docker/Podman container or Kubernetes pod running LocalStack.                                                                                                                                                                                                                               |
-| [LocalStack Extensions]({{< ref "references/localstack-extensions" >}})              | Extend and customize LocalStack using pluggable Python distributions to run applications alongside the main process in the LocalStack Docker container.                                                                                                                                         |
+| [LocalStack Extensions]({{< ref "references/extensions" >}})              | Extend and customize LocalStack using pluggable Python distributions to run applications alongside the main process in the LocalStack Docker container.                                                                                                                                         |
 | [LocalStack Platform]({{< ref "web-application" >}})                      | The LocalStack Web Application for licensed users to use advanced features, such as Stack Insights, CI Analytics, Resource Browser, and Team Collaboration.                                                                                                                                     |
 | [Stack Insights]({{< ref "user-guide/web-application/stack-insights" >}}) | Web Application feature to allow LocalStack users to report AWS API usage telemetry of LocalStack runs to their LocalStack account via the central dashboard.                                                                                                                                   |
 

diff --git a/content/en/references/extensions.md b/content/en/references/extensions.md
@@ -0,0 +1,69 @@
+---
+title: "Extensions Reference"
+linkTitle: "Extensions"
+weight: 50
+description: >
+  References for using and building LocalStack extensions.
+aliases:
+  /references/localstack-extensions/
+---
+
+Extensions are a powerful system to extend and customize LocalStack with additional features, emulators, or custom functionality.
+
+## Using extensions
+
+Find a user-oriented guide on extensions [here]({{< ref "/user-guide/extensions" >}}).
+* [Managing extensions]({{< ref "managing-extensions" >}})
+* [Developing extensions]({{< ref "developing-extensions" >}})
+* [List of official extensions]({{< ref "official-extensions" >}})
+
+## Extensions API reference
+
+* [Extension interface to implement](https://github.com/localstack/localstack-extensions#the-extensions-api)
+* [Extension API in our core codebase](https://github.com/localstack/localstack/tree/master/localstack/extensions/api)
+
+## Extension configuration
+
+### Environment variables
+
+| Environment Variable   | Description                                                                                                                                                                                                         |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| EXTENSION_DEV_MODE     | Enable/disable developer mode for extensions. Developer mode will mount local extension sources automatically into the container. See our user guide on [developing extensions]({{<ref "developing-extensions" >}}) |
+| EXTENSION_AUTO_INSTALL | A comma-separated list of extensions that will be installed automatically as the container starts up                                                                                                                |
+
+
+### Paths in the container
+
+* `/etc/localstack/conf.d/extensions.txt`: a file following the [pip requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/) that will automatically be installed on container startup.
+  This file can contain a list of extensions.
+
+
+## How extensions are managed
+
+Extensions are Python distributions managed in their own virtual environment within the [LocalStack Volume]({{< ref "filesystem" >}}).
+Specifically, within the "variable packages folder `/var/lib/localstack/lib`", the volume management system creates a folder `extensions` and a virtual environment `python_venv`, where all extensions and their dependencies live.
+LocalStack's own virtual environment is linked so it resolves all transitive dependencies of extensions.
+
+Here's an example what the default LocalStack volume looks like after installing the MailHog extension:
+
+```console
+thomas@om ~/.cache/localstack/volume
+ % tree -L 4
+.
+├── cache
+│   ├── ...
+├── lib
+│   ├── extensions
+│   │   └── python_venv
+│   │       ├── bin
+│   │       ├── include
+│   │       ├── lib
+│   │       ├── lib64 -> lib
+│   │       └── pyvenv.cfg
+│   └── mailhog
+│       └── v1.0.1
+│           └── MailHog_linux_amd64
+├── logs
+└── tmp
+    └── state
+```
diff --git a/content/en/user-guide/extensions/_index.md b/content/en/user-guide/extensions/_index.md
@@ -0,0 +1,26 @@
+---
+title: "LocalStack Extensions"
+linkTitle: "Extensions"
+weight: 3
+description: >
+  Use the power of LocalStack Extensions to customize and extend your local development experience.
+cascade:
+  type: docs
+slug: extensions
+---
+
+{{< figure src="https://user-images.githubusercontent.com/3996682/184503940-c30bfcac-e049-4ee4-b905-207b340111d1.png" >}}
+
+LocalStack Extensions allow developers to extend and customize LocalStack.
+Extensions are a feature of our paid offering.
+To install and use extensions, you need an active LocalStack license.
+
+Specific LocalStack Extensions are documented [here]({{< ref "user-guide/extensions/official-extensions" >}}) and
+can be discovered on our [Extension Library](https://app.localstack.cloud/extensions/library).
+Our blogpost about [LocalStack’s Cloudflare Extension](https://localstack.cloud/blog/2023-06-26-develop-your-cloudflare-workers-aws-apps-locally-with-localstack-miniflare/)
+showcases LocalStack as a local cloud development platform beyond AWS emulation.
+
+{{<alert title="Note">}}
+The feature and the API are currently experimental and may be subject to change.
+Please report any issues or feature requests on our [GitHub repository](https://github.com/localstack/localstack-extensions).
+{{</alert>}}
diff --git a/content/en/user-guide/extensions/developing-extensions/extension-installer.png b/content/en/user-guide/extensions/developing-extensions/extension-installer.png
diff --git a/...nt/en/references/localstack-extensions.md → ...extensions/developing-extensions/index.md b/...nt/en/references/localstack-extensions.md → ...extensions/developing-extensions/index.md
@@ -1,75 +1,15 @@
 ---
-title: "LocalStack Extensions"
-linkTitle: "LocalStack Extensions"
-weight: 50
-description: >
-  Using LocalStack Extensions to extend and customize LocalStack
-categories: ["LocalStack Pro"]
+title: "Developing extensions"
 tags: ["extensions"]
-aliases:
-  - /developer-guide/localstack-extensions/
-  - /contributing/localstack-extensions/
+weight: 10
+description: >
+  How to develop your own extensions
 ---
 
-LocalStack Extensions allow developers to extend and customize LocalStack.
-
-Specific LocalStack Extensions are documented [here]({{< ref "user-guide/tools/localstack-extensions" >}}) and
-can be discovered on our [GitHub repository](https://github.com/localstack/localstack-extensions).
-Our blogpost about [LocalStack’s Cloudflare Extension](https://localstack.cloud/blog/2023-06-26-develop-your-cloudflare-workers-aws-apps-locally-with-localstack-miniflare/)
-showcases LocalStack as a local cloud development platform beyond AWS emulation.
-
-{{<alert title="Note">}}
-The feature and the API are currently experimental and may be subject to change.
-Please report any issues or feature requests on our [GitHub repository](https://github.com/localstack/localstack-extensions).
-{{</alert>}}
-
-## Using Extensions
-
-Extensions are a LocalStack Pro feature. To use and install extensions, use the CLI to first login to your account
-
-{{< command >}}
-$ localstack login
-Please provide your login credentials below
-Username: ...
-{{< / command >}}
-
-To get a list of all available commands in LocalStack Extensions, run:
-
-{{< command >}}
-$ localstack extensions --help
-
-Usage: localstack extensions [OPTIONS] COMMAND [ARGS]...
-
-  Manage LocalStack extensions (beta)
-
-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
-{{< / command >}}
-
-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:
-
-{{< command >}}
-$ localstack extensions install localstack-extension-httpbin
-{{< / command >}}
-
-You can alternatively install the latest development version directly from our Git repository:
-
-{{< command >}}
-$ localstack extensions install "git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-httpbin&subdirectory=httpbin"
-{{< / command >}}
-
-## Developing Extensions
-
 This section provides a brief overview of how to develop your own extensions.
 
+## Overview
+
 ### 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/master/localstack/extensions/api).
@@ -157,10 +97,19 @@ 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!")
 ```
 
-### Package your Extension
+
+{{<alert title="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. 
+{{</alert>}}
+
+### Packaging extensions
 
 Your extensions needs to be packaged as a Python distribution with a
 `setup.cfg` or `setup.py` config. LocalStack uses the
@@ -196,7 +145,7 @@ entry point name is the plugin name `my_ready_announcer`. The object
 reference points to the plugin class.
 
 
-### Using the extensions CLI
+### 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.
@@ -216,19 +165,22 @@ Commands:
   new      Create a new LocalStack extension from the official extension...
 ```
 
-#### Creating new extensions
+## Creating your first extension
 
-First, create a new extension from a template:
+### 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`.
 
 {{< command >}}
 $ 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 [[email protected]]: 
-github_username [janedoe]: 
+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 [[email protected]]:
+github_username [janedoe]:
 version [0.1.0]:
 {{< / command >}}
 
@@ -248,7 +200,7 @@ my-localstack-extension
 
 Then run `make install` in the newly created project to make a distribution package.
 
-#### Start LocalStack with the extension
+### Start LocalStack with the extension
 
 To start LocalStack with the extension in dev mode, first enable it by running:
 
@@ -273,3 +225,14 @@ 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 <img src="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).
+
+{{< figure src="extension-installer.png" >}}
+
+<!-- TODO: add screenshot of installer with a specific extension, currently doesn't work -->
diff --git a/content/en/user-guide/extensions/managing-extensions/extensions-manager.png b/content/en/user-guide/extensions/managing-extensions/extensions-manager.png