aws-emulator README

项目的 README,来自 github.com/aws/aws-emulator。合并为一个 markdown 文件:README.md。

AWS Emulator README

AWS Emulator is a local emulator of the AWS APIs. You use it to test your software without calling AWS, on your own machine, on a development server, or in continuous integration (CI). You don’t need an AWS account. Your requests go to the emulator, not to AWS. So you work with emulated resources instead of AWS resources. AWS Emulator has no additional service fee. You pay only for AWS resources when you deploy on AWS.

The emulator is a local program that serves an AWS API endpoint. It has no graphical interface. After you start the emulator, you set environment variables to point the AWS CLI or an AWS SDK at its endpoint. Then you run your code as usual. In embedded mode, you pass the emulator’s HTTP client to your SDK instead.

AWS Emulator is for building and testing. Don’t use it for production workloads or to test security. See Security in AWS Emulator.

Documentation: AWS Emulator User Guide

Quick start

With an AI coding agent

Install the aws-emulator skill, then ask your agent to set up the emulator. This needs the AWS CLI version 2.35.0 or later. See Getting started with an AI coding agent.

aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

Local process

To start the emulator as a local process, see Getting started. Point your SDK at a running emulator by setting environment variables. See Pointing your AWS SDK at AWS Emulator.

Embedded mode

Add the emulator as a dev-dependency and run it in-process, one isolated instance per test. There is no endpoint URL, certificate, or environment variable to set. Your test wires the emulator's HTTP client straight into the SDK client. See Getting started with embedded mode, and Building from source below.

Known issues

To see how closely each service matches AWS, check the fidelity scores published with each release on the releases page. To check whether your own project is expected to work, see Checking whether your project works with AWS Emulator.

Individual gaps are tracked in the repository's issues/ directory. APIs and behaviors that don't work yet are under issues/things-that-do-not-work/, and ones that have since been fixed move to issues/things-that-now-work/.

Building from source

You need this if you are modifying the emulator, running it from a checkout, or using embedded mode. Embedded mode compiles the emulator into your test binary, so the prerequisites and build guidance below apply to it too. Most other users install a prebuilt package instead (see Quick start). Building from source is supported on Linux (x86_64 and aarch64); on Windows and macOS, use Docker (see Getting started with Docker).

Prerequisites

Build and run

cargo build -p aws-emulator-router
cargo run   -p aws-emulator-router

The emulator serves HTTPS on 127.0.0.1:9297 (self-signed certificate).

Embedded mode build

Embedded mode compiles the emulator into your test binary, so your project's first cargo test builds the emulator's service crates alongside your own code. Budget a first build and target/ on the same order as building from source above, then fast incremental builds. Recommendation: reuse one CARGO_TARGET_DIR across projects, cache target/ (or use sccache) in CI, and pin the emulator to a release commit so it isn't rebuilt on every change.

Repository layout

.
├── Cargo.toml              # workspace: one member per service, plus the core crates
├── services/
│   └── service-<name>/     # ONE CRATE PER SERVICE
│       ├── smithy-model/   # <name>.json — the Smithy model that drives the wire protocol
│       ├── build.rs        # generates the service declaration from the model
│       ├── src/
│       │   ├── service.rs  # request routing and refusal overrides
│       │   ├── state.rs    # this service's in-memory state
│       │   └── ops/        # one file per operation
│       └── tests/
├── core/
│   ├── router/             # the emulator binary: mounts every service on one endpoint
│   └── embedded/           # the in-process (embedded mode) facade
├── vendor/                 # framework crates — do not edit (replaced on update)
└── issues/                 # tracked fidelity issues

Telemetry

AWS Emulator is configured to collect and report usage data to AWS, to gain insight into how AWS Emulator is used. Telemetry is on by default. AWS Emulator collects telemetry data with strict data minimization in mind, preventing identification or attribution to specific users, accounts, or organizations. Its records never include what’s in your requests or responses, your code, your credentials, or personal data. We don’t share telemetry with third parties.

For details on what is collected and how the data is handled, see Telemetry in AWS Emulator. To turn telemetry off, use one of the following options.

Use a command-line option

Start the emulator with the --telemetry option (short form -t) set to off. This setting applies only to that emulator process.

aws-emulator --telemetry off

