pjmyburg/localstack Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

LocalStack - 功能完整的本地AWS云栈

!LocalStack

LocalStack 提供了一个易于使用的测试/模拟框架，用于开发云应用程序。目前，其重点主要是支持AWS云栈。

概述

LocalStack 在本地机器上启动以下核心云API服务：

• API Gateway：http://localhost:4567
• Kinesis：http://localhost:4568
• DynamoDB：http://localhost:4569
• DynamoDB Streams：http://localhost:4570
• Elasticsearch：http://localhost:4571
• S3：http://localhost:4572
• Firehose：http://localhost:4573
• Lambda：http://localhost:4574
• SNS：http://localhost:4575
• SQS：http://localhost:4576
• Redshift：http://localhost:4577
• ES (Elasticsearch Service)：http://localhost:4578
• SES：http://localhost:4579
• Route53：http://localhost:4580
• CloudFormation：http://localhost:4581
• CloudWatch：http://localhost:4582
• SSM：http://localhost:4583
• SecretsManager：http://localhost:4584

此外，LocalStack 提供了一套强大的工具来与云服务交互，包括具有Python绑定的全功能KCL Kinesis客户端、用于nosetests的简单设置/拆卸集成，以及允许轻松在本地和远程云执行之间切换的环境抽象。

核心功能和特性

为什么选择LocalStack？

LocalStack 构建在现有的一流模拟/测试工具之上，最著名的是kinesalite/dynalite和moto。虽然这些工具非常出色，但它们在某些用例中缺乏功能。LocalStack 整合了这些工具，使它们能够互操作，并在它们之上添加了重要的缺失功能：

• 错误注入：LocalStack 允许注入真实云环境中经常发生的错误，例如Kinesis或DynamoDB在超过读写吞吐量时抛出的ProvisionedThroughputExceededException。
• 隔离进程：LocalStack 中的所有服务都在单独的进程中运行。额外进程的开销可以忽略不计，整个栈可以轻松在任何开发机器和CI服务器上执行。相比之下，moto中的组件通常硬连接在内存中（例如，当将SNS主题上的消息转发到SQS队列时，队列端点在本地哈希映射中查找）。而LocalStack服务处于隔离状态（通过HTTP可用的单独进程），这促进了真正的解耦，更接近真实的云环境。
• 可插拔服务：由于每个服务使用隔离进程，LocalStack中的所有服务都易于插拔（和替换）。这使我们能够保持框架更新，并为每个单独的服务选择一流的模拟工具。

使用场景和适用范围

• 云应用开发测试：在本地开发环境中模拟AWS服务，无需连接真实AWS账户，降低开发成本和风险。
• CI/CD流程集成：在持续集成/持续部署流程中作为测试环境，确保应用在云环境中的兼容性。
• 功能原型验证：快速验证基于AWS服务的应用功能原型，无需实际部署到云端。

详细使用方法和配置说明

系统要求

• make
• python（支持Python 2.x和3.x）
• pip（Python包管理器）
• npm（Node.js包管理器）
• java/javac（Java 8运行时环境和编译器）
• mvn（Maven，Java构建系统）

安装

安装LocalStack最简单的方法是通过pip：

bash
pip install localstack

安装后，使用以下命令运行基础设施：

bash
localstack start

注意：请不要使用sudo或root用户 - LocalStack应完全在本地非root用户下安装和启动。如果在MacOS X Sierra中遇到权限问题，请使用pip install --user localstack安装。

在Docker中运行

您也可以在Docker中启动LocalStack：

bash
localstack start --docker

（注意，在MacOS上，如果$TMPDIR包含Docker无法挂载的符号链接，可能需要运行TMPDIR=/private$TMPDIR localstack start --docker。）

或者使用docker-compose（需要先克隆仓库，目前支持docker-compose version 2）：

bash
docker-compose up

（注意，在MacOS上，如果$TMPDIR包含Docker无法挂载的符号链接，可能需要运行TMPDIR=/private$TMPDIR docker-compose up。）

配置参数

可以向LocalStack传递以下环境变量：

