v4 docs (#1547)

Co-authored-by: Ben Simon Hartung <[email protected]> Co-authored-by: Joel Scheuner <[email protected]> Co-authored-by: Silvio Vasiljevic <[email protected]> Co-authored-by: Daniel Fangl <[email protected]> Co-authored-by: Simon Wallner <[email protected]> Co-authored-by: komarkovich <[email protected]> Co-authored-by: MarcelStranak <[email protected]> Co-authored-by: Harsh Mishra <[email protected]> Co-authored-by: Simon Walker <[email protected]> Co-authored-by: Alexander Rashed <[email protected]>
localstack · Nov 21, 2024 · 88b4e17 · 88b4e17
1 parent ceb7bf9
commit 88b4e17
Show file tree

Hide file tree

Showing 50 changed files with 633 additions and 1,019 deletions.
diff --git 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
@@ -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
@@ -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 <YOUR_AUTH_TOKEN>
 localstack start
 {{< /tab >}}
 {{< tab header="Windows" lang="powershell" >}}
-$env:LOCALSTACK_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"; localstack start
+localstack auth set-token <YOUR_AUTH_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
@@ -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]({{<ref "user-guide/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?