In a container, add --telemetry off after the image name in the docker run command.

Use an environment variable

Set EMULATOR_TELEMETRY to off before you start the emulator. This setting applies to every emulator that you start from that shell.

EMULATOR_TELEMETRY accepts on, true, or 1 to turn telemetry on, and off, false, or 0 to turn it off. Values aren’t case sensitive. Any other value turns telemetry off, and the startup notice shows a warning.

export EMULATOR_TELEMETRY=off
aws-emulator

Use a configuration file

To turn telemetry off for every run on a machine, add these lines to the emulator settings file, config.toml. The file is ~/.aws/emulator/config.toml on Linux and macOS, and %USERPROFILE%\.aws\emulator\config.toml on Windows. To use a different file, set the EMULATOR_CONFIG environment variable to its path.

[telemetry]
enabled = false

Use the embedded configuration API

In embedded mode, turn off telemetry in the options that you pass when you create the emulator.

use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions, Telemetry};

fn main() {
    let emulator = AwsEmulatorEmbedded::new(EmbeddedOptions::default().telemetry(Telemetry::Off));
    let _http_client = emulator.http_client();
}

You might build a tool that includes the emulator, such as a test framework that other people run. If you do, tell your users about telemetry and give them a way to turn it off. You can also ship your tool with telemetry off.

Reporting issues and contributing

We don't accept pull requests: AI agents keep the emulator up to date with AWS, with regular updates. See CONTRIBUTING.md for details.

License

This software is licensed under the CC0 1.0 Universal (CC0-1.0) License, except the code in the vendor/ directory, which is under the Apache License 2.0. See LICENSE for details, and vendor/README.md for the license of the code in vendor/.

aws-emulator (aws/aws-emulator)

正在搜索数据库…

这是什么?这是 AWS API 的本地模拟器。你可以在自己的机器、开发服务器或 CI 中使用它来测试软件,无需调用 AWS,也不需要 AWS 账户。
它是库还是独立程序?主要是独立程序:它提供 AWS API 端点,没有图形界面。你也可以把它作为 dev-dependency 嵌入 Rust 测试中。
我该怎么让它运行起来?在 Linux 上安装 RPM 或 Debian 软件包,然后运行 aws-emulator。在 Windows 或 macOS 上,使用一个简短的 Dockerfile 构建容器并在其中运行。然后设置环境变量,让 AWS CLI 或 AWS SDK 指向模拟器的端点。
我需要 AWS 账户或 AWS CLI 吗?不需要 AWS 账户,因为你的请求会发送到模拟器。但你需要 AWS CLI 或 AWS SDK,并将其指向模拟器。AI 智能体的设置方式需要 AWS CLI 2.35.0 或更高版本。
它不适合做什么,编译它要付出什么代价?它用于构建和测试,不适用于生产负载或安全测试。从源码构建或使用嵌入模式需要 Rust 工具链、C 编译器,以及至少 100 GB 的可用磁盘空间,而且首次构建耗时很长。
它会向外发送任何数据吗?会。遥测功能默认开启,会向 AWS 上报使用数据。记录中从不包含你的请求、响应、代码、凭证或个人数据,也不会与第三方共享。你可以通过 --telemetry off 选项、EMULATOR_TELEMETRY 环境变量或 config.toml 将其关闭。
授权方面有什么需要注意的吗?代码采用 CC0-1.0 授权,即公共领域。例外的是 vendor/ 目录,它采用 Apache License 2.0 授权。
我能在 Rust 测试里直接使用,而不启动服务器吗?可以。嵌入模式会在进程内运行模拟器,每个测试使用一个相互隔离的实例。无需设置端点、证书或环境变量,直接把模拟器的 HTTP 客户端传给 SDK 客户端即可。
它与真实 AWS 的行为有多接近?每个版本都会在 releases 页面发布各服务的仿真保真度评分。具体的差距记录在仓库的 issues/ 目录中,尚未实现的 API 则位于 issues/things-that-do-not-work/ 下。
运行它需要花钱吗?不需要。AWS Emulator 没有额外的服务费用。只有在 AWS 上部署时,才需要为 AWS 资源付费。
作者
aws
大小
1.3 GB
星标
9.1K
时长
2个月
提交 · 90 天