• SERVICES：逗号分隔的服务名称和（可选）它们应运行的端口。如果未指定端口，则使用默认端口。服务名称基本上对应AWS CLI的服务名称（kinesis、lambda、sqs等），尽管LocalStack仅支持其中的一部分。示例值：kinesis,lambda:4569,sqs:4570表示在默认端口启动Kinesis，在4569端口启动Lambda，在4570端口启动SQS。

• DEFAULT_REGION：与API通信时使用的AWS区域（默认为us-east-1）。

• HOSTNAME：在内部公开服务的主机名（默认为localhost）。用于自定义框架内部通信，例如，如果服务在不同的容器中使用docker-compose启动。

• HOSTNAME_EXTERNAL：在外部公开服务的主机名（默认为localhost）。例如，当从SQS服务向客户端返回队列URL时使用此主机。

• USE_SSL：是否使用带SSL加密的[***] URL（默认为false）。

• KINESIS_ERROR_PROBABILITY：0.0（默认）到1.0之间的十进制值，用于随机将ProvisionedThroughputExceededException错误注入Kinesis API响应。

• DYNAMODB_ERROR_PROBABILITY：0.0（默认）到1.0之间的十进制值，用于随机将ProvisionedThroughputExceededException错误注入DynamoDB API响应。

• LAMBDA_EXECUTOR：用于执行Lambda函数的方法。可能的值：

  • local：在本地机器的临时目录中运行Lambda函数
  • docker：在单独的Docker容器中运行每个函数调用
  • docker-reuse：为每个函数创建一个Docker容器，并在调用之间重用它

  对于docker和docker-reuse，如果LocalStack本身在Docker内部启动，则容器内部需要可用docker命令（通常需要以特权模式运行容器）。默认为docker，如果Docker不可用，则回退到local。

• LAMBDA_REMOTE_DOCKER：确定Lambda代码是复制还是挂载到容器中。可能的值：

  • true（默认）：Lambda函数定义将通过复制zip文件传递到容器（可能较慢）。允许远程执行，主机和客户端不在同一台机器上。
  • false：Lambda函数定义将通过挂载卷传递到容器（可能较快）。这要求Docker客户端和Docker主机在同一台机器上。

• DATA_DIR：用于保存持久数据的本地目录（目前仅支持以下服务：Kinesis、DynamoDB、Elasticsearch、S3）。将其设置为/tmp/localstack/data以启用持久性（/tmp/localstack挂载到Docker容器中），留空则禁用持久性（默认）。

• PORT_WEB_UI：Web用户界面（仪表板）的端口。默认为8080。

• <SERVICE>_BACKEND：用于特定服务的自定义端点URL，其中<SERVICE>是大写的服务名称（目前适用于：APIGATEWAY、CLOUDFORMATION、DYNAMODB、ELASTICSEARCH、KINESIS、S3、SNS、SQS）。这允许轻松将第三方服务集成到LocalStack中。

• FORCE_NONINTERACTIVE：使用Docker运行时，禁用--interactive和--tty标志。在无头环境中运行时有用。

此外，以下只读环境变量可用：

• LOCALSTACK_HOSTNAME：LocalStack服务可用的主机名。这在Lambda函数内部访问服务时需要（例如，从Lambda向DynamoDB或S3存储项目）。变量LOCALSTACK_HOSTNAME对本地Lambda执行（LAMBDA_EXECUTOR=local）和在单独Docker容器中执行（LAMBDA_EXECUTOR=docker）都可用。

通过CLI或代码访问基础设施

您可以将aws CLI指向本地基础设施，例如：

bash
aws --endpoint-url=http://localhost:4568 kinesis list-streams
{
    "StreamNames": []
}

新功能：查看awslocal，这是一个轻量级CLI包装器，可直接针对LocalStack运行命令（无需再指定--endpoint-url）。通过pip install awscli-local安装，然后使用如下：

bash
awslocal kinesis list-streams
{
    "StreamNames": []
}

更新：在Lambda函数内部使用环境变量$LOCALSTACK_HOSTNAME确定目标主机。有关更多详细信息，请参见配置部分。

客户端库

• Python：[***]
  • 或者，您也可以使用boto3并在创建连接时使用endpoint_url参数

与nosetests集成

