diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index cffd522cc9..f3fd902e78 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -7,6 +7,7 @@ ignores: - 'content/en/user-guide/integrations/terraform/*' - 'content/en/user-guide/aws/events/*' - 'content/en/references/coverage/_index.md' + - 'content/en/getting-started/installation.md' customRules: - markdownlint-rule-max-one-sentence-per-line config: @@ -25,3 +26,4 @@ config: MD032: false # Lists should be surrounded by blank lines MD018: false # No space after hash on atx style header MD022: false # Headers should be surrounded by blank lines + MD037: false # Spaces inside emphasis markers diff --git a/config.toml b/config.toml index cc2e462c5b..8e62be8b87 100644 --- a/config.toml +++ b/config.toml @@ -210,7 +210,7 @@ enable = true [params.localstack] # LocalStack specific configuration values -latest_version = "3.8.0" +latest_version = "4.0.0" [params.localstack.cli_links] # Configure the different download links for the cli-binary-download shortcode diff --git a/content/en/getting-started/auth-token/index.md b/content/en/getting-started/auth-token/index.md index 3e46f4b9f1..0a4a108383 100644 --- a/content/en/getting-started/auth-token/index.md +++ b/content/en/getting-started/auth-token/index.md @@ -2,24 +2,29 @@ title: "Auth Token" weight: 20 description: > - Configure your Auth Token to start LocalStack + Configure your Auth Token to access and activate LocalStack. --- ## Introduction -The Auth Token is a personal identifier used for user authentication outside the LocalStack Web Application, particularly in conjunction with the LocalStack core cloud emulator. -Its primary functions are to retrieve the user's license and enable access to advanced features, effectively replacing the older developer API keys. +The Auth Token identifies and authenticates users outside the LocalStack Web Application to activate the LocalStack core cloud emulator. +It primarily accesses your workspace and advanced services & features. -The Auth Token remains unchanged unless manually rotated by the user, regardless of any license assignment changes. -You can locate your Auth Token on the [Getting Started page](https://app.localstack.cloud/getting-started) or the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) in the LocalStack Web Application. +Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**: -{{< callout "warning" >}} -- Previously, API keys were required to activate the LocalStack core cloud emulator. - These API keys are now being replaced by Auth Tokens. -- Currently, LocalStack supports both API Keys and Auth Tokens. - However, API Keys will be discontinued in the upcoming major release of LocalStack. -- To update your LocalStack configuration, replace your API Key with an Auth Token. - Use the `LOCALSTACK_AUTH_TOKEN` environment variable in place of `LOCALSTACK_API_KEY`. +- The **Developer Auth Token** is linked to a specific user within a specific workspace. + Every user has their own Auth Token. + It cannot be deleted but can be rotated for security reasons if needed. +- The **CI Auth Token** is not associated with any specific user and is designed for use in CI environments and other non-developer contexts. + These tokens are stored in the workspace and can be managed by members with appropriate permissions. + +Both the **Developer Auth Token** and **CI Auth Token** can be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). + +{{< callout "warning">}} +- It's crucial to keep your Auth Token confidential. + Do not include it in source code management systems, such as Git repositories. +- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. +- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). {{< /callout >}} ## Managing your License @@ -51,7 +56,7 @@ If you do not assign a license, you will not be able to use LocalStack even if y {{< /callout >}} To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license). -You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) to view your Auth Token. +You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) to view your **Developer Auth Token** and **CI Auth Token**. ## Configuring your Auth Token @@ -63,7 +68,7 @@ The following sections describe the various methods of setting your Auth Token. - It's crucial to keep your Auth Token confidential. Do not include it in source code management systems, such as Git repositories. - Be aware that if an Auth Token is committed to a public repository, it's at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. -- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token). +- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). {{< /callout >}} ### LocalStack CLI @@ -76,7 +81,8 @@ localstack auth set-token localstack start {{< /tab >}} {{< tab header="Windows" lang="powershell" >}} -$env:LOCALSTACK_AUTH_TOKEN=""; localstack start +localstack auth set-token +localstack start {{< /tab >}} {{< /tabpane >}} @@ -121,13 +127,31 @@ environment: You can manually set the Auth Token, or use the `export` command to establish the Auth Token in your current shell session. This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation. -## Licensing-related configuration +### CI Environments + +CI environments require a CI Auth Token. +Developer Auth Tokens cannot be used in CI. +CI Auth Tokens are available on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and are configured similarly to Developer Auth Tokens. + +To set the CI Auth Token, add the Auth Token value in the `LOCALSTACK_AUTH_TOKEN` environment variable of your CI provider, and refer to it when starting LocalStack in your CI workflow. +You can find detailed examples in our [LocalStack in CI documentation](https://docs.localstack.cloud/user-guide/ci/). + +## Rotating the Auth Token + +Your personal Auth Token provides full access to your workspace and LocalStack license. +It's important to treat auth tokens as confidential, avoiding sharing or storing them in source control management systems (SCMs) like Git. + +If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay. +When you reset a token, the old one is immediately deactivated, losing its ability to access your license or workspace. +It is not possible to restore previous tokens. + +To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and select the **Reset Auth Token** option. + +## Licensing configuration & activation checkup To avoid logging any licensing-related error messages, set `LOG_LICENSE_ISSUES=0` in your environment. Refer to our [configuration guide](https://docs.localstack.cloud/references/configuration/#localstack-pro) for more information. -## Checking license activation - The simplest method to verify if LocalStack is active is by querying the health endpoint for a list of running services: {{< tabpane text=true >}} @@ -170,37 +194,37 @@ Another way to confirm this is by checking the logs of the LocalStack container [...] Successfully activated license {{< / command >}} -Otherwise, check our collected most [common activation issues](#common-activation-issues). +Otherwise, check our [troubleshooting](#troubleshooting) section. -## Rotating the Auth Token +## FAQ -Your personal Auth Token provides full access to your workspace and LocalStack license. -It's important to treat auth tokens as confidential, avoiding sharing or storing them in source control management systems (SCMs) like Git. +### How do I activate older versions of LocalStack (Before v3.0)? -If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay. -When you reset a token, the old one is immediately deactivated, losing its ability to access your license or workspace. -It is not possible to restore previous tokens. +Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation. + +For backwards compatibility, we've updated our back-end to accept new Auth Tokens within the `LOCALSTACK_API_KEY` variable. +You can use the new Auth Token in the same way you previously used the API key. -To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) and select the **Reset Auth Token** option. +### When will the legacy API keys be phased out? -### Configuring your CI environment +In early 2025, we will begin phasing out legacy API keys entirely. +After the sunsetting period, legacy API and legacy CI keys will no longer activate or work with LocalStack. -For use in Continuous Integration (CI) or automated test environments, a CI key is necessary. -Refer to our [CI documentation]({{< ref "user-guide/ci" >}}) for guidance on securely handling secrets, including storing your CI key in these environments. +During the sunsetting period, the legacy service will experience scheduled downtimes. +These are planned to encourage users to transition to new Auth Tokens while minimizing impact for those who have not yet updated. -To configure your CI key, you need to set the `LOCALSTACK_API_KEY` environment variable to your CI key. -You can find your CI key on the [CI Keys page](https://app.localstack.cloud/workspace/ci-keys) in the LocalStack Web Application. +The downtime schedule will be communicated well in advance, allowing users ample time to switch to the new Auth Tokens. -## Common activation issues +## Troubleshooting -Starting from version 2.0.0, the `localstack/localstack-pro` image in LocalStack demands a successful license activation for startup. +While using Auth Tokens, LocalStack demands a successful license activation for startup. If the activation of the license is unsuccessful, LocalStack will exit and display error messages. ```bash =============================================== License activation failed! πŸ”‘βŒ -Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your auth token or API key in the LocalStack web app https://app.localstack.cloud. +Reason: The credentials defined in your environment are invalid. Please make sure to either set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token, or the LOCALSTACK_API_KEY variable to a valid LocalStack API key. You can find your Auth Token or API key in the LocalStack web app https://app.localstack.cloud. Due to this error, Localstack has quit. LocalStack pro features can only be used with a valid license. @@ -213,8 +237,8 @@ The key activation in LocalStack may fail for several reasons, and the most comm ### Missing Credentials -You need to provide either an Auth Token or an API Key to start the LocalStack Pro image successfully. -You can find your Auth Token or API Key on the [Auth Token page](https://app.localstack.cloud/workspace/auth-token) or the [Legacy API Key page](https://app.localstack.cloud/workspace/api-keys) in the LocalStack Web Application. +You need to provide either an Auth Token to start the LocalStack Pro image successfully. +You can find your Auth Token on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token or use the following command to set it up: diff --git a/content/en/getting-started/faq.md b/content/en/getting-started/faq.md index e1ccf078a6..f0e9ea6499 100644 --- a/content/en/getting-started/faq.md +++ b/content/en/getting-started/faq.md @@ -27,7 +27,7 @@ To resolve the issue follow the steps: Additionally, it’s important to clear the cached certificate from your host machine as mentioned above. 2. **Use HTTP Instead of HTTPS**: Where possible, use `http://` instead of `https://` to avoid issues related to the revoked certificates. This workaround works with most browsers. - However, Safari requires additional steps: + However, Safari requires additional steps: 2.1. **Safari Users**: To make this work, you’ll need to first navigate to the page in a new tab and accept the security warning. To do this, make sure that LocalStack is started with `SKIP_SSL_CERT_DOWNLOAD=1` and that you have cleared the cached certificate as mentioned above. Once you’ve accepted the warning, you should be able to proceed. @@ -280,20 +280,20 @@ $ curl localhost:4566/_localstack/health | jq {{< / command >}} If a Pro-only [service]({{< ref "aws" >}}) -- like [XRay]({{< ref "xray" >}}) -- is running, LocalStack Pro or Enterprise has started successfully. -If your auth token is invalid, you will see an error message like this in the logs of LocalStack: +If your Auth Token is invalid, you will see an error message like this in the logs of LocalStack: ```bash license activation failed! Reason: ... ``` -If this error occurs, something is wrong with your auth token or license. -Make sure your auth token is set correctly (check for typos!) and your license is valid. -If the auth token still does not work, please [contact us](https://localstack.cloud/contact/). +If this error occurs, something is wrong with your Auth Token or license. +Make sure your Auth Token is set correctly (check for typos!) and your license is valid. +If the Auth Token still does not work, please [contact us](https://localstack.cloud/contact/). ### How are CI credits in LocalStack calculated? -A CI key allows you to use LocalStack in your CI environment. -Every activation of a CI key consumes one build credit. +A CI Auth Token allows you to use LocalStack in your CI environment. +Every activation with a CI Auth Token consumes one CI credit. This means that with every build triggered through the LocalStack container you will consume one credit. To understand the CI pricing across our product tiers, follow up with our [LocalStack in CI]({{}}) documentation. @@ -329,7 +329,7 @@ $ dig api.localstack.cloud If the result has some other status than `status: NOERROR,` your machine cannot resolve this domain. Some corporate DNS servers might filter requests to certain domains. -Contact your network administrator to safelist`localstack.cloud` domains. +Contact your network administrator to safelist `localstack.cloud` domains. ### How does LocalStack Pro handle security patches and bug fixes? diff --git a/content/en/getting-started/help-and-support/index.md b/content/en/getting-started/help-and-support/index.md index 724f2816e1..bc1a9319ea 100644 --- a/content/en/getting-started/help-and-support/index.md +++ b/content/en/getting-started/help-and-support/index.md @@ -55,7 +55,7 @@ At the moment, we only provide support in `English`, as we are an international | Support ticketing portal | | | | βœ… | | SLAs | | | | βœ… | | Direct Slack connect channel | | | | βœ… | -| Dedicated CSM and AM | | | | βœ… | +| Dedicated CSM and TAM | | | | βœ… | - Real time chat support is offered during our [Support Business Hours](#support-business-hours) diff --git a/content/en/getting-started/installation.md b/content/en/getting-started/installation.md index a1f6967c8d..c4e8c7229e 100644 --- a/content/en/getting-started/installation.md +++ b/content/en/getting-started/installation.md @@ -15,12 +15,14 @@ The quickest way get started with LocalStack is by using the LocalStack CLI. It allows you to start LocalStack from your command line. Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on. +### Installing LocalStack CLI + The CLI starts and manages the LocalStack Docker container. For alternative methods of managing the LocalStack container, see our [alternative installation instructions]({{< ref "#alternatives" >}}). {{< tabpane text=true >}} - @@ -75,8 +77,8 @@ $ brew install localstack/tap/localstack-cli {{< /tab >}} - {{< tab header="**MacOS**" >}} @@ -182,6 +184,8 @@ It should be installed and started entirely under a local non-root user. {{< /tab >}} {{< /tabpane >}} +### Starting LocalStack + To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: {{< command >}} $ localstack --version @@ -189,9 +193,56 @@ $ localstack --version {{< / command >}} You are all set! +You can now start LocalStack with the following command: + +{{< command >}} +$ localstack start # start localstack in background with -d flag + + __ _______ __ __ + / / ____ _________ _/ / ___// /_____ ______/ /__ + / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ + / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< + /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| + + πŸ’» LocalStack CLI 4.0.0 + πŸ‘€ Profile: default + +[12:47:13] starting LocalStack in Docker mode 🐳 localstack.py:494 + preparing environment bootstrap.py:1240 + configuring container bootstrap.py:1248 + starting container bootstrap.py:1258 +[12:47:15] detaching bootstrap.py:1262 + +{{< / command >}} +{{< callout >}} To use all of LocalStack's features we recommend to [get a LocalStack account and set up your auth token]({{< ref "auth-token" >}}). -Afterwards, check out our [Quickstart guide]({{< ref "quickstart" >}}) to start your local cloud! +Afterwards, check out our [Quickstart guide]({{< ref "quickstart" >}}) to start your local development cloud! +{{< /callout >}} + +### Updating LocalStack CLI + +The LocalStack CLI allows you to easily update the different components of LocalStack. +To check the various options available for updating, run: +{{< command >}} +$ localstack update --help +Usage: localstack update [OPTIONS] COMMAND [ARGS]... + + Update different LocalStack components. + +Options: + -h, --help Show this message and exit. + +Commands: + all Update all LocalStack components + docker-images Update docker images LocalStack depends on + localstack-cli Update LocalStack CLI +{{< / command >}} + +{{< callout >}} +Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. +If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. +{{< /callout >}} ## Alternatives @@ -213,6 +264,9 @@ Besides using the CLI, there are other ways of starting and managing your LocalS Use Helm to create a LocalStack deployment in a Kubernetes cluster. LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. + +The LocalStack emulator is available on Docker Hub in two editions: the Community Edition (`localstack/localstack`) and the Pro Edition (`localstack/localstack-pro`). + For a comprehensive overview of the LocalStack images, check out our [Docker images documentation]({{< ref "docker-images" >}}). ### LocalStack Desktop @@ -286,7 +340,7 @@ $ docker-compose up - This command pulls the current nightly build from the `master` branch (if you don't have the image locally) and **not** the latest supported version. If you want to use a specific version, set the appropriate LocalStack image tag at `services.localstack.image` in the `docker-compose.yml` file (for example `localstack/localstack:`). -- If you are using LocalStack with an [auth token]({{< ref "auth-token" >}}), you need to specify the image tag as `localstack/localstack-pro` in the `docker-compose.yml` file. +- If you are using LocalStack with an [Auth Token]({{< ref "auth-token" >}}), you need to specify the image tag as `localstack/localstack-pro` in the `docker-compose.yml` file. Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. - This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. @@ -300,7 +354,7 @@ $ docker-compose up - If using the Docker default bridge network using `network_mode: bridge`, container name resolution will not work inside your containers. Please consider removing it, if this functionality is needed. -- To configure an auth token, refer to the [auth token]({{< ref "auth-token" >}}) documentation. +- To configure an Auth Token, refer to the [Auth Token]({{< ref "auth-token" >}}) documentation. {{< /callout >}} Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). @@ -357,7 +411,7 @@ $ docker run \ If you want to use a specific version of LocalStack, use the appropriate tag: `docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:`. Check-out the [LocalStack releases](https://github.com/localstack/localstack/releases) to know more about specific LocalStack versions. -- If you are using LocalStack with an [auth token]({{< ref "auth-token" >}}), you need to specify the image tag as `localstack/localstack-pro` in your Docker setup. +- If you are using LocalStack with an [Auth Token]({{< ref "auth-token" >}}), you need to specify the image tag as `localstack/localstack-pro` in your Docker setup. Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. - This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. @@ -372,7 +426,7 @@ $ docker run \ - To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. -- To configure an auth token, refer to the [auth token]({{< ref "auth-token" >}}) documentation. +- To configure an Auth Token, refer to the [Auth Token]({{< ref "auth-token" >}}) documentation. {{< /callout >}} ### Helm @@ -394,29 +448,18 @@ $ helm upgrade --install localstack localstack-repo/localstack The Helm charts are not maintained in the main repository, but in a [separate one](https://github.com/localstack/helm-charts). -## Updating - -The LocalStack CLI allows you to easily update the different components of LocalStack. -To check the various options available for updating, run: -{{< command >}} -$ localstack update --help -Usage: localstack update [OPTIONS] COMMAND [ARGS]... - - Update different LocalStack components. - -Options: - -h, --help Show this message and exit. - -Commands: - all Update all LocalStack components - docker-images Update docker images LocalStack depends on - localstack-cli Update LocalStack CLI -{{< / command >}} +## What's next? -{{< callout >}} -Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. -If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. -{{< /callout >}} +Now that you have LocalStack up and running, the following resources might be useful for your next steps: +- Check out our [Quickstart guide]({{< ref "quickstart" >}}) if you are a new user to get started with LocalStack quickly. +- [Use the LocalStack integrations]({{< ref "integrations" >}}) to interact with LocalStack and other integrated tools, for example: + - Use `awslocal` to use the AWS CLI against your local cloud! + - Use the Serverless Framework with LocalStack! + - And many more! +- [Find out how to configure LocalStack]({{< ref "configuration" >}}) such that it perfectly fits your need. +- [Use LocalStack in your CI environment]({{< ref "user-guide/ci" >}}) to increase your code quality. +- [Checkout LocalStack's Cloud Developer Tools]({{< ref "user-guide/tools" >}}) to further increase your development efficiency with LocalStack. +- Find out about the ways you can [configure LocalStack]({{< ref "configuration" >}}). ## Troubleshooting @@ -483,16 +526,3 @@ After running the task, run the diagnostic endpoint and share the archive file w We have extensive network troubleshooting documentation available [here]({{< ref "references/network-troubleshooting" >}}). If this does not solve your problem then please [reach out]({{< ref "help-and-support" >}}). - -## What's next? - -Now that you have LocalStack up and running, the following resources might be useful for your next steps: -- Check out our [Quickstart guide]({{< ref "quickstart" >}}) if you are a new user to get started with LocalStack quickly. -- [Use the LocalStack integrations]({{< ref "integrations" >}}) to interact with LocalStack and other integrated tools, for example: - - Use `awslocal` to use the AWS CLI against your local cloud! - - Use the Serverless Framework with LocalStack! - - And many more! -- [Find out how to configure LocalStack]({{< ref "configuration" >}}) such that it perfectly fits your need. -- [Use LocalStack in your CI environment]({{< ref "user-guide/ci" >}}) to increase your code quality. -- [Checkout LocalStack's Cloud Developer Tools]({{< ref "user-guide/tools" >}}) to further increase your development efficiency with LocalStack. -- Find out about the ways you can [configure LocalStack]({{< ref "configuration" >}}). diff --git a/content/en/references/api-key.md b/content/en/references/api-key.md index 6e5c99f5cc..f34ef3fae5 100644 --- a/content/en/references/api-key.md +++ b/content/en/references/api-key.md @@ -13,8 +13,10 @@ aliases: - LocalStack is transitioning from API Keys to Auth Tokens for activation. Auth Tokens streamline license management and remove the need for developers to adjust their setup when license changes occur. - For detailed information and guidance on migrating your LocalStack setup to Auth Tokens, please consult our [Auth Token documentation]({{< ref "auth-token" >}}). -- API Keys will remain functional for LocalStack Pro and Enterprise users until the next major release. - Following this release, LocalStack Pro and Enterprise will exclusively use Auth Tokens. +- API Keys will remain functional for LocalStack Pro and Enterprise users till early 2025 +- After the sunsetting period, legacy API and legacy CI keys will no longer activate or work with LocalStack. +- During the sunsetting period, the legacy service will experience scheduled downtimes. +- We strongly encourage users to transition to new Auth Tokens while minimizing impact for those who have not yet updated. {{< /callout >}} The LocalStack API key is a unique identifier to activate your LocalStack license needed to start LocalStack Pro. diff --git a/content/en/references/configuration.md b/content/en/references/configuration.md index f420e4590c..4b1416ea65 100644 --- a/content/en/references/configuration.md +++ b/content/en/references/configuration.md @@ -75,7 +75,7 @@ This section covers configuration options that are specific to certain AWS servi | Variable | Example Values | Description | | - | - | - | -| `PROVIDER_OVERRIDE_APIGATEWAY` | `next_gen` | Use [the new API Gateway implementation]({{< ref "user-guide/aws/apigateway#new-api-gateway-implementation" >}}) for both API Gateway v1 and v2, available since LocalStack 3.8. | +| `PROVIDER_OVERRIDE_APIGATEWAY` | `legacy`\|`next_gen` (default)| The [new API Gateway implementation]({{< ref "user-guide/aws/apigateway#new-api-gateway-implementation" >}}) is active by default since LocalStack 4.0. | ### AppSync @@ -94,7 +94,8 @@ This section covers configuration options that are specific to certain AWS servi | Variable | Example Values | Description | | - | - | - | -| `LOCALSTACK_ENABLE_BEDROCK` | `1` | Use the Bedrock provider | +| `BEDROCK_PREWARM` | `0` (default) \| `1` | Pre-warm the Bedrock engine directly on LocalStack startup instead of on demand. | +| `DEFAULT_BEDROCK_MODEL` | `mistral` (default) | The model to use to handle text model invocations in Bedrock. Any text-based model available for Ollama is usable. | ### BigData (EMR, Athena, Glue) @@ -232,9 +233,8 @@ Please consult the [migration guide]({{< ref "user-guide/aws/lambda#migrating-to | `LAMBDA_DOCKER_FLAGS` | `-e KEY=VALUE`, `-v host:container`, `-p host:container`, `--add-host domain:ip` | Additional flags passed to Docker `run`\|`create` commands. Supports environment variables (also with `--env-file`, but the file has to be mounted into the LocalStack container), ports, volume mounts, extra hosts, networks, DNS servers, labels, ulimits, user, platform, and privileged mode. The `--env-file` argument for Docker `run` and Docker Compose have different feature sets. To provide both, we support the `--env-file` for environment files with the docker run syntax, while `--compose-env-file` supports the full docker compose features, like placeholders with `${}`, replacing quotes, etc. | | `LAMBDA_DOCKER_NETWORK` | `bridge` (Docker default) | [Docker network driver](https://docs.docker.com/network/) for the Lambda and ECS containers. Needs to be set to the network the LocalStack container is connected to. Limitation: `host` mode currently not supported. | | `LAMBDA_DOWNLOAD_AWS_LAYERS` | `1` (default, pro) | Whether to download public Lambda layers from AWS through a LocalStack proxy when creating or updating functions. | -| `LAMBDA_EVENT_SOURCE_MAPPING` | `v2` | Use the new Lambda Event Source Mapping (ESM) implementation. (preview) | | `LAMBDA_IGNORE_ARCHITECTURE` | `0` (default) | Whether to ignore the AWS architectures (x86_64 or arm64) configured for the lambda function. Set to `1` to run cross-platform compatible lambda functions natively (i.e., Docker selects architecture). | -| `LAMBDA_K8S_IMAGE_PREFIX` | `amazon/aws-lambda-` (default, pro) | Prefix for images that will be used to execute Lambda functions in Kubernetes. | +| `LAMBDA_K8S_IMAGE_PREFIX` | `amazon/aws-lambda-` (default, enterprise) | Prefix for images that will be used to execute Lambda functions in Kubernetes. | | `LAMBDA_K8S_INIT_IMAGE` | | Specify the image for downloading the init binary from LocalStack. The image must include the `curl` and `chmod` commands. This is only relevant for container-based Lambdas on Kubernetes | | `LAMBDA_KEEPALIVE_MS` | `600000` (default 10min) | Time in milliseconds until lambda shuts down the execution environment after the last invocation has been processed. Set to `0` to immediately shut down the execution environment after an invocation. | | `LAMBDA_LIMITS_CONCURRENT_EXECUTIONS` | `1000` (default) | The maximum number of events that functions can process simultaneously in the current Region. See [AWS service quotas](https://docs.aws.amazon.com/general/latest/gr/lambda-service.html) | @@ -245,7 +245,7 @@ Please consult the [migration guide]({{< ref "user-guide/aws/lambda#migrating-to | `LAMBDA_REMOVE_CONTAINERS` | `1` (default) | Whether to remove any Lambda Docker containers. | | `LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT` | `20` (default) | How many seconds Lambda will wait for the runtime environment to start up. Increase this timeout if I/O is slow or your Lambda deployments are large or contain many files. | | `LAMBDA_RUNTIME_EXECUTOR` | `docker` (default) | Where Lambdas will be executed. | -| | `kubernetes` (pro) | Execute lambdas in a Kubernetes cluster. | +| | `kubernetes` (enterprise) | Execute lambdas in a Kubernetes cluster. | | `LAMBDA_RUNTIME_IMAGE_MAPPING` | [base images for Lambda](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-images.html) (default) | Customize the Docker image of Lambda runtimes, either by:
a) pattern with `` placeholder, e.g. `custom-repo/lambda-:2022`
b) json dict mapping the `` to an image, e.g. `{"python3.9": "custom-repo/lambda-py:thon3.9"}` | | `LAMBDA_RUNTIME_VALIDATION` | `0` (default) | Set to `1` to enforce strict [AWS parity](https://blog.localstack.cloud/2022-08-04-parity-explained/) by raising an exception when using a deprecated [Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) for the API operation [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html). Deprecated Lambda runtimes (e.g., `nodejs14.x`) can be used with disabled validation (current default). | | `LAMBDA_SYNCHRONOUS_CREATE` | `0` (default) | Set to `1` to create lambda functions synchronously (not recommended). | @@ -296,17 +296,8 @@ Please consult the [migration guide]({{< ref "user-guide/aws/lambda#migrating-to | Variable | Example Values | Description | | - | - | - | -| `S3_DIR` || **Deprecated since 3.0.0** This is only supported for the `legacy_v2` provider. Configure a global parent directory that contains all buckets as sub-directories (`S3_DIR=/path/to/root`) or an individual directory that will get mounted as special bucket names (`S3_DIR=/path/to/root/bucket1:bucket1`). Only available for Localstack Pro. | `S3_SKIP_SIGNATURE_VALIDATION`| `0` \| `1` (default) | Used to toggle validation of S3 pre-signed URL request signature. Set to `0` to validate. Note that validation can only pass if the `AWS_SECRET_ACCESS_KEY` is set to `test` or if using credentials returned from `STS.AssumeRole` | | `S3_SKIP_KMS_KEY_VALIDATION` | `0` \| `1` (default) | Used to toggle validation of provided KMS key in S3 operations. | -| `PROVIDER_OVERRIDE_S3` | `legacy_v2` \| `v3` (default) | The new LocalStack-native S3 provider (v3) is active by default since LocalStack 3.0. | - -### StepFunctions - -| Variable | Example Values | Description | -| - | - | - | -| `PROVIDER_OVERRIDE_STEPFUNCTIONS` | `legacy` \| `v2` (default) | The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0. | -| `STEPFUNCTIONS_LAMBDA_ENDPOINT` | `default` | **Deprecated since 3.0.0** This is only supported for the `legacy` provider. URL to use as the Lambda service endpoint in Step Functions. By default this is the LocalStack Lambda endpoint. Use default to select the original AWS Lambda endpoint.
**Removed in new provider.** | ### SQS @@ -433,6 +424,10 @@ These configurations have already been removed and **won't have any effect** on | Variable | Removed in | Example Values | Description | | - | - | - | - | +| `LAMBDA_EVENT_SOURCE_MAPPING` | 4.0.0 | `v2` (default since [3.8.0](https://blog.localstack.cloud/localstack-release-v-3-8-0/#new-default-lambda-event-source-mapping-implementation)) \| `v1` | Feature flag to switch Lambda Event Source Mapping (ESM) implementations. | +| `PROVIDER_OVERRIDE_STEPFUNCTIONS` | 4.0.0 | `v2` (default) \| `legacy` | The new LocalStack-native StepFunctions provider (v2) is active by default since LocalStack 3.0. | +| `STEPFUNCTIONS_LAMBDA_ENDPOINT` | 4.0.0 | `default` | This is only supported for the `legacy` provider. URL to use as the Lambda service endpoint in Step Functions. By default this is the LocalStack Lambda endpoint. Use default to select the original AWS Lambda endpoint. | +| `S3_DIR` | 4.0.0 | `/path/to/root` | This was only supported for the `legacy_v2` provider. Configure a global parent directory that contains all buckets as sub-directories (`S3_DIR=/path/to/root`) or an individual directory that will get mounted as special bucket names (`S3_DIR=/path/to/root/bucket1:bucket1`). Only available for Localstack Pro. | `_BACKEND` | 3.0.0 | `http://localhost:7577` | Custom endpoint URL to use for a specific service, where `` is the uppercase service name. | | `_PORT_EXTERNAL` | 3.0.0 | `4567` | Port number to expose a specific service externally . `SQS_PORT_EXTERNAL`, e.g. , is used when returning queue URLs from the SQS service to the client. | | `ACTIVATE_NEW_POD_CLIENT` | 3.0.0 | `0`\|`1` (default) | Whether to use the new Cloud Pods client leveraging LocalStack container's APIs. | diff --git a/content/en/references/credentials.md b/content/en/references/credentials.md index d27b7f1353..3e053e4f39 100644 --- a/content/en/references/credentials.md +++ b/content/en/references/credentials.md @@ -6,18 +6,20 @@ description: > Credentials for accessing LocalStack AWS API --- -Like AWS, LocalStack requires access key IDs to be set in all operations. -The choice of access key ID will affect [multi-account namespacing]({{< ref "multi-account-setups" >}}). -Values of secret access keys are currently ignored by LocalStack. +Like AWS, LocalStack requires AWS credentials to be supplied in all API operations. + +## Access Key ID + +For root accounts, the choice of access key ID affects [multi-account namespacing]({{< ref "multi-account-setups" >}}). Access key IDs can be one of following patterns: -## Accounts IDs +### Accounts IDs You can specify a 12-digit number which will be taken by LocalStack as the account ID. For example, `112233445566`. -## Structured access key ID +### Structured access key ID You can specify a structured key like `LSIAQAAAAAAVNCBMPNSG` (which translates to account ID `000000000042`). This must be at least 20 characters in length and must be decodable to an account ID. @@ -34,7 +36,13 @@ We strongly recommend leaving it on. Please refer to the [IAM docs]({{< ref "user-guide/aws/iam" >}}) to learn how to create access keys in LocalStack. -## Alphanumeric string +### Alphanumeric string You can also specify an arbitrary alphanumeric access key ID like `test` or `foobar123`. -In all such cases, the account ID will be evaluated to `000000000000`. +In all such cases, the account ID is evaluated to `000000000000`. + +## Secret Access Key + +The value of the secret access key are currently ignored by LocalStack. + +We recommend using the same value as access key ID or `test` diff --git a/content/en/references/docker-images.md b/content/en/references/docker-images.md index c904e0f95d..4a34a8dd34 100644 --- a/content/en/references/docker-images.md +++ b/content/en/references/docker-images.md @@ -23,7 +23,7 @@ $ docker pull localstack/localstack:latest {{< / command >}} To use the LocalStack Community image, you don't need to sign-up for an account on [LocalStack Web Application](https://app.localstack.cloud). -The Community image is free to use and does not require any API key to run. +The Community image is free to use and does not require a license to run. The Community image can be used to run [local AWS services](https://docs.localstack.cloud/user-guide/aws/) with [integrations](https://docs.localstack.cloud/user-guide/integrations/) on your local machine or in your [continuous integration pipelines](https://docs.localstack.cloud/user-guide/ci/). The Community image also covers a limited set of [LocalStack Tools](https://docs.localstack.cloud/user-guide/tools/) to make your life as a cloud developer easier. @@ -42,8 +42,8 @@ To use the LocalStack Pro image, you can pull the image from Docker Hub: $ docker pull localstack/localstack-pro:latest {{< / command >}} -To use the LocalStack Pro image, you must configure an environment variable named `LOCALSTACK_AUTH_TOKEN` to contain your auth token. -The LocalStack Pro image will display a warning if you do not set an auth token (or if the license is invalid/expired) and will not activate the Pro features. +To use the LocalStack Pro image, you must configure an environment variable named `LOCALSTACK_AUTH_TOKEN` to contain your Auth Token. +The LocalStack Pro image will display a warning if you do not set an Auth Token (or if the license is invalid/expired) and will not activate the Pro features. LocalStack Pro gives you access to the complete set of LocalStack features, including the [LocalStack Web Application](https://app.localstack.cloud) and [dedicated customer support](https://docs.localstack.cloud/getting-started/help-and-support/#pro-support). You can use the Pro image to start your LocalStack container using various [installation methods](https://docs.localstack.cloud/getting-started/installation/). diff --git a/content/en/references/init-hooks.md b/content/en/references/init-hooks.md index 93a4695d0d..e79e727e7b 100644 --- a/content/en/references/init-hooks.md +++ b/content/en/references/init-hooks.md @@ -7,7 +7,7 @@ aliases: - /localstack/init-hooks/ --- -## Lifecycle stages and hooks +## Lifecycle Stages and Hooks LocalStack has four well-known lifecycle phases or stages: * `BOOT`: the container is running but the LocalStack runtime has not been started @@ -41,14 +41,14 @@ A script can be in one of four states: `UNKNOWN`, `RUNNING`, `SUCCESSFUL`, `ERRO Scripts are by default in the `UNKNOWN` state once they have been discovered. The remaining states should be self-explanatory. -### Execution order and script failures +### Execution Order and Script Failures Scripts are sorted and executed in alphanumerical order. If you use subdirectories, scripts in parent folders are executed first, and then the directories are traversed in alphabetical order, depth first. If an init script fails, the remaining scripts will still be executed in order. A script is considered in `ERROR` state if it is a shell script and returns with a non-zero exit code, or if a Python script raises an exception during its execution. -## Status endpoint +## Status Endpoint There is an additional endpoint at `localhost:4566/_localstack/init` which returns the state of the initialization procedure. Boot scripts (scripts placed in `boot.d`) are currently always in the `UNKNOWN` state, since they are executed outside the LocalStack process and we don't know whether they have been successfully executed or not. @@ -80,7 +80,7 @@ curl -s localhost:4566/_localstack/init | jq . } ``` -### Query individual stages +### Querying Stages You can also query a specific stage at `localhost:4566/_localstack/init/`: @@ -109,12 +109,14 @@ curl -s localhost:4566/_localstack/init/ready | jq .completed which returns either `true` or `false`. -## Usage example +## Example A common use case for init hooks is pre-seeding LocalStack with custom state. -If you have more complex state, [Cloud Pods]({{< ref "user-guide/state-management/cloud-pods" >}}) and [how to auto-load them on startup]({{< ref "user-guide/state-management/cloud-pods#auto-loading-cloud-pods" >}}) may be a good option to look into! +For example if you want to have a certain S3 bucket or DynamoDB table created when starting LocalStack, init hooks can be very useful. -But for simple state, for example if you want to have a certain S3 bucket or DynamoDB table created when starting LocalStack, init hooks can be very useful. +{{< callout "tip" >}} +If you have more complex states, [Cloud Pods]({{< ref "user-guide/state-management/cloud-pods" >}}) and [how to auto-load them on startup]({{< ref "user-guide/state-management/cloud-pods#auto-loading-cloud-pods" >}}) may be a good option to look into! +{{< /callout >}} To execute aws cli commands when LocalStack becomes ready, simply create a script `init-aws.sh` and mount it into `/etc/localstack/init/ready.d/`. @@ -123,6 +125,9 @@ You can use anything available inside the container, including `awslocal`: ```bash #!/bin/bash + +export AWS_ACCESS_KEY_ID=000000000000 AWS_SECRET_ACCESS_KEY=000000000000 + awslocal s3 mb s3://my-bucket awslocal sqs create-queue --queue-name my-queue ``` @@ -155,24 +160,20 @@ DOCKER_FLAGS='-v /path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh' Another use for init hooks can be seen when [adding custom TLS certificates to LocalStack]({{< ref "custom-tls-certificates#custom-tls-certificates-with-init-hooks" >}}). -### Terraform configuration files as init hooks +### Terraform Files as Init Hooks Running Terraform configuration files as init hooks requires the installation of a special extension. For more information on how to manage [LocalStack extensions]({{< ref "user-guide/extensions/" >}}), please refer to the dedicated documentation page, and for more details on running init hooks in development mode, you can check out the [extension repository description](https://github.com/localstack/localstack-extensions/tree/main/terraform-init). -##### Usage - Start LocalStack with **`EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init"`**. Mount a **`main.tf`** file into **`/etc/localstack/init/ready.d`** When LocalStack starts up, it will install the extension, which in turn installs Terraform and [`tflocal`](https://github.com/localstack/terraform-local) into the container. If one of the init stage directories contain a `main.tf` file, the extension will run `tflocal init` and `tflocal apply` on that directory. -##### Example - -main.tf: - ```terraform +# main.tf + resource "aws_s3_bucket" "example" { bucket = "my-tf-test-bucket" @@ -183,7 +184,7 @@ Environment = "Dev" } ``` -Start LocalStack Pro with mounted main.tf: +Start LocalStack Pro with mounted `main.tf`: {{< tabpane >}} {{< tab header="docker-compose.yml" lang="yml" >}} @@ -252,3 +253,5 @@ If you are having issues with your initialization hooks not being executed, plea * If your script does not show up in the list of discovered init scripts, please check your Docker volume mount. Most likely the scripts are not properly mounted into the Docker container. +* Are resources not being created? + * Ensure that AWS [credentials]({{< ref "references/credentials" >}}) are set, e.g. through `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. diff --git a/content/en/references/network-troubleshooting/transparent-endpoint-injection/_index.md b/content/en/references/network-troubleshooting/transparent-endpoint-injection/_index.md index 69b4c35af0..f4bfe17739 100644 --- a/content/en/references/network-troubleshooting/transparent-endpoint-injection/_index.md +++ b/content/en/references/network-troubleshooting/transparent-endpoint-injection/_index.md @@ -14,7 +14,7 @@ In such cases, there are different approaches you can take depending on your set {{< figure src="../images/2.svg" width="400" >}} -If you're using LocalStack with an [auth token]({{}}), then you can utilize the [DNS server]({{}}) to perform requests to LocalStack as if it were AWS. +If you're using LocalStack with an [Auth Token]({{}}), then you can utilize the [DNS server]({{}}) to perform requests to LocalStack as if it were AWS. You need to make two changes: * Publish port 53 from the LocalStack docker container to your host. diff --git a/content/en/references/usage-tracking.md b/content/en/references/usage-tracking.md index e525294463..e76d0ef9a5 100644 --- a/content/en/references/usage-tracking.md +++ b/content/en/references/usage-tracking.md @@ -23,7 +23,7 @@ Collecting basic anonymized usage of AWS services helps us better direct enginee The current usage event collection on the client side includes: - A randomly generated ID pertaining to the session -- The auth token or legacyAPI key (if any) +- The Auth Token or legacy API key (if any) - A randomly generated machine ID is kept throughout the session but deleted once the LocalStack cache directory is removed - The operating system (mostly Linux since LocalStack typically runs in our Debian container) - The LocalStack version being used @@ -88,7 +88,7 @@ For the community image, we only track service, operation, status code, and how ### CLI invocations We collect an anonymized event if a CLI command was invoked, but do not collect any of the parameter values. -This event is not connected to the session or the auth token. +This event is not connected to the session or the Auth Token. Here is an example of a CLI invocation event: diff --git a/content/en/tutorials/lambda-ecr-container-images/index.md b/content/en/tutorials/lambda-ecr-container-images/index.md index 66a1f2da59..1374fe0bbd 100644 --- a/content/en/tutorials/lambda-ecr-container-images/index.md +++ b/content/en/tutorials/lambda-ecr-container-images/index.md @@ -111,7 +111,7 @@ The resulting image will contain your function code and any specified dependenci Now that the initial setup is complete let's explore how to leverage LocalStack's AWS emulation by pushing our image to ECR and deploying the Lambda container image. Start LocalStack by executing the following command. -Make sure to replace `` with your actual auth token: +Make sure to replace `` with your actual Auth Token: {{< command >}} $ LOCALSTACK_AUTH_TOKEN= DEBUG=1 localstack start -d diff --git a/content/en/tutorials/simulating-outages/index.md b/content/en/tutorials/simulating-outages/index.md index c0c280cf3f..46740b4c80 100644 --- a/content/en/tutorials/simulating-outages/index.md +++ b/content/en/tutorials/simulating-outages/index.md @@ -141,7 +141,6 @@ Message sent to queue. If we review the logs, it will show that the `DynamoDbException` has been managed effectively. ```text -2023-11-06T22:21:40.789 DEBUG --- [ asgi_gw_2] l.services.fis.handler : FIS handler called with configs: {'dynamodb': {None: [(100, 'DynamoDbException', '500')]}} 2023-11-06T22:21:40.789 INFO --- [ asgi_gw_2] localstack.request.aws : AWS dynamodb.PutItem => 500 (DynamoDbException) 2023-11-06T22:21:40.834 DEBUG --- [ asgi_gw_4] l.services.sns.publisher : Topic 'arn:aws:sns:us-east-1:000000000000:ProductEventsTopic' publishing '5520d37a-fc21-4a73-b1bf-f9b9afce5908' to subscribed 'arn:aws:sqs:us-east-1:000000000000:ProductEventsQueue' with protocol 'sqs' (subscription 'arn:aws:sns:us-east-1:000000000000:ProductEventsTopic:0a4abf8c-744a-404a-9ff9-f132e25d1b30') diff --git a/content/en/tutorials/using-terraform-with-testcontainers-and-localstack/index.md b/content/en/tutorials/using-terraform-with-testcontainers-and-localstack/index.md index 2ecec7cca5..45c813ef89 100644 --- a/content/en/tutorials/using-terraform-with-testcontainers-and-localstack/index.md +++ b/content/en/tutorials/using-terraform-with-testcontainers-and-localstack/index.md @@ -83,8 +83,8 @@ In the root folder of the demo project run: ```bash $ export LOCALSTACK_AUTH_TOKEN= -$ localstack start -e EXTENSION_AUTO_INSTALL=localstack-extension-terraform-init - -v ./terraform/main.tf:/etc/localstack/init/ready.d/main.tf +$ localstack start -e EXTENSION_AUTO_INSTALL=localstack-extension-terraform-init + -v ./terraform/main.tf:/etc/localstack/init/ready.d/main.tf -v ./target/product-lambda.jar:/etc/localstack/init/ready.d/target/product-lambda.jar ``` @@ -260,7 +260,7 @@ This configuration is abstracted in a superclass to be reusable across different Here's what each configuration line does: - **LAMBDA_REMOVE_CONTAINERS="1"**: Ensures that Lambda containers are removed after execution to free up resources and avoid clutter. - **EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init"**: Automatically installs the Terraform init hooks extension. -- **LOCALSTACK_AUTH_TOKEN**: Fetches the LocalStack auth token from environment variables. +- **LOCALSTACK_AUTH_TOKEN**: Fetches the LocalStack Auth Token from environment variables. - **DEBUG="1"**: Enables verbose logging for troubleshooting and ensuring detailed logs are available for debugging. The `withFileSystemBind` commands mount the `product-lambda.jar` and the directory containing the Terraform files from the host machine into the appropriate init hook directory within the LocalStack container. diff --git a/content/en/user-guide/aws/apigateway/index.md b/content/en/user-guide/aws/apigateway/index.md index e3cb503412..a84e775fec 100644 --- a/content/en/user-guide/aws/apigateway/index.md +++ b/content/en/user-guide/aws/apigateway/index.md @@ -194,14 +194,21 @@ Create a new deployment for the API using the [`CreateDeployment`](https://docs. {{< command >}} $ awslocal apigateway create-deployment \ --rest-api-id \ - --stage-name test + --stage-name dev {{< /command >}} Your API is now ready to be invoked. You can use [curl](https://curl.se/) or any HTTP REST client to invoke the API endpoint: {{< command >}} -$ curl -X GET http://localhost:4566/restapis//test/_user_request_/test +$ curl -X GET http://.execute-api.localhost.localstack.cloud:4566/dev/test + +{"message":"Hello World"} +{{< /command >}} + +You can also use our [alternative URL format]({{< ref "#alternative-url-format" >}}) in case of DNS issues: +{{< command >}} +$ curl -X GET http://localhost:4566/_aws/execute-api//dev/test {"message":"Hello World"} {{< /command >}} @@ -210,9 +217,11 @@ $ curl -X GET http://localhost:4566/restapis//test/_user_request_/t {{< callout >}} -Since [3.8.0](https://blog.localstack.cloud/localstack-release-v-3-8-0/#new-api-gateway-provider), LocalStack supports a new API Gateway implementation for both API Gateway v1 (REST API) and v2 (HTTP API). +Since `4.0`, LocalStack uses a new API Gateway implementation for both API Gateway v1 (REST API) and v2 (HTTP API) by default. + +It was released in [3.8.0](https://blog.localstack.cloud/localstack-release-v-3-8-0/#new-api-gateway-provider). +If you are using LocalStack 4.0 and have been using the new implementation, please remove the [following flag]({{< ref "configuration#api-gateway" >}}) `PROVIDER_OVERRIDE_APIGATEWAY=next_gen` as it is now default. -You can [set the following flag]({{< ref "configuration#api-gateway" >}}) `PROVIDER_OVERRIDE_APIGATEWAY=next_gen` to use the new implementation. {{< /callout >}} We're entirely reworked how REST and HTTP APIs are invoked, to closely match the behavior on AWS. @@ -299,29 +308,29 @@ http://0v1p6q6.execute-api.localhost.localstack.cloud:4566/my/path1 #### Alternative URL format -{{< callout >}} -If you are using the [new API Gateway implementation]({{< ref "#new-api-gateway-implementation" >}}), the `_user_request_` format is deprecated, and you should use the following: +The alternative URL format is an endpoint with the predefined base path `/_aws/execute-api`: ```shell http://localhost:4566/_aws/execute-api/// ``` -This new endpoint more closely resembles the recommended URL format, and allows you to use HTTP APIs with a `$default` stage. -{{< /callout >}} - -The alternative URL format is an endpoint with the predefined path marker `_user_request_`: +For the example above, the URL would be: ```shell -http://localhost:4566/restapis///_user_request_/ +http://localhost:4566/_aws/execute-api/0v1p6q6/local/my/path1 ``` -For the example above, the URL would be: +This format is sometimes used in case of local DNS issues. + +{{< callout >}} + +If you are using LocalStack 4.0, the following `_user_request_` format is deprecated, and you should use the format above. ```shell -http://localhost:4566/restapis/0v1p6q6/local/_user_request_/my/path1 +http://localhost:4566/restapis///_user_request_/ ``` -This format is sometimes used in case of local DNS issues. +{{< / callout >}} ### WebSocket APIs (Pro) diff --git a/content/en/user-guide/aws/bedrock/index.md b/content/en/user-guide/aws/bedrock/index.md index ef642e157c..82f668af2a 100644 --- a/content/en/user-guide/aws/bedrock/index.md +++ b/content/en/user-guide/aws/bedrock/index.md @@ -15,17 +15,28 @@ The supported APIs are available on our [API Coverage Page](https://docs.localst This guide is designed for users new to AWS Bedrock and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. -Start your LocalStack container using your preferred method using the `LOCALSTACK_ENABLE_BEDROCK=1` configuration variable. +Start your LocalStack container using your preferred method with or without pre-warming the Bedrock engine. We will demonstrate how to use Bedrock by following these steps: 1. Listing available foundation models 2. Invoking a model for inference 3. Using the conversation API +4. Using batch processing + +### Pre-warming the Bedrock engine + +The startup of the Bedrock engine can take some time. +Per default, we only start it once you send a request to one of the `bedrock-runtime` APIs. +However, if you want to start the engine when localstack starts to avoid long wait times on your first request you can set the flag `BEDROCK_PREWARM`. ### List available foundation models You can view all available foundation models using the [`ListFoundationModels`](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListFoundationModels.html) API. -This will show you which models are available for use in your local environment. +This will show you which models are available on AWS Bedrock. +{{< callout "note">}} +The actual model that will be used for emulation will differ from the ones defined in this list. +You can define the used model with `DEFAULT_BEDROCK_MODEL` +{{< / callout >}} Run the following command: @@ -36,7 +47,8 @@ $ awslocal bedrock list-foundation-models ### Invoke a model You can use the [`InvokeModel`](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API to send requests to a specific model. -In this example, we'll use the Llama 3 model to process a simple prompt. +In this example, we selected the Llama 3 model to process a simple prompt. +However, the actual model will be defined by the `DEFAULT_BEDROCK_MODEL` environment variable. Run the following command: @@ -73,7 +85,50 @@ $ awslocal bedrock-runtime converse \ }]' {{< / command >}} +### Model Invocation Batch Processing + +Bedrock offers the feature to handle large batches of model invocation requests defined in S3 buckets using the [`CreateModelInvocationJob`](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateModelInvocationJob.html) API. + +First, you need to create a `JSONL` file that contains all your prompts: + +{{< command >}} +$ cat batch_input.jsonl +{"prompt": "Tell me a quick fact about Vienna.", "max_tokens": 50, "temperature": 0.5} +{"prompt": "Tell me a quick fact about Zurich.", "max_tokens": 50, "temperature": 0.5} +{"prompt": "Tell me a quick fact about Las Vegas.", "max_tokens": 50, "temperature": 0.5} +{{< / command >}} + +Then, you need to define buckets for the input as well as the output and upload the file in the input bucket: + +{{< command >}} +$ awslocal s3 mb s3://in-bucket +make_bucket: in-bucket + +$ awslocal s3 cp batch_input.jsonl s3://in-bucket +upload: ./batch_input.jsonl to s3://in-bucket/batch_input.jsonl + +$ awslocal s3 mb s3://out-bucket +make_bucket: out-bucket +{{< / command >}} + +Afterwards you can run the invocation job like this: + +{{< command >}} +$ awslocal bedrock create-model-invocation-job \ + --job-name "my-batch-job" \ + --model-id "mistral.mistral-small-2402-v1:0" \ + --role-arn "arn:aws:iam::123456789012:role/MyBatchInferenceRole" \ + --input-data-config '{"s3InputDataConfig": {"s3Uri": "s3://in-bucket"}}' \ + --output-data-config '{"s3OutputDataConfig": {"s3Uri": "s3://out-bucket"}}' +{ + "jobArn": "arn:aws:bedrock:us-east-1:000000000000:model-invocation-job/12345678" +} +{{< / command >}} + +The results will be at the S3 URL `s3://out-bucket/12345678/batch_input.jsonl.out` + ## Limitations -* LocalStack Bedrock implementation is mock-only and does not run any LLM model locally. +* At this point, we have only tested text-based models in LocalStack. +Other models available with Ollama might also work, but are not officially supported by the Bedrock implementation. * Currently, GPU models are not supported by the LocalStack Bedrock implementation. diff --git a/content/en/user-guide/aws/cloudformation/index.md b/content/en/user-guide/aws/cloudformation/index.md index e384ff90b1..3141cedf94 100644 --- a/content/en/user-guide/aws/cloudformation/index.md +++ b/content/en/user-guide/aws/cloudformation/index.md @@ -6,13 +6,6 @@ persistence: supported with limitations --- -{{< callout >}} -With LocalStack 3.5 we've improved how the internal engine orders resources for deployment and deletion of stacks. -Specifically it now more accurately calculates dependencies between resources and doesn't try to deploy/delete resources which don't have their dependencies available yet. -Should you encounter any issues, please report them on [GitHub](https://github.com/localstack/localstack/issues/new/choose). -You can temporarily revert to the old behavior with `CFN_LEGACY_TEMPLATE_DEPLOYER=1`, but be aware that this is only a temporary option. -{{< /callout >}} - ## Introduction CloudFormation is a service provided by Amazon Web Services (AWS) that allows you to define and provision infrastructure as code. diff --git a/content/en/user-guide/aws/ec2/index.md b/content/en/user-guide/aws/ec2/index.md index 0bdd63cc43..4a55afa32f 100644 --- a/content/en/user-guide/aws/ec2/index.md +++ b/content/en/user-guide/aws/ec2/index.md @@ -261,7 +261,6 @@ $ docker tag ubuntu:focal localstack-ec2/ubuntu-focal-ami:ami-000001 The above example will make LocalStack treat the `ubuntu:focal` Docker image as an AMI with name `ubuntu-focal-ami` and ID `ami-000001`. At startup, LocalStack downloads the following AMIs that can be used to launch Dockerized instances. -- Ubuntu 20.04 `ami-ff0fea8310f3` (deprecated and marked for removal in the next major release) - Ubuntu 22.04 `ami-df5de72bdb3b` - Amazon Linux 2023 `ami-024f768332f0` @@ -468,13 +467,13 @@ This is often labelled as 'Virtualization Technology', 'VT-d' or 'VT-x' in UEFI/ If the Docker host and Libvirt host is the same, the Libvirt socket on the host must be mounted inside the LocalStack container. This can be done by including the volume mounts when the LocalStack container is started. -If you are using the [Docker Compose template]({{< ref "installation#starting-localstack-with-docker-compose" >}}), include the following line in `services.localstack.volumes` list: +If you are using the [Docker Compose template]({{< ref "getting-started/installation#docker-compose" >}}), include the following line in `services.localstack.volumes` list: ```text "/var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock" ``` -If you are using [Docker CLI]({{< ref "installation#starting-localstack-with-docker" >}}), include the following parameter in `docker run`: +If you are using [Docker CLI]({{< ref "getting-started/installation#docker" >}}), include the following parameter in `docker run`: ```text -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock diff --git a/content/en/user-guide/aws/fis/index.md b/content/en/user-guide/aws/fis/index.md index bd1f3dad5c..67c03468b1 100644 --- a/content/en/user-guide/aws/fis/index.md +++ b/content/en/user-guide/aws/fis/index.md @@ -237,27 +237,6 @@ LocalStack FIS currently supports the following actions: If you would like support for more FIS actions, please make a feature request on [GitHub](https://github.com/localstack/localstack/issues/new/choose). {{< /callout >}} -The following actions are deprecated and marked for removal: - -- **`localstack:generic:api-error`**: Raise a custom HTTP error. - This action accepts the following parameters. - Please migrate to the [Chaos API]({{< ref "chaos-api" >}}) which supports this capability and more. - - `region`: The region name where faults will be introduced, e.g. `us-west-1`. - Default: region of the experiment - - `service`: The service name to limit faults to, e.g. `kms`. - Default: all services - - `operation`: The operation name for the specified service to limit faults to, e.g. `ListKeys` - - `percentage`: The percentage of API calls to fail among matching calls. - Default: 100 - - `exception`: The name of the exception to raise for affected API calls. - Default: `InternalError` - - `errorCode`: The HTTP error code to return for impacted API calls. - Default: 500 -- **`localstack:kms:inject-api-internal-error`**: Special case of the previous action which injects an InternalError for KMS operations. -- **`localstack:log-debug`**: Prints a debug message in the LocalStack logs when experiment is started and stopped. -- **`localstack:generic:latency`**: Introduces a latency in the network call. - Please migrate to the [Chaos API]({{< ref "chaos-api" >}}). - ## Current Limitations - LocalStack does not implement the [selection mode](https://docs.aws.amazon.com/fis/latest/userguide/targets.html#target-selection-mode) mechanism available on AWS. diff --git a/content/en/user-guide/aws/lambda/index.md b/content/en/user-guide/aws/lambda/index.md index 2bd058afd7..fd8e1cd60e 100644 --- a/content/en/user-guide/aws/lambda/index.md +++ b/content/en/user-guide/aws/lambda/index.md @@ -167,11 +167,6 @@ Since [3.4.0](https://discuss.localstack.cloud/t/localstack-release-v3-4-0/871#n You can [configure]({{< ref "configuration" >}}) `EVENT_RULE_ENGINE=java` (preview) to use the AWS [event-ruler](https://github.com/aws/event-ruler), which offers better parity. {{< /callout >}} -{{< callout >}} -Since [3.7.0](https://blog.localstack.cloud/2024-08-29-localstack-release-v-3-7-0/#new-lambda-event-source-mapping-implementation), LocalStack supports a Event Source Mapping (ESM) implementation. -You can [configure]({{< ref "configuration" >}}) `LAMBDA_EVENT_SOURCE_MAPPING=v2` (preview) to use the new ESM implementation. -{{< /callout >}} - [Lambda event source mappings](https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventsourcemapping.html) allows you to connect Lambda functions to other AWS services. The following event sources are supported in LocalStack: @@ -180,31 +175,18 @@ The following event sources are supported in LocalStack: - [Managed Streaming for Apache Kafka (MSK)](https://docs.aws.amazon.com/lambda/latest/dg/with-msk.html) - [Simple Queue Service (SQS)](https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html) -### New Lambda Event Source Mapping implementation - -Since v3.8, LocalStack uses a new default implementation for [Lambda Event Source Mapping](https://docs.aws.amazon.com/lambda/latest/dg/invocation-eventsourcemapping.html) (ESM) with improved reliability, performance, and AWS parity. -The new ESM v2 implementation is also compatible with the Java-based event pattern rule engine (`EVENT_RULE_ENGINE=java`) for better event filtering. - -The improvements over ESM v1 include: -- Improved reliability through internal retries and separation of concern such that single exceptions or timeouts don't affect other event source mappings. -- Improved performance by enabling concurrent event source mappings rather than having a single thread handling everything. -- Improved AWS parity, related to events filtering, configuring failure destinations, (partial) batch failure handling, and SQS, Kinesis, & DynamoDB Streams events polling. -- Improved Kafka support for Amazon MSK and Self-Managed Kafka. - -Create a [GitHub issue](https://github.com/localstack/localstack/issues/new/choose) or reach out to [LocalStack support](https://docs.localstack.cloud/getting-started/help-and-support/) if you experience any challenges. -You can temporarily switch back to the old implementation using the configuration `LAMBDA_EVENT_SOURCE_MAPPING=v1`. -The old implementation won't be available in the next major release. - The limitations compared to AWS include: - Lambda Success Destinations are not supported. -- Only very basic validations are performed upon creating and updating ESM. -- Streaming Pollers for Kinesis and DynamoDB do not implement features like: +- Only basic validations are performed upon creating and updating ESM. +- Streaming Pollers for Kinesis and DynamoDB do not implement the following batching behavior configurations: - `BisectBatchOnFunctionError` - `MaximumBatchingWindowInSeconds` - `ParallelizationFactor` - `ScalingConfig` - `TumblingWindowInSeconds`. +Create a [GitHub issue](https://github.com/localstack/localstack/issues/new/choose) or reach out to [LocalStack support](https://docs.localstack.cloud/getting-started/help-and-support/) if you experience any challenges. + ## Lambda Layers (Pro) [Lambda layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html) let you include additional code and dependencies in your Lambda functions. diff --git a/content/en/user-guide/aws/pipes/index.md b/content/en/user-guide/aws/pipes/index.md index 70fa43d01e..0270c8776b 100644 --- a/content/en/user-guide/aws/pipes/index.md +++ b/content/en/user-guide/aws/pipes/index.md @@ -129,6 +129,21 @@ $ awslocal sqs receive-message \ --queue-url http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/target-queue {{< /command >}} +## Resource Browser + +The LocalStack Web Application provides a Resource Browser for managing EventBridge Pipes. +You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the **Resource Browser** section, and then clicking on **EventBridge Pipes** under the **App Integration** section. + +EventBridge Pipes Resource Browser +
+
+ +The Resource Browser for EventBridge Pipes in LocalStack allows you to perform the following actions: + +1. **Create a Pipe**: Click on the **Create Pipe** button to set up a new pipe with a source and target service, filter criteria, and more. +2. **View Pipe Details**: Click on the pipe name to view detailed information, including source, target, batch size, state, and more. +3. **Delete a Pipe**: Select a pipe and click on the **Actions** dropdown menu, followed by **Remove Selected**, to delete the pipe. + ## Supported sources LocalStack supports the following [sources](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes-event-source.html) for Pipes: diff --git a/content/en/user-guide/aws/pipes/pipes-resource-browser.png b/content/en/user-guide/aws/pipes/pipes-resource-browser.png new file mode 100644 index 0000000000..4cb95e5455 Binary files /dev/null and b/content/en/user-guide/aws/pipes/pipes-resource-browser.png differ diff --git a/content/en/user-guide/aws/rds/index.md b/content/en/user-guide/aws/rds/index.md index 0e4ee51b0f..c8a95ff06b 100644 --- a/content/en/user-guide/aws/rds/index.md +++ b/content/en/user-guide/aws/rds/index.md @@ -171,7 +171,7 @@ For instance, the `storage-encrypted` flag is returned as configured, but active ### PostgreSQL Engine When you establish an RDS DB cluster or instance using the `postgres`/`aurora-postgresql` DB engine along with a specified `EngineVersion`, LocalStack will dynamically install and configure the corresponding PostgreSQL version as required. -Presently, you have the option to choose major versions ranging from 10 to 15. +Presently, you have the option to choose major versions ranging from 11 to 15. If you select a major version beyond this range, the system will automatically default to version 11. It's important to note that the selection of minor versions is not available. diff --git a/content/en/user-guide/chaos-engineering/fault-injection-service/index.md b/content/en/user-guide/chaos-engineering/fault-injection-service/index.md index 47881246bc..3796a79e9f 100644 --- a/content/en/user-guide/chaos-engineering/fault-injection-service/index.md +++ b/content/en/user-guide/chaos-engineering/fault-injection-service/index.md @@ -7,142 +7,21 @@ aliases: - /tutorials/fault-injection-service-experiments/ --- -## Introduction - -The [Fault Injection Service](https://aws.amazon.com/fis/) is a fully managed service by AWS designed to help you improve the resilience of your applications by simulating real-world outages and operational issues. +The [Fault Injection Service (FIS)](https://aws.amazon.com/fis/) is a fully managed service by AWS designed to help you improve the resilience of your applications by simulating real-world outages and operational issues. This service allows you to conduct controlled experiments on your AWS infrastructure, injecting faults and observing how your system responds under various conditions. By using the Fault Injection Service, you can identify weaknesses, test recovery procedures, and ensure that your applications can withstand unexpected disruptions. This proactive approach to reliability engineering enables you to enhance system robustness, minimize downtime, and maintain a high level of service availability for your users. -To see the FIS in action within a more complex application stack, please refer to the [Chaos Engineering Tutorials]({{< ref "tutorials" >}}). - {{< alert title="Note">}} Fault Injection Service emulation is available as part of the LocalStack Enterprise plan. If you'd like to try it out, please [contact us](https://www.localstack.cloud/demo) to request access. {{< /alert >}} -## Prerequisites - -The prerequisites for this guide are: - -- LocalStack Pro with [LocalStack CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli) & [LocalStack Auth Token](https://docs.localstack.cloud/getting-started/auth-token/) -- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) -- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) - -Ensure that you set the Auth Token as an environment variable before beginning: - -{{< command >}} -$ LOCALSTACK_AUTH_TOKEN= -$ localstack start -{{< /command >}} - -## Getting Started - {{< callout "tip" >}} -For more information on LocalStack FIS, please refer to the [FIS service docs]({{< ref "user-guide/aws/fis" >}}). +For more information, please refer to the [FIS service docs]({{< ref "user-guide/aws/fis" >}}). {{< /callout >}} -This guide is created with users who are new to FIS in mind, and assumes basic knowledge of the AWS CLI and our `awslocal` wrapper script. - -The following demo will depict constructing various FIS experiments designed to trigger different types of failures in a DynamoDB service. - -Let's create a simple DynamoDB table called `Students` in the `us-east-1` region. - -{{< command >}} -$ awslocal dynamodb create-table \ - --table-name Students \ - --attribute-definitions AttributeName=id,AttributeType=S \ - --key-schema AttributeName=id,KeyType=HASH \ - --billing-mode PAY_PER_REQUEST \ - --region us-east-1 - -{ - "TableDescription": { - "AttributeDefinitions": [ - { - "AttributeName": "id", - "AttributeType": "S" - } - ], - "TableName": "Students", - "KeySchema": [ - { - "AttributeName": "id", - "KeyType": "HASH" - } - ], - "TableStatus": "ACTIVE", - "CreationDateTime": 1710945576.193, - "ProvisionedThroughput": { - "LastIncreaseDateTime": 0.0, - "LastDecreaseDateTime": 0.0, - "NumberOfDecreasesToday": 0, - "ReadCapacityUnits": 0, - "WriteCapacityUnits": 0 - }, - "TableSizeBytes": 0, - "ItemCount": 0, - "TableArn": "arn:aws:dynamodb:us-east-1:000000000000:table/Students", - "TableId": "c9ae13b6-ecf1-42f2-8d69-0e14d65a4dc3", - "BillingModeSummary": { - "BillingMode": "PAY_PER_REQUEST", - "LastUpdateToPayPerRequestDateTime": 1710945576.193 - } - } -} - -{{< /command >}} - -The newly created table has two items added: - -{{< command >}} -$ awslocal dynamodb put-item --table-name Students --region us-east-1 --item '{ - "id": {"S": "1216"}, - "first name": {"S": "Liam"}, - "last name": {"S": "Davis"}, - "year": {"S": "Junior"}, - "enrolment date": {"S": "2023-03-19"} - }' - -$ awslocal dynamodb put-item --table-name Students --region us-east-1 --item '{ - "id": {"S": "1748"}, - "first name": {"S": "John"}, - "last name": {"S": "Doe"}, - "year": {"S": "Senior"}, - "enrolment date": {"S": "2022-03-19"} - }' -{{< /command >}} - -And then we can look up one of the students by ID, also using the awslocal CLI: - -{{< command >}} -$ awslocal dynamodb get-item --table-name Students --key '{"id": {"S": "1216"}}' - -{ - "Item": { - "id": { - "S": "1216" - }, - "last name": { - "S": "Davis" - }, - "enrolment date": { - "S": "2023-03-19" - }, - "first name": { - "S": "Liam" - }, - "year": { - "S": "Junior" - } - } -} - -{{< /command >}} - -## Key concepts of FIS - Some of the most important concepts associated with a FIS experiment are: **1. @@ -168,492 +47,3 @@ These are necessary for AWS FIS to perform actions on your behalf, like injectin **6. Experiment Execution**: When you start an experiment, AWS FIS executes the actions defined in the experiment template against the specified targets, adhering to any defined stop conditions. The execution process is logged, and detailed information about the experiment's progress and outcome is provided. - -## Examples - -### Service Unavailability - -{{< callout "warning" >}} -The `localstack:generic:api-error` action is deprecated and marked for removal. -Please use the [Chaos API]({{< ref "chaos-api" >}}) to achieve the same effect. -{{< /callout >}} - -In a file called `dynamodb-experiment.json` let's define a FIS experiment that causes all calls to the `GetItem` API of the DynamoDB service to return a 503 `Service Unavailable` response. -This failure will happen 100% of the times the method is called. - -```json -{ - "actions": { - "Test disruption": { - "actionId": "localstack:generic:api-error", - "parameters": { - "service": "dynamodb", - "operation": "GetItem", - "percentage": "100", - "exception": "Service Unavailable", - "errorCode": "503" - } - } - }, - "description": "Template for interfering with the DynamoDB service", - "stopConditions": [{ - "source": "none" - }], - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" -} -``` - -And create the experiment: - -{{< command >}} -$ awslocal fis create-experiment-template --cli-input-json file://dynamodb-experiment.json - -{ - "experimentTemplate": { - "id": "547ec5c3-5ca1-4227-9b9d-a737223d1d42", - "description": "Template for interfering with the DynamoDB service", - "actions": { - "Test disruption": { - "actionId": "localstack:generic:api-error", - "parameters": { - "service": "dynamodb", - "operation": "GetItem", - "percentage": "100", - "exception": "DynamoDbException", - "errorCode": "500" - } - } - }, - "stopConditions": [ - { - "source": "none" - } - ], - "creationTime": 1710948862.04738, - "lastUpdateTime": 1710948862.04738, - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" - } -} - -{{}} - -The experiment needs to be started in order to be running: - -{{< command >}} -$ awslocal fis start-experiment --experiment-template-id 547ec5c3-5ca1-4227-9b9d-a737223d1d42 - -{ - "experiment": { - "id": "1a01327a-79d5-4202-8132-e56e55c9391b", - "experimentTemplateId": "547ec5c3-5ca1-4227-9b9d-a737223d1d42", - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole", - "state": { - "status": "running" - }, - "actions": { - "Test disruption": { - "actionId": "localstack:generic:api-error", - "parameters": { - "service": "dynamodb", - "operation": "GetItem", - "percentage": "100", - "exception": "DynamoDbException", - "errorCode": "500" - } - } - }, - "stopConditions": [ - { - "source": "none" - } - ], - "creationTime": 1710949720.491161, - "startTime": 1710949720.491161 - } -} - -{{}} - -The LocalStack logs are confirming the experiment related activity: - -```bash -2024-03-20T15:34:22.048 INFO --- [ asgi_gw_0] localstack.request.aws : AWS fis.CreateExperimentTemplate => 200 -2024-03-20T15:48:40.492 INFO --- [ asgi_gw_0] localstack.request.aws : AWS fis.StartExperiment => 200 -``` - -Let's see it in action: - -{{< command >}} -$ awslocal dynamodb get-item --table-name Students --key '{"id": {"S": "1216"}}' - -An error occurred (DynamoDbException) when calling the GetItem operation (reached max retries: 9): Failing as per Fault Injection Simulator configuration - -{{}} - -The logs now show several attempts of performing the `GetItem` operation, before returning the error message: - -```text -2024-03-20T15:54:16.630 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:16.707 INFO --- [ asgi_gw_1] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:16.825 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:17.040 INFO --- [ asgi_gw_1] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:17.476 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:18.301 INFO --- [ asgi_gw_1] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:19.925 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:23.141 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:29.559 INFO --- [ asgi_gw_1] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -2024-03-20T15:54:42.381 INFO --- [ asgi_gw_1] localstack.request.aws : AWS dynamodb.GetItem => 500 (DynamoDbException) -``` - -However, the `PutItem` and other operations are still working as expected: - -{{< command >}} -$ awslocal dynamodb put-item --table-name Students --region us-east-1 --item '{ - "id": {"S": "9865"}, - "first name": {"S": "Jenny"}, - "last name": {"S": "Jones"}, - "year": {"S": "Sophomore"}, - "enrolment date": {"S": "2021-03-19"} - }' - -2024-03-20T16:00:27.958 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.PutItem => 200 - -{{< /command >}} - -Finally, the experiment can be stopped using the experiment's ID with the following command: - -```bash -awslocal fis stop-experiment --id 1a01327a-79d5-4202-8132-e56e55c9391b -``` - -### Region Unavailability - -{{< callout "warning" >}} -The `localstack:generic:api-error` action is deprecated and marked for removal. -Please use the [Chaos API]({{< ref "chaos-api" >}}) to achieve the same effect. -{{< /callout >}} - -This sort of experiment involves disabling entire regions to simulate regional outages and failovers. -Let's see what that would look like, in a separate file, `regional-experiment.json`: - -```json -{ - "actions": { - "regionUnavailable-us-east-1": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-east-1", - "errorCode": "503" - } - }, - "regionUnavailable-us-west-2": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-west-2", - "errorCode": "503" - } - } - }, - "description": "Template for internal server error for regions us-west-2, us-east-1", - "stopConditions": [{ - "source": "none" - }], - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" -} -``` - -This template defines actions to simulate internal server errors (HTTP 503) in both `us-east-1` and `us-west-2` regions, without specific stop conditions. -These outages will affect all the resources within the regions. - -The experiment is created and started: - -{{< command >}} -$ awslocal fis create-experiment-template --cli-input-json file://regional-experiment.json - -{ - "experimentTemplate": { - "id": "19bec43e-9cb4-4bb8-9509-bf71c6e313c4", - "description": "Template for internal server error for regions us-west-2, us-east-1", - "actions": { - "regionUnavailable-us-east-1": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-east-1", - "errorCode": "503" - } - }, - "regionUnavailable-us-west-2": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-west-2", - "errorCode": "503" - } - } - }, - "stopConditions": [ - { - "source": "none" - } - ], - "creationTime": 1710951319.333033, - "lastUpdateTime": 1710951319.333033, - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" - } -} - -{{< /command >}} - -{{< command >}} -$ awslocal fis start-experiment --experiment-template-id 19bec43e-9cb4-4bb8-9509-bf71c6e313c4 - -{ - "experiment": { - "id": "1a650841-bc81-4b4b-9317-6ec52df51c1d", - "experimentTemplateId": "19bec43e-9cb4-4bb8-9509-bf71c6e313c4", - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole", - "state": { - "status": "running" - }, - "actions": { - "regionUnavailable-us-east-1": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-east-1", - "errorCode": "503" - } - }, - "regionUnavailable-us-west-2": { - "actionId": "localstack:generic:api-error", - "parameters": { - "region": "us-west-2", - "errorCode": "503" - } - } - }, - "stopConditions": [ - { - "source": "none" - } - ], - "creationTime": 1710951725.475228, - "startTime": 1710951725.475228 - } -} - -{{< /command >}} - -The previously created table in the `us-east-1` region, is not reachable, but this time a different error is thrown, the one that we defined in the latest experiment template: - -{{< command >}} -$ awslocal dynamodb get-item --table-name Students --region us-east-1 --key '{"id": {"S": "1216"}}' - -An error occurred (InternalError) when calling the GetItem operation (reached max retries: 9): Failing as per Fault Injection Simulator configuration - -{{< /command >}} - -However, the `eu-central-1` region is unaffected, and a new table can be created and used in that area. - -{{< command >}} -$ awslocal dynamodb create-table \ - --table-name Students \ - --attribute-definitions AttributeName=id,AttributeType=S \ - --key-schema AttributeName=id,KeyType=HASH \ - --billing-mode PAY_PER_REQUEST \ - --region eu-central-1 - -{ - "TableDescription": { - "AttributeDefinitions": [ - { - "AttributeName": "id", - "AttributeType": "S" - } - ], - "TableName": "Students", - "KeySchema": [ - { - "AttributeName": "id", - "KeyType": "HASH" - } - ], - "TableStatus": "ACTIVE", - "CreationDateTime": 1710952212.617, - "ProvisionedThroughput": { - "LastIncreaseDateTime": 0.0, - "LastDecreaseDateTime": 0.0, - "NumberOfDecreasesToday": 0, - "ReadCapacityUnits": 0, - "WriteCapacityUnits": 0 - }, - "TableSizeBytes": 0, - "ItemCount": 0, - "TableArn": "arn:aws:dynamodb:eu-central-1:000000000000:table/Students", - "TableId": "917f7df1-0050-433a-8647-427f072e7409", - "BillingModeSummary": { - "BillingMode": "PAY_PER_REQUEST", - "LastUpdateToPayPerRequestDateTime": 1710952212.617 - } - } -} - -{{< /command >}} - -```bash -awslocal dynamodb put-item --table-name Students --region eu-central-1 --item '{ - "id": {"S": "1111"}, - "first name": {"S": "Alice"}, - "last name": {"S": "Simpson"}, - "year": {"S": "Freshman"}, - "enrolment date": {"S": "2020-03-19"} - }' - -2024-03-20T16:34:57.164 INFO --- [ asgi_gw_0] localstack.request.aws : AWS dynamodb.PutItem => 200 -``` - -Just as with the earlier experiment, this one should be stopped by running the following command: - -```bash -awslocal fis stop-experiment --id e49283c1-c2e0-492b-b69f-9fbd710bc1e3 -``` - -### Service Latency - -{{< callout "warning" >}} -The `localstack:generic:latency` action is deprecated and marked for removal. -Please use the [Chaos API]({{< ref "chaos-api" >}}) to achieve the same effect. -{{< /callout >}} - -Let's now add some latency to our DynamoDB API calls. -First the definition of a new experiment template in another file, `latency-experiment.json`: - -```json -{ - "actions": { - "latency": { - "actionId": "localstack:generic:latency", - "parameters": { - "region": "us-east-1", - "latencyMilliseconds": 5000 - } - } - }, - "description": "template for testing delays in DynamoDB API calls", - "stopConditions": [], - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" -} -``` - -After saving the file, we can create and start the experiment: - -{{< command >}} -$ awslocal fis create-experiment-template --cli-input-json file://latency-experiment.json - -{ - "experimentTemplate": { - "id": "1f6e0ce8-57ed-4987-a7e5-b85ba3f5b933", - "description": "template for testing delays in DynamoDB API calls", - "actions": { - "latency": { - "actionId": "localstack:generic:latency", - "parameters": { - "service": "dynamodb", - "region": "us-east-1", - "latencyMilliseconds": "5000" - } - } - }, - "stopConditions": [], - "creationTime": 1711024346.972359, - "lastUpdateTime": 1711024346.972359, - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole" - } -} - -{{< /command >}} - -{{< command >}} -$ awslocal fis start-experiment --experiment-template-id 1f6e0ce8-57ed-4987-a7e5-b85ba3f5b933 - -{ - "experiment": { - "id": "dd598567-56e6-4d00-9ef5-15c7e90e7851", - "experimentTemplateId": "1f6e0ce8-57ed-4987-a7e5-b85ba3f5b933", - "roleArn": "arn:aws:iam:000000000000:role/ExperimentRole", - "state": { - "status": "running" - }, - "actions": { - "latency": { - "actionId": "localstack:generic:latency", - "parameters": { - "service": "dynamodb", - "region": "us-east-1", - "latencyMilliseconds": "5000" - } - } - }, - "stopConditions": [], - "creationTime": 1711024425.844646, - "startTime": 1711024425.844646 - } -} - -{{< /command >}} - -This FIS experiment introduces a delay of 5 seconds to all DynamoDB API calls within the `us-east-1` region. -Tables located in the `eu-central-1` region, or any other service, remain unaffected. -To extend the latency effect to a regional level, the specific service constraint can be omitted, thereby applying the latency to all resources within the selected region. - -As always, remember to stop your experiment, so it does not cause unexpected issues down the line: - -```bash -awslocal fis stop-experiment --id dd598567-56e6-4d00-9ef5-15c7e90e7851 -``` - -Remember to replace the IDs with your own corresponding values. - -### Experiment overview - -If you want to keep track of all your experiments and make sure nothing is running in the background to hinder any other work, you can get an overview by using the command: - -{{< command >}} -$ awslocal fis list-experiments - -{ - "experiments": [ - { - "id": "1a01327a-79d5-4202-8132-e56e55c9391b", - "experimentTemplateId": "547ec5c3-5ca1-4227-9b9d-a737223d1d42", - "state": { - "status": "stopped" - }, - "creationTime": 1710949720.491161 - }, - { - "id": "1a650841-bc81-4b4b-9317-6ec52df51c1d", - "experimentTemplateId": "19bec43e-9cb4-4bb8-9509-bf71c6e313c4", - "state": { - "status": "stopped" - }, - "creationTime": 1710951725.475228 - }, - { - "id": "e49283c1-c2e0-492b-b69f-9fbd710bc1e3", - "experimentTemplateId": "19bec43e-9cb4-4bb8-9509-bf71c6e313c4", - "state": { - "status": "stopped" - }, - "creationTime": 1710951872.250418 - }, - { - "id": "dd598567-56e6-4d00-9ef5-15c7e90e7851", - "experimentTemplateId": "1f6e0ce8-57ed-4987-a7e5-b85ba3f5b933", - "state": { - "status": "running" - }, - "creationTime": 1711024425.844646 - } - ] -} - -{{< /command >}} diff --git a/content/en/user-guide/chaos-engineering/outages-extension/index.md b/content/en/user-guide/chaos-engineering/outages-extension/index.md deleted file mode 100644 index 6f2c572b52..0000000000 --- a/content/en/user-guide/chaos-engineering/outages-extension/index.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Outages Extension" -linkTitle: "Outages Extension" -description: Use LocalStack Outages Extension to mimic service outages by testing your infrastructure's ability to deploy robustly and recover from unexpected events. -tags: ["Enterprise plan"] ---- - -## Introduction - -{{< callout "warning" >}} -Outages Extension has been deprecated. -It is recommended to migrate to the [Chaos API]({{< ref "chaos-api" >}}). -{{< /callout >}} - -The [LocalStack Outages Extension](https://pypi.org/project/localstack-extension-outages/) allows you to mimic outages across any AWS region or service. -By integrating the Outages Extension using the [LocalStack Extension mechanism](https://docs.localstack.cloud/user-guide/extensions/), you can assess -your infrastructure's robustness. -Intentionally triggering service outages and monitoring the system's response in situations -where the infrastructure is compromised offers a powerful way to test. -This strategy helps gauge the effectiveness of the system's -deployment procedures and its resilience against infrastructure disruptions, which is a key element of chaos engineering. - -### Prerequisites - -The general prerequisites for this guide are: - -- LocalStack Pro with [LocalStack CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli) & [LocalStack Auth Token](https://docs.localstack.cloud/getting-started/auth-token/) -- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) -- [Python](https://www.python.org/downloads/) - -### Installing the extension - -To install the LocalStack Outages Extension, first set up your LocalStack Auth Token in your environment. -Once the token is configured, use the command below to install the extension: - -{{< command >}} -$ localstack auth set-token -$ localstack extensions install localstack-extension-outages -{{< /command >}} - -Alternatively, you can enable automatic installation of the extension by setting the environment variable `EXTENSION_AUTO_INSTALL=localstack-extension-outages` when you start the LocalStack container. - -Follow our [Managing Extensions documentation](https://docs.localstack.cloud/user-guide/extensions/managing-extensions/) for more information on how to install & manage extensions. - -### Configuration - -The extension is set up through an API endpoint, where the setup involves specifying a set of rules that are applied in order. -Each rule includes two key pieces of information: the service name and its region. -You have the option to use the `*` wildcard -for flexibility in either attribute. - -To initiate an outage for specific service/region combinations, you can make a POST request as described below: - -{{< command >}} -curl --location --request POST 'http://outages.localhost.localstack.cloud:4566/outages' \ ---header 'Content-Type: application/json' \ ---data ' -[ - { - "service": "kms", - "region": "us-east-1" - }, - { - "service": "s3", - "region": "us-*" - }, - { - "service": "lambda", - "region": "*" - } -]' -{{< /command >}} - -Once activated, any API requests to the impacted services and regions will result in an HTTP 503 Service Unavailable error. - -In the given example, the services and regions affected include: - -- KMS in us-east-1 -- S3 in all US regions, including us-east-1, us-east-2, us-west-1, us-west-2, us-gov-east-1, and us-gov-west-1 -- Lambda across all regions - -To demonstrate this works as expected, we can try to create an S3 bucket in a US-based region: - -{{< command >}} -$ awslocal s3 mb s3://test-bucket --region us-east-1 - -make_bucket failed: s3://test-bucket An error occurred (ServiceUnavailableException) when calling the CreateBucket operation (reached max retries: 4): Service 's3' not accessible in 'us-east-1' region due to an outage - -{{< /command >}} - -However, the same command executed for `eu-central-1` is unaffected: - -{{< command >}} -$ awslocal s3 mb s3://test-bucket --region eu-central-1 - -make_bucket: test-bucket - -{{< /command >}} - -Outages may be stopped by using empty list in the configuration. -The following request will clear the current configuration: - -{{< command >}} -curl --location --request POST 'http://outages.localhost.localstack.cloud:4566/outages' \ ---header 'Content-Type: application/json' \ ---data '[]' -{{< /command >}} - -To retrieve the current configuration, make the following GET call: - -{{< command >}} -curl --location --request GET 'http://outages.localhost.localstack.cloud:4566/outages' -{{}} - -To add a new service/region rule pair to the configuration, make a PATCH call as follows: - -{{< command >}} -curl --location --request PATCH 'http://outages.localhost.localstack.cloud:4566/outages' \ ---header 'Content-Type: application/json' \ ---data '[{"service": "transcribe", "region": "us-west-1"}]' -{{}} - -To remove a service/region rule pair from the configuration, make a DELETE call as follows: - -{{< command >}} -curl --location --request DELETE 'http://outages.localhost.localstack.cloud:4566/outages' \ ---header 'Content-Type: application/json' \ ---data '[{"service": "transcribe", "region": "us-west-1"}]' -{{}} diff --git a/content/en/user-guide/ci/_index.md b/content/en/user-guide/ci/_index.md index fd382d6964..982a3e9e60 100644 --- a/content/en/user-guide/ci/_index.md +++ b/content/en/user-guide/ci/_index.md @@ -31,14 +31,14 @@ You can also pre-seed state into the local AWS services (e.g., DynamoDB entries After a successful test run, you can execute the more expensive AWS CodeBuild pipeline for deploying your application. You can enrich the test reports created by your testing framework with traces and analytics generated inside LocalStack. -## CI integrations - -The steps required for the integration differ slightly depending on your preferred CI platform. -Please refer to the relevant sections of the [CI keys settings page](https://app.localstack.cloud/workspace/ci-keys) in the [LocalStack Web app](https://app.localstack.cloud). - ## CI images -LocalStack Docker images can be used in your CI environment by adding a CI Key. +LocalStack Docker images can be used in your CI environment by adding a [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens). The images are available on [Docker Hub](https://hub.docker.com/r/localstack/localstack/tags), and comprehensive documentation is available on our [Docker images](https://docs.localstack.cloud/references/docker-images/) documentation. Community users can use the `localstack/localstack` image, while licensed users can use the `localstack/localstack-pro` image. For Big Data jobs that require services such as EMR, Athena, and Glue, we provide a mono-container that uses the `localstack/localstack-pro:2.0.2-bigdata` image, which bakes in the required dependencies, such as Hadoop, Hive, Presto, into the LocalStack image. + +## CI integrations + +The steps required for the integration differ slightly depending on your preferred CI provider. +Please refer to the relevant documentation below to configure LocalStack for your CI pipelines. diff --git a/content/en/user-guide/ci/bitbucket/index.md b/content/en/user-guide/ci/bitbucket/index.md index fa27546a49..c453d1fde0 100644 --- a/content/en/user-guide/ci/bitbucket/index.md +++ b/content/en/user-guide/ci/bitbucket/index.md @@ -53,18 +53,19 @@ pipelines: - awslocal s3 ls ``` -## Configuring a CI key +## Configuring a CI Auth Token -You can enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your CI key to the project's environment variables. +You can enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your CI Auth Token to the project's environment variables. The LocalStack container will automatically pick it up and activate the Pro features. -To add a CI key to your BitBucket Pipeline: +Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. +To add a CI Auth Token to your BitBucket Pipeline: - Select a workspace from the BitBucket dashboard. - Select the **Settings** on the top navigation bar. - Select **Workspace settings** from the **Settings dropdown** menu. -- On left-hand menu, navigate to **Pipelines** and click on **Workspace variables**. -- Add a new variable with the name `LOCALSTACK_API_KEY` and the value of your CI key. +- On the left-hand menu, navigate to **Pipelines** and click on **Workspace variables**. +- Add a new variable with the name `LOCALSTACK_AUTH_TOKEN` and the value of your CI Auth Token. Navigate to your BitBucket Pipeline and add the following lines to the `bitbucket-pipelines.yaml` file: diff --git a/content/en/user-guide/ci/circle-ci/circleci-env-config.png b/content/en/user-guide/ci/circle-ci/circleci-env-config.png deleted file mode 100644 index d5b975059b..0000000000 Binary files a/content/en/user-guide/ci/circle-ci/circleci-env-config.png and /dev/null differ diff --git a/content/en/user-guide/ci/circle-ci/index.md b/content/en/user-guide/ci/circle-ci/index.md index 871e22ee43..1200bbe758 100644 --- a/content/en/user-guide/ci/circle-ci/index.md +++ b/content/en/user-guide/ci/circle-ci/index.md @@ -88,21 +88,19 @@ jobs: ... ``` -### Configuring a CI key +### Configuring a CI Auth Token -To enable LocalStack Pro+, you need to add your LocalStack CI key to the project's environment variables. +To enable LocalStack Pro+, you need to add your LocalStack CI Auth Token to the project's environment variables. The LocalStack container will automatically pick it up and activate the licensed features. -Go to the [CI Key Page](https://app.localstack.cloud/workspace/ci-keys) page and copy your CI key. -To add the CI key to your CircleCI project, follow these steps: +Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. +To add the CI Auth Token to your CircleCI project, follow these steps: - Click on **Project Settings**. - Select **Environment Variables** from the left side menu. - Click **Add Environment Variable**. -- Name your environment variable `LOCALSTACK_API_KEY`. -- Paste your CI key into the input field. - -Adding the LocalStack CI key in CircleCI +- Name your environment variable `LOCALSTACK_AUTH_TOKEN`. +- Paste your CI Auth Token into the input field. After the above steps, just start up LocalStack using our official orb as usual. @@ -127,7 +125,7 @@ jobs: ### Store LocalStack state You can preserve your AWS infrastructure with LocalStack in various ways. -To be able to use any of the below samples, you must [set a valid CI key](#configuring-a-ci-key). +To be able to use any of the below samples, you must [set a valid CI Auth Token](#configuring-a-ci-auth-token). _Note: For best result we recommend to use a combination of the below techniques and you should familiarise yourself with CircleCI's data persistance approach, see their [official documentation](https://circleci.com/docs/persist-data/)._ diff --git a/content/en/user-guide/ci/codebuild/index.md b/content/en/user-guide/ci/codebuild/index.md index 1c4b228ea8..d4ddecc05b 100644 --- a/content/en/user-guide/ci/codebuild/index.md +++ b/content/en/user-guide/ci/codebuild/index.md @@ -88,17 +88,17 @@ phases: ... ``` -### Configuring a CI key +### Configuring a CI Auth Token -To enable LocalStack Pro features, you need to add your LocalStack CI API key to the project's environment variables. +To enable LocalStack Pro features, you need to add your LocalStack CI Auth Token to the project's environment variables. The LocalStack container will automatically pick it up and activate the licensed features. -Go to the [CI Key Page](https://app.localstack.cloud/workspace/ci-keys) page and copy your CI key. -To add the CI key to your CodeBuild project, follow these steps: +Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. +To add the CI Auth Token to your CodeBuild project, follow these steps: - Navigate to your project dashboard, click **Edit** to open the dropdown, and select **Environment**. - Click on **Additional configuration** and navigate to the **Environment variables** section. -- Specify **Name** as `LOCALSTACK_API_KEY` and **Value** as your CI key. +- Specify **Name** as `LOCALSTACK_AUTH_TOKEN` and **Value** as your CI Auth Token. Specify **Type** as per your requirement. Click on **Update environment** to save your environment variables. diff --git a/content/en/user-guide/ci/github-actions/github-create-secret.png b/content/en/user-guide/ci/github-actions/github-create-secret.png deleted file mode 100644 index aedbf5f76c..0000000000 Binary files a/content/en/user-guide/ci/github-actions/github-create-secret.png and /dev/null differ diff --git a/content/en/user-guide/ci/github-actions/index.md b/content/en/user-guide/ci/github-actions/index.md index e857fc3e9e..8c5262065a 100644 --- a/content/en/user-guide/ci/github-actions/index.md +++ b/content/en/user-guide/ci/github-actions/index.md @@ -36,33 +36,29 @@ For example, to set the `DEBUG` configuration option, you can use the following You can add extra configuration options by separating them with a comma. -### Configure a CI key +### Configure a CI Auth Token -To enable LocalStack Pro+, you need to add your LocalStack CI API key to the project's environment variables. +To enable LocalStack Pro, you need to add your LocalStack CI Auth Token to the project's environment variables. The LocalStack container will automatically pick it up and activate the licensed features. -Go to the [CI Key Page](https://app.localstack.cloud/workspace/ci-keys) page and copy your CI key. -To add the CI key to your GitHub project, follow these steps: +Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. +To add the CI Auth Token to your GitHub project, follow these steps: - Navigate to your repository **Settings > Secrets** and press **New repository secret**. -- Enter `LOCALSTACK_API_KEY` as the name of the secret and paste your CI key as the value. +- Enter `LOCALSTACK_AUTH_TOKEN` as the name of the secret and paste your CI Auth Token as the value. Click **Add secret** to save your secret. -Adding the LocalStack CI key as secret in GitHub -
-
- -Additionally, you need to modify your GitHub Action workflow to use the `localstack/localstack-pro` image and use the `LOCALSTACK_API_KEY` environment variable. +You can then use our [`setup-localstack`](https://github.com/localstack/setup-localstack) GitHub Action to start your LocalStack container, with the `LOCALSTACK_AUTH_TOKEN` environment variable: ```yaml - name: Start LocalStack - uses: LocalStack/setup-localstack@v0.2.2 + uses: LocalStack/setup-localstack@v0.2.3 with: image-tag: 'latest' install-awslocal: 'true' use-pro: 'true' env: - LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ``` ### Dump Localstack logs @@ -156,7 +152,7 @@ Find out more about ephemeral instances [here](/user-guide/cloud-sandbox/). state-action: load state-name: my-ls-state env: - LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ... @@ -168,7 +164,7 @@ Find out more about ephemeral instances [here](/user-guide/cloud-sandbox/). state-action: save state-name: my-ls-state env: - LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} ... ``` diff --git a/content/en/user-guide/ci/gitlab-ci/index.md b/content/en/user-guide/ci/gitlab-ci/index.md index 97402d0450..c7c9ad2650 100644 --- a/content/en/user-guide/ci/gitlab-ci/index.md +++ b/content/en/user-guide/ci/gitlab-ci/index.md @@ -75,20 +75,20 @@ job: - DOCKER_HOST="tcp://${dind_ip}:2375" localstack start -d ``` -### Configure a CI key +### Configure a CI Auth Token -You can easily enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your CI key to the repository's environment variables. -Go to your project's **Settings > CI/CD** and expand the **Variables** section. -Select the **Add Variable** button and fill in the necessary details. -After you create a variable, you can use it in the `.gitlab-ci.yml` file. +You can easily enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) to the repository's environment variables as `LOCALSTACK_AUTH_TOKEN`. +Go to your project's **Settings > CI/CD** and expand the **Variables** section. +Select the **Add Variable** button and fill in the necessary details with `LOCALSTACK_AUTH_TOKEN` as the key and your CI Auth Token as the value. +After you create the variable, you can use it in the `.gitlab-ci.yml` file. -However Variables set in the GitLab UI are not passed down to service containers. -We need to assign them to variables in the UI, and then re-assign them in our `.gitlab-ci.yml` +However, variables set in the GitLab UI are not automatically passed down to service containers. +You need to assign them as variables in the UI, and then re-assign them in your `.gitlab-ci.yml`. ```yaml ... variables: - LOCALSTACK_API_KEY: $LOCALSTACK_API_KEY + LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN ... services: - name: localstack/localstack-pro:latest @@ -97,7 +97,7 @@ services: ``` You can check the logs of the LocalStack container to see if the activation was successful. -If the CI key activation fails, LocalStack container will exit with an error code. +If the CI Auth Token activation fails, LocalStack container will exit with an error code. ### Dump Localstack logs @@ -179,7 +179,7 @@ Find more information about cloud pods [here](/user-guide/state-management/cloud ```yaml ... variables: - LOCALSTACK_API_KEY: $LOCALSTACK_API_KEY + LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN ... setup-job: stage: build diff --git a/content/en/user-guide/ci/travis-ci/index.md b/content/en/user-guide/ci/travis-ci/index.md index 8ee4bfe9b6..18136859ac 100644 --- a/content/en/user-guide/ci/travis-ci/index.md +++ b/content/en/user-guide/ci/travis-ci/index.md @@ -46,16 +46,14 @@ script: - echo "Execute your tests here :)" ``` -## Configuring a CI key +## Configuring a CI Auth Token -You can easily enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your CI key to the project's environment variables. -The LocalStack CLI will automatically pick it up and activate the Pro features. +You can easily enable LocalStack Pro by using the `localstack/localstack-pro` image and adding your [CI Auth Token](https://app.localstack.cloud/workspace/auth-tokens) to the project's environment variables as `LOCALSTACK_AUTH_TOKEN`. +The LocalStack CLI will automatically detect it and activate the Pro features. -Just go to the project settings in Travis CI (`More options` β†’ `Settings`), scroll down to the `Environment Variables` section, and add your CI key: +To configure this in Travis CI, go to the project settings (`More options` β†’ `Settings`), scroll down to the `Environment Variables` section, and add your CI Auth Token as `LOCALSTACK_AUTH_TOKEN`. -![Adding the LocalStack CI key in Travis CI](travis-ci-env-config.png) - -Here is an example: +Here is an example workflow: ```yaml before_install: diff --git a/content/en/user-guide/ci/travis-ci/travis-ci-env-config.png b/content/en/user-guide/ci/travis-ci/travis-ci-env-config.png deleted file mode 100644 index d2b91d54a5..0000000000 Binary files a/content/en/user-guide/ci/travis-ci/travis-ci-env-config.png and /dev/null differ diff --git a/content/en/user-guide/cloud-sandbox/application-previews/index.md b/content/en/user-guide/cloud-sandbox/application-previews/index.md index 1b8f68d05b..4a34d4ffd4 100644 --- a/content/en/user-guide/cloud-sandbox/application-previews/index.md +++ b/content/en/user-guide/cloud-sandbox/application-previews/index.md @@ -40,7 +40,7 @@ A comment containing the preview link is automatically added to a Pull Request w This preview is available for 30 minutes ```yaml -uses: LocalStack/setup-localstack@v0.2.2 +uses: LocalStack/setup-localstack@v0.2.3 with: github-token: ${{ secrets.GITHUB_TOKEN }} state-backend: ephemeral diff --git a/content/en/user-guide/cloud-sandbox/ephemeral-instance/index.md b/content/en/user-guide/cloud-sandbox/ephemeral-instance/index.md index 8d0ec2e75e..9f21f41513 100644 --- a/content/en/user-guide/cloud-sandbox/ephemeral-instance/index.md +++ b/content/en/user-guide/cloud-sandbox/ephemeral-instance/index.md @@ -83,6 +83,103 @@ Ephemeral Instances, by default, are created with the latest version of LocalSta If you have created a Cloud Pod from an older version of LocalStack, you need to update the Cloud Pod to the latest version before loading it into an Ephemeral Instance. {{< /callout >}} +## Ephemeral Instances CLI + +The Ephemeral Instances CLI is included in the [LocalStack CLI installation](https://docs.localstack.cloud/getting-started/installation/#localstack-cli), so no additional installations are needed to start using it. +If you're a licensed user, setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable is recommended to access all features of the Ephemeral Instances CLI. + +Access the Ephemeral Instances CLI by running the `localstack ephemeral` command from your terminal. + +{{< command >}} +$ localstack ephemeral --help + +Usage: localstack ephemeral [OPTIONS] COMMAND [ARGS]... + + (Preview) Manage ephemeral LocalStack instances in the cloud. + + This command group allows you to create, list, and delete ephemeral + LocalStack instances. + Ephemeral instances are temporary cloud instances that + can be used for testing and development. + +Options: + -h, --help Show this message and exit. + +Commands: + create Create a new ephemeral instance + delete Delete an ephemeral instance + list List all ephemeral instances + logs Fetch logs from an ephemeral instance + +{{< / command >}} + +To start an Ephemeral Instance, run the following command: + +{{< command >}} +$ localstack ephemeral create --name my-instance-123 +{{< / command >}} + +The output of the command should look like this: + +```bash +{ + "creation_time": 1731347416, + "endpoint_url": "https://ls-ji9gajoqrveou.sandbox.localstack.cloud", + "expiry_time": 1731351016, + "id": "ji9gajoqrveou", + "image": { + "image_name": "localstack/localstack-pro", + "tag": "latest" + }, + "instance_name": "my-instance-123", + "labels": { + "image-name": "localstack/localstack-pro", + "image-tag": "latest", + "instance-name": "my-instance-123", + "requestor": "4e60f2cb" + }, + "requestor": "4e60f2cb", + "shape": { + "memory_megabytes": 2048, + "virtual_cpus": 1 + }, + "status": "running" +} +``` + +List your available running Ephemeral Instances with: + +{{< command >}} +$ localstack ephemeral list +{{< / command >}} + +Retrieve your Ephemeral Instance logs with: + +{{< command >}} +$ localstack ephemeral logs --name my-instance-123 +{{< / command >}} + +The logs output will look like this: + +```bash +LocalStack version: 3.8.2.dev98 +LocalStack build date: 2024-11-11 +LocalStack build git hash: c624ee66 + +2024-11-11T17:50:42.373 INFO --- [ MainThread] l.p.c.b.licensingv2 : Successfully requested and activated new license 636c4b55-b09c-4a93-bef6-2f6d024f7d8a:enterprise πŸ”‘βœ… +2024-11-11T17:50:43.504 INFO --- [ MainThread] l.p.c.extensions.platform : loaded 0 extensions +Ready. +``` + +Finally, delete your Ephemeral Instance with: + +{{< command >}} +$ localstack ephemeral delete --name my-instance-123 + +Successfully deleted instance: my-instance-123 βœ… + +{{< / command >}} + ## Credit Consumption Ephemeral Instances consume credits based on the resources used and the duration of the instance. diff --git a/content/en/user-guide/lambda-tools/debugging/index.md b/content/en/user-guide/lambda-tools/debugging/index.md index 1eaaa49af9..7c4d624d5d 100644 --- a/content/en/user-guide/lambda-tools/debugging/index.md +++ b/content/en/user-guide/lambda-tools/debugging/index.md @@ -23,6 +23,11 @@ More examples and tooling support for local Lambda debugging (including support * [Lambda Debug Mode (preview)](#lambda-debug-mode-preview) * [Resources](#resources) +{{< callout tip >}} +Due to the ports published by the Lambda container for the debugger, it is currently only possible to debug one Lambda function at a time. +For advanced debugging scenarios, such as those requiring multiple ports, refer to [Lambda Debug Mode (preview)]({{< relref "debugging#lambda-debug-mode-preview" >}}) section. +{{< /callout >}} + ## Debugging Python lambdas Lambda functions debugging used to be a difficult task. diff --git a/content/en/user-guide/localstack-enterprise/ci-analytics/index.md b/content/en/user-guide/localstack-enterprise/ci-analytics/index.md index ee48147b2a..63300f4438 100644 --- a/content/en/user-guide/localstack-enterprise/ci-analytics/index.md +++ b/content/en/user-guide/localstack-enterprise/ci-analytics/index.md @@ -96,7 +96,7 @@ jobs: steps: - name: Start LocalStack env: - LOCALSTACK_API_KEY: ${{ secrets.LOCALSTACK_API_KEY }} + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} LS_CI_PROJECT: ls-platform-integration-tests run: | pip install localstack awscli-local[ver1] diff --git a/content/en/user-guide/localstack-enterprise/enterprise-support/index.md b/content/en/user-guide/localstack-enterprise/enterprise-support/index.md index 335315d5f2..e4b1138e2a 100644 --- a/content/en/user-guide/localstack-enterprise/enterprise-support/index.md +++ b/content/en/user-guide/localstack-enterprise/enterprise-support/index.md @@ -13,7 +13,7 @@ The key components of our enterprise support offering include: - **Direct Slack Connect Channel**: A dedicated Slack Connect channel is available to maintain a direct communication link with the LocalStack engineering team. This setup ensures quick issue resolution and streamlined collaboration, improving overall service efficiency. -- **Dedicated Customer Success Manager (CSM) and Solutions Architect (SA)**: Enterprise customers are assigned a CSM and SA. +- **Dedicated Customer Success Manager (CSM) and Technical Account Manager (TAM)**: Enterprise customers are assigned a CSM and SA. The CSM acts as a strategic advisor to help fully utilize LocalStack's offerings, while the SA provides expert technical assistance in designing and optimizing solutions tailored to your needs. - **Custom Service Level Agreements (SLAs)**: Tailor your service levels and response times to meet your organization's requirements. Custom SLAs can be negotiated to align with your business objectives and ensure optimal system performance. diff --git a/content/en/user-guide/localstack-enterprise/k8s-operator/index.md b/content/en/user-guide/localstack-enterprise/k8s-operator/index.md index 423c55f897..6a2cafeb9a 100644 --- a/content/en/user-guide/localstack-enterprise/k8s-operator/index.md +++ b/content/en/user-guide/localstack-enterprise/k8s-operator/index.md @@ -32,7 +32,7 @@ spec: image: localstack/localstack-pro:3.5.0 debug: trace - authToken: "" # Set your LocalStack auth token here + authToken: "" # Set your LocalStack Auth Token here autoLoadPods: [""] # Set your Cloud Pods to automatically load them here (optional) dnsProvider: coredns diff --git a/content/en/user-guide/state-management/cloud-pods/index.md b/content/en/user-guide/state-management/cloud-pods/index.md index df1a2f44fb..6eb607946a 100644 --- a/content/en/user-guide/state-management/cloud-pods/index.md +++ b/content/en/user-guide/state-management/cloud-pods/index.md @@ -138,7 +138,7 @@ $ localstack pod versions s3-test ### Pull your Pod state -On a separate machine, start LocalStack while ensuring the auth token is properly configured. +On a separate machine, start LocalStack while ensuring the Auth Token is properly configured. Then, retrieve the previously created Cloud Pod by employing the `load` command, specifying the Cloud Pod name as the first argument: {{< command >}} @@ -236,7 +236,9 @@ To export the state, follow these steps: 1. Navigate to the **Cloud Pod** tab within the [Export/Import State](https://app.localstack.cloud/inst/default/state) page. 2. Create AWS resources locally as needed. 3. Enter the Pod name and toggle between the **New Pod** and **Existing Pod** options. -4. Click on **Create New Pod**. +4. Enter the services to save resources for. + By default, all available service resources are saved. +5. Click on **Create New Pod**. A new Cloud Pod will be created and will be available for import into another LocalStack instance. You can check out the list of available Cloud Pods in the [Cloud Pod](https://app.localstack.cloud/pods) page. @@ -518,7 +520,6 @@ Once added, a remote persists even after LocalStack restarts. ## State Merging Cloud Pods offers various strategies for integrating states into your LocalStack container. -To activate the merge strategies, you can set `--strategy ` while loading the Cloud Pod. The available strategies are: - `overwrite`: This strategy clears the existing state and loads the new state from the Cloud Pod, completely resetting the LocalStack state. @@ -527,6 +528,22 @@ The available strategies are: - `service-merge`: This strategy merges services at the account-region level, provided there's no overlap in resources. It prioritizes the loaded resources when merging. +### LocalStack CLI + +To activate merge strategies, set `--strategy ` when loading a Cloud Pod using the LocalStack CLI. +For instance, to load a Cloud Pod named `test-pod-s3-sqs` with the `service-merge` strategy, run the following command: + +{{< command >}} +$ localstack pod load test-pod-s3-sqs --strategy service-merge +{{< / command >}} + +### LocalStack Web Application + +To activate merge strategies, navigate to the **Cloud Pods** tab on the [Export/Import State page](https://app.localstack.cloud/inst/default/state). +Enter the name of the Cloud Pod, select the version, choose the strategy from a dropdown, and click **Load State from Pod**. + +Merge Strategy Web UI + ### Example scenario Let us take the image below as example. @@ -592,7 +609,7 @@ However, state management might not yet work reliably for every service. ## Troubleshooting -### Unable to obtain auth token +### Unable to obtain Auth Token When you try to save a Cloud Pod and see the error in LocalStack logs like this: diff --git a/content/en/user-guide/state-management/cloud-pods/merge-strategy-web-app.png b/content/en/user-guide/state-management/cloud-pods/merge-strategy-web-app.png new file mode 100644 index 0000000000..8682751988 Binary files /dev/null and b/content/en/user-guide/state-management/cloud-pods/merge-strategy-web-app.png differ diff --git a/content/en/user-guide/tools/event-studio/display-the-connections.png b/content/en/user-guide/tools/event-studio/display-the-connections.png new file mode 100644 index 0000000000..b9b2ce1ef7 Binary files /dev/null and b/content/en/user-guide/tools/event-studio/display-the-connections.png differ diff --git a/content/en/user-guide/tools/event-studio/edit-and-replay.png b/content/en/user-guide/tools/event-studio/edit-and-replay.png new file mode 100644 index 0000000000..2df3116ced Binary files /dev/null and b/content/en/user-guide/tools/event-studio/edit-and-replay.png differ diff --git a/content/en/user-guide/tools/event-studio/index.md b/content/en/user-guide/tools/event-studio/index.md new file mode 100644 index 0000000000..229dc95212 --- /dev/null +++ b/content/en/user-guide/tools/event-studio/index.md @@ -0,0 +1,93 @@ +--- +title: "Event Studio" +weight: 12 +description: Event Studio allows you to record, trace, debug and replay any events exchanged between AWS services. +tags: ["Pro image"] +--- + +## Introduction + +Event Studio allows users to view, collect, and inspect data exchanges, including event payloads and metadata, between AWS services. +It enhances system observability by displaying the data exchanged at every stage, facilitating clear understanding of event flows. +It further centralizes debugging by enabling event replay at any system stage for detailed analysis and troubleshooting. +In addition, it serves as a single point of truth to understand potential errors, service configuration mismatches and IAM permission issues. + +With Event Studio, you can: + +- Observe and understand the flow of events through your system. +- Replay events to troubleshoot AWS services involved in your workflow. +- Identify errors and obtain detailed information for corrections. +- Get immediate feedback on any misconfigurations in your services. +- Gain insights into IAM policies and detect missing permissions. +- Enhance event contexts for advanced flow tracing. + +## Installation + +To install Event Studio, start your LocalStack container with your `LOCALSTACK_AUTH_TOKEN`: + +{{< command >}} +$ export LOCALSTACK_AUTH_TOKEN=... +$ localstack start +{{< / command >}} + +Event Studio is available as a LocalStack Extension. +To install it, use the `extensions` sub-command in the `localstack` CLI. +Run the following command to install Event Studio: + +{{< command >}} +$ localstack extension install localstack-extension-event-studio +{{< / command >}} + +Check the LocalStack logs for Event Studio output, where you should see logs like: + +```bash +localstack-main | 2024-11-21T08:47:25.688 INFO --- [ MainThread] l.e.patterns.webapp : eventstudio extension available at http://localhost.localstack.cloud:4566/_extension/eventstudio +localstack-main | 2024-11-21T08:47:25.694 INFO --- [ MainThread] l.e.patterns.webapp : eventstudio extension available at http://eventstudio.localhost.localstack.cloud:4566 +localstack-main | 2024-11-21T08:47:25.858 INFO --- [ady_monitor)] eventstudio.extension : Extension Loaded +localstack-main | Ready. +``` + +You can navigate to **https://eventstudio.localhost.localstack.cloud:4566** in your browser to view your events. + +## Features + +### List the local events + +With Event Studio, you can view a detailed list of events in your application, including event producers, types, and timestamps. +The interface enables you to trace the flow of events, identify relationships between services, and analyze patterns for debugging or optimization. + +Listing the local events + +### Display the connections + +By clicking on the events, you can visualize the intricate relationships between AWS services in your event-driven architecture. +Event Studio offers a clear, interactive graph that shows how different AWS services interact, making it easy to track data flow, identify bottlenecks, and debug issues. + +Display the connections + +### View Event Details + +When you click on the service, you can drill down into the specifics of each event, including the data exchanged between services, detailed payloads, and metadata. +Event Studio highlights errors, warnings, and potential IAM permission issues, enabling precise debugging and troubleshooting. +This detailed view ensures complete transparency and insight into system interactions at every step. + +View Event Details + +### Edit & Replay + +Finally, you can modify event payloads and metadata directly within the interface to test different scenarios or adjust configurations. +Replay edited events through your system to analyze workflows, validate fixes, and ensure accurate service interactions. +This is essential for effectively debugging complex event-driven architectures. + +Edit & Replay + +## Supported Services + +The following services are supported on Event Studio: + +- [S3](https://docs.localstack.cloud/user-guide/aws/s3/) +- [SQS](https://docs.localstack.cloud/user-guide/aws/sqs/) +- [SNS](https://docs.localstack.cloud/user-guide/aws/sns/) +- [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) +- [Lambda](https://docs.localstack.cloud/user-guide/aws/lambda/) +- [EventBridge](https://docs.localstack.cloud/user-guide/aws/events/) diff --git a/content/en/user-guide/tools/event-studio/listing-local-events.png b/content/en/user-guide/tools/event-studio/listing-local-events.png new file mode 100644 index 0000000000..02fde3c6f9 Binary files /dev/null and b/content/en/user-guide/tools/event-studio/listing-local-events.png differ diff --git a/content/en/user-guide/tools/event-studio/view-event-details.png b/content/en/user-guide/tools/event-studio/view-event-details.png new file mode 100644 index 0000000000..d080f904bb Binary files /dev/null and b/content/en/user-guide/tools/event-studio/view-event-details.png differ diff --git a/content/en/user-guide/web-application/ci-keys/ci-keys.png b/content/en/user-guide/web-application/ci-keys/ci-keys.png deleted file mode 100644 index 56e5124838..0000000000 Binary files a/content/en/user-guide/web-application/ci-keys/ci-keys.png and /dev/null differ diff --git a/content/en/user-guide/web-application/ci-keys/index.md b/content/en/user-guide/web-application/ci-keys/index.md index cf69759292..f365bf1f36 100644 --- a/content/en/user-guide/web-application/ci-keys/index.md +++ b/content/en/user-guide/web-application/ci-keys/index.md @@ -1,20 +1,35 @@ --- -title: "CI Keys" -linkTitle: "CI Keys" +title: "CI Keys (Deprecated)" +linkTitle: "CI Keys (Deprecated)" weight: 160 -description: A CI key is used to access LocalStack in CI or other machine environments. +description: A CI Key is used to access LocalStack in CI or other machine environments. aliases: - /user-guide/ci/ci-keys/ --- +{{< callout "warning">}} +LocalStack CI Keys are now deprecated, and the option to issue or retrieve a CI Key has been removed from the LocalStack Web Application. +Users are advised to switch to **CI Auth Tokens**, which are designed for use in CI environments and other non-developer contexts. +CI Auth Tokens can be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). + +To migrate to CI Auth Tokens, follow these steps: + +1. Retrieve your CI Auth Token from the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). +2. Remove the existing CI key labeled as `LOCALSTACK_API_KEY` from your CI provider's secrets. +3. Enter the Auth Token value into the `LOCALSTACK_AUTH_TOKEN` environment variable of your CI provider. + +In early 2025, we will completely phase out legacy CI keys. +After the sunsetting period, legacy CI keys will no longer activate or function with LocalStack. +{{< /callout >}} + +## Introduction + LocalStack requires a **CI Key** for use in Continuous Integration (CI) or similar machine environments. Each instance startup in a CI or comparable environment consumes one CI token. CI Keys are administered on the [CI Keys page](https://app.localstack.cloud/workspace/ci-keys) of the LocalStack Web Application. These keys are linked to specific CI pipelines or projects, rather than individual developers. -A screenshot of the LocalStack web app. The screenshot shows the page to manage CI keys - CI Keys are not meant for individual developers. To grant a developer access to LocalStack and its advanced features, assign a license to them on the [Users & Licenses page](https://app.localstack.cloud/workspace/members). diff --git a/content/en/user-guide/web-application/stack-overview/index.md b/content/en/user-guide/web-application/stack-overview/index.md new file mode 100644 index 0000000000..db934c6bc5 --- /dev/null +++ b/content/en/user-guide/web-application/stack-overview/index.md @@ -0,0 +1,40 @@ +--- +title: "Stack Overview" +linkTitle: "Stack Overview" +weight: 159 +description: Stack Overview reflects the current state of your LocalStack environment +--- + +## Introduction + +The Stack Overview provides a summary of deployed resources, categorized services with configurations, and quick access to resource details like identifiers and endpoints. + +You can access the Stack Overview in the [LocalStack Web Application](https://app.localstack.cloud/inst/default/overview). +Alternatively, go to your LocalStack Instance and click on **Overview** to see a high-level visualization of your locally running cloud app architecture. + +Stack Overview +
+
+ +## Supported Resources + +The following resources are supported by Stack Overview: + +1. [`AWS::ApiGateway::RestApi`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html) +2. [`AWS::CloudFormation::Stack`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-stack.html) +3. [`AWS::DynamoDB::Table`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html) +4. [`AWS::EC2::VPC`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-vpc.html) +5. [`AWS::Events::EventBus`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-events-eventbus.html) +6. [`AWS::IAM::Group`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-group.html) +7. [`AWS::IAM::Role`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html) +8. [`AWS::IAM::User`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-user.html) +9. [`AWS::Lambda::Function`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) +10. [`AWS::S3::Bucket`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3-bucket.html) +11. [`AWS::SES::EmailIdentity`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ses-emailidentity.html) +12. [`AWS::SNS::Topic`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-topic.html) +13. [`AWS::SQS::Queue`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sqs-queue.html) +14. [`AWS::SSM::Parameter`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-parameter.html) +15. [`AWS::SecretsManager::Secret`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-secretsmanager-secret.html) +16. [`AWS::StepFunctions::StateMachine`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html) +17. [`AWS::CloudFront::Distribution`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudfront-distribution.html) +18. [`AWS::Pipes::Pipe`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-pipes-pipe.html) diff --git a/content/en/user-guide/web-application/stack-overview/stack-overview.png b/content/en/user-guide/web-application/stack-overview/stack-overview.png new file mode 100644 index 0000000000..758148b4b6 Binary files /dev/null and b/content/en/user-guide/web-application/stack-overview/stack-overview.png differ diff --git a/content/en/user-guide/web-application/users-licences/index.md b/content/en/user-guide/web-application/users-licences/index.md index afbd0f6c89..d7561b99ae 100644 --- a/content/en/user-guide/web-application/users-licences/index.md +++ b/content/en/user-guide/web-application/users-licences/index.md @@ -54,20 +54,16 @@ Changes to licenses take effect immediately and require no further action of the In the past, access to LocalStack and advanced features was granted to individual developers by providing them with a (now legacy) API key. With the recent change, now the recommended way is to assign a 'license' to a user instead. -Instead of using the legacy API key, the user sets up their personal auth token to access LocalStack advanced features. -Upon authentication, the the auth token is used to identify the user and to retrieve and activate an assigned license. +Instead of using the legacy API key, the user sets up their personal Auth Token to access LocalStack advanced features. +Upon authentication, the the Auth Token is used to identify the user and to retrieve and activate an assigned license. The benefits of this new systems are: - Auth tokens are longer and more secure (more bits of entropy) -- A user can freely rotate their auth token (if needed) without any changes to their license. +- A user can freely rotate their Auth Token (if needed) without any changes to their license. - An admin can manage users's licenses, not requiring any configuration change of the user. Previously users had to manually update their (legacy) API key. -{{< callout >}} -The transition to auth tokens only affects _developer_ API keys. **CI keys** are unaffected by this transition and are still the only way to activate a LocalStack instance for use in CI or other automated contexts. -{{< /callout >}} - ### Migrating Users to Auth Tokens and Licenses To migrate users from legacy API keys, assign a license to them in the 'Workspace Members' list. @@ -77,8 +73,8 @@ A user holding both a legacy API key and a license is only counted once when the If a user uses an API key that was not assigned to them, then it might be necessary to first remove the API key before a license can be assigned. -Once the license is assigned to the user, and the user set up their system to use the new auth token, their legacy API key can be deleted from the workspace. -A user can find their personal auth token either in the 'Auth Token' or in the 'Getting Started' section of the web app. +Once the license is assigned to the user, and the user set up their system to use the new Auth Token, their legacy API key can be deleted from the workspace. +A user can find their personal Auth Token either in the 'Auth Token' or in the 'Getting Started' section of the web app. ### Sunsetting legacy API keys