Floci EMR Serverless 模拟器实践指南Application 管理面 API 的本地化实现与配置【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址: https://gitcode.com/gh_mirrors/fl/floci导读本文以 FlociAWS 本地模拟器官方文档 docs/services/emr-serverless.md 为核心系统讲解 Floci 如何模拟 AWS EMR Serverless 的管理面management-planeREST JSON API覆盖 Application 从创建、查询、更新到启停的完整生命周期。通过本文你将掌握该服务的配置项、全部端点语义、状态机行为与已知限制并能结合源码级实现证据EmrServerlessService.java理解其底层工作原理从而在本地开发、测试和 CI 环境中正确使用 Floci 替代真实 EMR Serverless 进行应用编排验证。一、EMR Serverless 模拟器概述AWS EMR Serverless 是 AWS 提供的一项无服务器数据分析服务用户无需预置或管理集群即可运行 Spark、Hive 等大数据分析任务。Floci 作为轻量、免费、开源的 AWS 本地模拟器为 EMR Serverless 提供了管理面 APIREST JSON的模拟实现覆盖 Application 的基本生命周期。从实现范围看Floci 的 EMR Serverless 模块位于 src/main/java/io/github/hectorvent/floci/services/emrserverless/包含EmrServerlessController.javaJAX-RS REST 控制器负责 HTTP 路由与参数解析EmrServerlessService.java核心业务逻辑负责校验、状态机、幂等与持久化EmrServerlessRouteFilter.java前置匹配过滤器解决与其他服务的路由冲突model/目录下的 30 个模型类Application、请求/响应 DTO 以及各类配置模型如InitialCapacityConfig、MonitoringConfiguration、NetworkConfiguration等。该模拟器的核心价值在于它能满足 Terraform 等 IaC 工具中aws_emrserverless_application资源的创建与管理需求让本地基础设施编排测试无需依赖真实 AWS 环境。二、Configuration启用开关与端口Floci 的 EMR Serverless 模拟器通过两个配置键控制对应源码中的EmrServerlessServiceConfig与端口绑定逻辑参见 EmulatorConfig.java 中EmrServerlessServiceConfig接口定义默认enabled()返回true。Key描述默认值floci.emrserverless.enabled是否启用 EMR Serverless APItruefloci.emrserverless.port服务暴露的端口45662.1 配置说明与源码对应floci.emrserverless.enabled默认启用。在 EmulatorConfig.java 中EmrServerlessServiceConfig接口通过WithDefault(true)声明默认值这是 Floci 对多数服务采用的统一开关模式。floci.emrserverless.port默认4566即 Floci 的默认网关端口。所有 AWS 服务端点均通过该统一端口对外暴露。此外从配置体系看EMR Serverless 还支持存储层面的配置EmrServerlessStorageConfig见 EmulatorConfig.java包含可选的mode存储模式以及默认5000ms 的flushIntervalMs数据落盘刷新间隔说明模拟器的数据持久化与 Floci 统一的存储后端体系AccountAwareStorageBackend挂钩。提示实际使用中可将上述配置写入 Floci 的application.yml配置文件或在环境变量中以FLOCI_EMRSERVERLESS_ENABLED、FLOCI_EMRSERVERLESS_PORT的形式注入。三、Endpoints标准 AWS emr-serverless 端点Floci 实现了 AWSemr-serverless服务的标准端点覆盖 Application 的完整管理面操作。下表汇总了全部端点及其对应的 AWS 操作名称HTTP 方法与路径AWS 操作功能POST /applicationsCreateApplication创建 ApplicationGET /applicationsListApplications列出 Application支持状态过滤与分页GET /applications/{applicationId}GetApplication查询单个 Application 详情PATCH /applications/{applicationId}UpdateApplication更新 Application 配置DELETE /applications/{applicationId}DeleteApplication删除 ApplicationPOST /applications/{applicationId}/startStartApplication启动 ApplicationPOST /applications/{applicationId}/stopStopApplication停止 Application这些端点与 EmrServerlessController.java 中的 JAX-RS 注解一一对应控制器统一使用application/json请求与响应符合 AWS REST JSON 协议约定。3.1 路由冲突的解决机制值得注意的一个实现细节由于EMR Serverless 与 AppConfig 的 REST API 都使用/applications路径会导致 JAX-RS 路由冲突。Floci 通过前置匹配过滤器 EmrServerlessRouteFilter.java 解决控制器内部实际注册在内部路径/_emrserverless/applications过滤器在请求匹配前检查路径是否以applications开头通过Host请求头以emr-serverless.开头或Authorization头包含/emr-serverless/aws4_request签名作用域识别 EMR Serverless 请求命中后将请求重写到内部路径实现路由分派。这意味着使用 AWS SDK、CLI 或 Terraform 时只要按照正常 EMR Serverless 服务名签发请求Host 为emr-serverless.localhost.localstack.cloud或签名作用域为emr-serverlessFloci 会自动正确路由对客户端完全透明。四、实战Application 生命周期操作4.1 CreateApplication创建 Application创建请求的合法负载至少需要三个字段缺失任一字段都会返回400 ValidationExceptionreleaseLabel如emr-6.6.0type如SPARKclientToken幂等令牌curl -X POST http://localhost:4566/applications \ -H Content-Type: application/json \ -d { name: my-test-app, releaseLabel: emr-6.6.0, type: SPARK, clientToken: test-token }成功响应返回applicationId、arn与name{ applicationId: a1b2c3d4e5f6a7b8, arn: arn:aws:emr-serverless:us-east-1:000000000000:/applications/a1b2c3d4e5f6a7b8, name: my-test-app }从源码EmrServerlessService.java可确认以下行为必填校验releaseLabel、type、clientToken三者均强制校验违反时抛出AwsException(ValidationException, ..., 400)幂等创建若已存在使用相同clientToken的 Application直接返回已有记录对应 AWS 的幂等语义测试 EmrServerlessIntegrationTest.java 验证了这一点ID 生成使用UUID.randomUUID()去掉连字符后取前 16 位作为applicationIdARN 构造ARN 形如arn:aws:emr-serverless:{region}:{accountId}:/applications/{id}region 与 accountId 取自请求上下文RequestContext缺省时回退到配置的默认值初始状态新建 Application 状态为CREATEDstateDetails为空字符串并记录createdAt/updatedAt时间戳。此外创建时可附带更丰富的配置字段见 Application.java包括architecture、initialCapacity、maximumCapacity、autoStartConfiguration、autoStopConfiguration、networkConfiguration、imageConfiguration、workerTypeSpecifications等Floci 会完整存储并在查询时回显。4.2 ListApplications列表、状态过滤与分页curl http://localhost:4566/applications?statesCREATEDmaxResults10ListApplications 支持以下查询参数参数说明states按 Application 状态过滤可传多个值maxResults单页最大返回条数nextToken分页游标用于获取下一页源码EmrServerlessService.java实现要点先按states过滤出匹配状态的 Application再通过统一的Pagination.paginate机制按maxResults分页默认上限 50超限返回ValidationExceptionnextToken用于游标续页返回的条目为ApplicationSummary精简字段id、arn、name、releaseLabel、type、state、stateDetails、时间戳、architecture。集成测试 EmrServerlessIntegrationTest.java 验证了状态过滤与分页行为如maxResults1时返回 1 条且nextToken非空。4.3 GetApplication查询详情curl http://localhost:4566/applications/{applicationId}返回{application: {...}}其中包含applicationId、name、state、releaseLabel、type以及创建时设置的全部配置字段。若 Application 不存在返回404 ResourceNotFoundException见 EmrServerlessService.java。4.4 UpdateApplication更新配置curl -X PATCH http://localhost:4566/applications/{applicationId} \ -H Content-Type: application/json \ -d { releaseLabel: emr-6.7.0, initialCapacity: { DRIVER: { workerCount: 2, workerConfiguration: { cpu: 4 vCPU, memory: 16 GB } } }, monitoringConfiguration: { s3MonitoringConfiguration: { logUri: s3://my-bucket/logs } }, interactiveConfiguration: { studioEnabled: true } }更新行为的关键约束源码 EmrServerlessService.java仅允许在CREATED或STOPPED状态下更新否则返回400 ValidationExceptionApplication must be in a stopped or created state in order to be updated.与真实 AWS 语义一致采用部分更新语义请求中出现的字段才会覆盖未出现的字段保持不变可更新的字段包括releaseLabel、initialCapacity、maximumCapacity、autoStartConfiguration、autoStopConfiguration、networkConfiguration、architecture、imageConfiguration、workerTypeSpecifications、monitoringConfiguration、runtimeConfiguration、schedulerConfiguration、diskEncryptionConfiguration、interactiveConfiguration、identityCenterConfiguration、jobLevelCostAllocationConfiguration更新后刷新updatedAt时间戳并持久化。集成测试 EmrServerlessIntegrationTest.java 完整演示了更新后通过 GetApplication 回读验证releaseLabel、monitoringConfiguration、interactiveConfiguration均已生效。4.5 Start / Stop启停 Applicationcurl -X POST http://localhost:4566/applications/{applicationId}/start curl -X POST http://localhost:4566/applications/{applicationId}/stop启动与停止的逻辑非常简洁EmrServerlessService.javastart若当前已是STARTED或STARTING则直接返回幂等否则将状态置为STARTEDstop若当前已是STOPPED或STOPPING则直接返回否则将状态置为STOPPED两者均刷新updatedAt并持久化。集成测试验证了启动后GET /applications/{id}的application.state为STARTED停止后为STOPPED。4.6 DeleteApplication删除curl -X DELETE http://localhost:4566/applications/{applicationId}删除同样有状态约束仅CREATED或STOPPED状态的 Application 可删除否则返回400 ValidationException源码 EmrServerlessService.java。删除后再次查询返回404。4.7 状态机小结Floci 模拟的 Application 状态机可归纳为创建 → CREATED初始状态 ├─ start → STARTED └─ stop / 再次 stop → STOPPED 更新 / 删除仅允许在 CREATED 或 STOPPED 状态下执行STARTING、STOPPING等过渡状态在代码中仅作为幂等判断条件存在实际状态切换是瞬时完成的详见下文限制与差异。五、持久化与存储后端Floci 的 EMR Serverless 数据通过统一的存储工厂持久化EmrServerlessService.javathis.storage storageFactory.create(emrserverless, emr-serverless-applications.json, new TypeReferenceMapString, Application() {});存储介质为AccountAwareStorageBackendApplication账号感知存储后端即数据按 AWS 账号隔离数据文件名为emr-serverless-applications.json存储层支持mode配置可选与flushIntervalMs默认 5000ms 刷新间隔相关配置定义见 EmulatorConfig.java。这意味着 Application 的元数据在模拟器重启后依然保留满足测试中断续使用的场景。六、Limitations and Differences from AWS限制与差异原文档明确列出了 Floci EMR Serverless 模拟器与真实 AWS 的差异理解这些边界对正确使用至关重要Jobs 未实现Jobs not implementedFloci 只支持Application管理面的预置足以满足 Terraform 的aws_emrserverless_application资源通过StartJobRun提交真实 Spark/Hive 作业并未实现。也就是说模拟器适合做资源编排与生命周期验证无法执行实际的数据分析任务。瞬时启停Instant Start/StopFloci 在调用 start/stop 时立即将 Application 标记为STARTED或STOPPED不会在后台预置任何真实计算容量。这一设计取舍是为了满足 IaC 工具对状态机的快速断言需求而非真实计算资源的模拟。无数据面Data PlaneFloci不实现 contenteditable="false">【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址: https://gitcode.com/gh_mirrors/fl/floci创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考