如果要在集成测试（例如nosetests）中使用LocalStack，只需在测试设置方法中启动基础设施，然后在拆卸方法中清理所有内容：

python
from localstack.services import infra

def setup():
    infra.start_infra(async=True)

def teardown():
    infra.stop_infra()

def my_app_test():
    # 这里是测试逻辑

有关更多详细信息，请参见示例测试文件tests/test_integration.py。

与Java/JUnit集成

为了将LocalStack与Java一起使用，该项目提供了一个简单的JUnit运行器和JUnit 5扩展。查看ext/java中的示例JUnit测试。运行测试时，所有依赖项会自动下载并安装到系统的临时目录中。

java
...
import cloud.localstack.LocalstackTestRunner;
import cloud.localstack.TestUtils;

@RunWith(LocalstackTestRunner.class)
public class MyCloudAppTest {

  @Test
  public void testLocalS3API() {
    AmazonS3 s3 = TestUtils.getClientS3()
    List<Bucket> buckets = s3.listBuckets();
    ...
  }

}

或者使用JUnit 5：

java
@ExtendWith(LocalstackExtension.class)
public class MyCloudAppTest {
   ...
}

此外，还有一个LocalStack Test Runner版本，它在Docker容器中运行，而不是在当前机器上安装LocalStack。唯一的依赖是本地安装Docker。测试运行器将自动拉取镜像并在测试期间启动容器。可以使用@LocalstackDockerProperties注解配置容器。

java
@RunWith(LocalstackDockerTestRunner.class)
@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
public class MyDockerCloudAppTest {

  @Test
  public void testKinesis() {
    AmazonKinesis kinesis = DockerTestUtils.getClientKinesis();

    ListStreamsResult streams = kinesis.listStreams();
    ...

或者使用JUnit 5：

java
@ExtendWith(LocalstackDockerExtension.class)
@LocalstackDockerProperties(randomizePorts = true, services = { "sqs", "kinesis:77077" })
public class MyDockerCloudAppTest {
   ...
}

LocalStack JUnit测试运行器作为Maven Central中的工件发布。只需将以下依赖项添加到pom.xml文件中：

xml
<dependency>
    <groupId>cloud.localstack</groupId>
    <artifactId>localstack-utils</artifactId>
    <version>0.1.15</version>
</dependency>

故障排除

• 如果使用带有Kinesis的AWS Java库，请参考Java SDK的CBOR协议问题指南，了解如何禁用kinesalite不支持的CBOR协议。
• 从Java访问本地S3：为避免域名解析问题，需要在客户端上启用路径样式访问：

java
s3.setS3ClientOptions(S3ClientOptions.builder().setPathStyleAccess(true).build());
// 如果使用任何客户端构建器类，也可以这样做：
AmazonS3ClientBuilder builder = AmazonS3ClientBuilder.standard();
builder.withPathStyleAccessEnabled(true);
...

• 挂载临时目录：注意，在MacOS上，如果$TMPDIR包含Docker无法挂载的符号链接，可能需要运行TMPDIR=/private$TMPDIR docker-compose up。（详见：[***]
• 如果在Mac OS上pip install时遇到文件权限问题（例如，Permission denied: '/Library/Python/2.7/site-packages/six.py'），可能需要通过Homebrew重新安装pip（参见此讨论线程）。或者，尝试使用--user标志安装：pip install --user localstack
• 如果在OpenShift中部署，请注意：pod必须以root身份运行，并且用户必须具有添加到运行pod的功能，以允许Elasticsearch以非rootlocalstack用户运行。
• 环境变量no_proxy由LocalStack重写。（内部请求将直接通过localhost，绕过任何代理配置）。
• 要排查localstack启动问题，可以通过运行DEBUG=1 localstack start检查调试日志。
• 如果遇到与node/nodejs相关的错误，可能会发现（此问题评论：[***]
• 如果使用AWS Java库并需要禁用SSL证书检查，在Java调用中添加-Dcom.amazonaws.sdk.disableCertChecking。

Web仪表板

该项目还附带一个简单的Web仪表板，允许查看已部署的AWS组件及其之间的关系。

bash
localstack web