AWS Elastic Beanstalk Kotlin SDK 示例:应用与环境全生命周期实战指南
AWS Elastic Beanstalk Kotlin SDK 示例:应用与环境全生命周期实战指南
本指南以仓库中 kotlin/services/elasticbeanstalk 目录下的官方示例为主体,系统讲解如何通过 AWS SDK for Kotlin 的 ElasticBeanstalkClient 创建、描述、配置与删除 Elastic Beanstalk 应用和环境,并配套讲解基于 JUnit 5 的自动化测试方案与 Gradle 构建配置。读者学完后可以独立编写和运行一套覆盖"创建 → 查询 → 删除"的 Elastic Beanstalk 全生命周期管理程序,并能复现仓库内的测试流程。
AWS Elastic Beanstalk 是一种"开箱即用"的应用部署与自动扩缩服务:你只需上传应用代码,平台便会自动完成容量供给、负载均衡、健康检查与自动扩缩等基础设施编排。本文中的 Kotlin 示例正是用代码方式驱动这一过程的完整样例。
示例总览
本示例目录(kotlin/services/elasticbeanstalk)共包含 6 个单操作示例,均基于 ElasticBeanstalkClient 实现:
| 示例 | 调用的 Elastic Beanstalk 命令 | 对应源文件 |
|---|---|---|
| 创建 Elastic Beanstalk 应用 | CreateApplication |
CreateApplication.kt |
| 创建 Elastic Beanstalk 环境 | CreateEnvironment |
CreateEnvironment.kt |
| 删除 Elastic Beanstalk 应用 | DeleteApplication |
DeleteApplication.kt |
| 描述 Elastic Beanstalk 应用 | DescribeApplications |
DescribeApplications.kt |
| 描述配置选项 | DescribeConfigurationOptions |
DescribeConfigurationOptions.kt |
| 描述 Elastic Beanstalk 环境 | DescribeEnvironment |
DescribeEnvironment.kt |
这 6 个操作按使用频率组成两条主线:资源创建(应用 → 环境)与状态查询/清理(描述应用 → 描述环境 → 描述配置 → 删除应用),与仓库中的 JUnit 测试顺序完全对应。
架构要点:应用与环境的层级关系
从源码结构看,Elastic Beanstalk 的资源模型分两层:
- 应用(Application):逻辑容器,保存应用名称、描述与版本信息,本身不承载计算资源;
- 环境(Environment):隶属于某个应用,承载实际运行的 EC2 实例、负载均衡器、自动扩缩组等基础设施,每个应用可同时运行多个环境(如 dev/prod)。
在 CreateEnvironment.kt 的请求构造中可以看到这一关系被显式表达:CreateEnvironmentRequest 必须同时指定 applicationName 与 environmentName,即"在哪个应用下创建哪个环境"。
环境准备与安全须知
前置条件
运行示例前需完成两件事:
- 安装并配置 AWS SDK for Kotlin 开发环境:包括 Kotlin 编译器、Gradle 以及 AWS 凭证。官方入门步骤参见 AWS SDK for Kotlin 开发者指南的 Get started 章节。
- 准备 AWS 凭证与区域:示例代码通过
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }从环境变量/凭证链读取凭证,并固定使用us-east-1区域(详见下文源码分析)。
费用与安全警告
- 这些示例会对你凭证所对应的 AWS 账户和区域执行真实操作,运行可能会产生账户费用,具体费用参见 AWS 定价页面;
- 运行 JUnit 测试同样可能产生费用;
- 强烈建议遵循最小权限原则:仅为任务授予所需的最低权限,参见 IAM 最佳实践中的 Grant least privilege;
- 本示例代码并未在所有 AWS 区域做过测试,跨区域使用前请确认目标服务在该区域的可用性,参见 AWS Regional Services 页面。
创建应用与环境:核心源码逐行解析
创建应用(CreateApplication)
CreateApplication.kt 的命令行用法为:
Usage:
<appName>
Where:
appName - The name of the AWS Elastic Beanstalk application.
核心逻辑位于 createApp 函数:
suspend fun createApp(appName: String?): String {
val applicationRequest =
CreateApplicationRequest {
description = "An AWS Elastic Beanstalk app created using the AWS SDK for Kotlin"
applicationName = appName
}
var tableArn: String
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
val applicationResponse = beanstalkClient.createApplication(applicationRequest)
tableArn = applicationResponse.application?.applicationArn.toString()
}
return tableArn
}
关键点说明:
- 请求构造:
CreateApplicationRequest仅需applicationName(必填)与description(可选描述)。示例中描述为创建时生成的固定文案; - 客户端创建:
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }是 SDK for Kotlin 的标准构造方式,凭证来自环境配置(AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY等或共享凭证文件),region通过构建器 lambda 指定; - 资源释放:
.use { ... }扩展函数确保客户端在作用域结束时自动关闭底层 HTTP 连接; - 返回值:从响应
applicationResponse.application?.applicationArn中提取新应用 ARN 并打印。注意此处使用了 Kotlin 空安全操作符?.,当响应中缺少 application 对象时返回"null"字符串; - 挂起函数:
createApp声明为suspend,因为 SDK for Kotlin 的所有 API 调用都是基于协程的挂起函数,只能在协程或main挂起函数中调用。
创建环境(CreateEnvironment)
创建环境比创建应用复杂得多,因为它需要指定解决方案栈与实例配置。CreateEnvironment.kt 用法:
Usage:
<envName> <appName>
Where:
envName - The name of the AWS Elastic Beanstalk environment.
appName - The name of the AWS Elastic Beanstalk application.
核心逻辑:
suspend fun createEBEnvironment(
envName: String?,
appName: String?,
): String {
val setting1 =
ConfigurationOptionSetting {
namespace = "aws:autoscaling:launchconfiguration"
optionName = "IamInstanceProfile"
value = "aws-elasticbeanstalk-ec2-role"
}
val applicationRequest =
CreateEnvironmentRequest {
description = "An AWS Elastic Beanstalk environment created using the AWS SDK for Kotlin"
environmentName = envName
solutionStackName = "64bit Amazon Linux 2 v3.2.12 running Corretto 11"
applicationName = appName
optionSettings = listOf(setting1)
}
var envArn: String
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
val applicationResponse = beanstalkClient.createEnvironment(applicationRequest)
envArn = applicationResponse.environmentArn.toString()
}
return envArn
}
逐参数说明:
solutionStackName:指定平台栈,示例使用64bit Amazon Linux 2 v3.2.12 running Corretto 11,即基于 Amazon Linux 2、运行 Corretto 11(OpenJDK 发行版)的 64 位平台。该字符串需与 Elastic Beanstalk 当前支持的平台列表精确匹配,否则调用会失败;optionSettings:通过ConfigurationOptionSetting列表注入自定义配置。示例设置了一个经典选项:namespace = "aws:autoscaling:launchconfiguration":自动扩缩启动配置命名空间;optionName = "IamInstanceProfile":指定环境中的 EC2 实例使用的 IAM 实例配置文件;value = "aws-elasticbeanstalk-ec2-role":使用 Elastic Beanstalk 默认服务角色aws-elasticbeanstalk-ec2-role(该角色需提前在 IAM 中创建并附加 Beanstalk 托管策略,否则环境创建可能失败);
- 返回值:从
applicationResponse.environmentArn提取环境 ARN。
客户端构造方式对比
两个创建示例都使用了 ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" },这与 DescribeApplications.kt 中直接使用 ElasticBeanstalkClient { region = "us-east-1" } 略有不同:前者显式指定从环境解析配置,后者使用默认配置链。二者在实际凭证解析行为上等效,均可从标准 AWS 凭证链读取凭证。
查询与配置描述:读取 Beanstalk 状态
描述应用与环境(DescribeApplications)
DescribeApplications.kt 演示了一个串联查询模式:先列出所有应用,再针对每个应用查询其环境列表:
suspend fun describeApps() {
ElasticBeanstalkClient { region = "us-east-1" }.use { beanstalkClient ->
val response = beanstalkClient.describeApplications(DescribeApplicationsRequest {})
response.applications?.forEach { app ->
println("The application name is ${app.applicationName}")
val desRequest =
DescribeEnvironmentsRequest {
applicationName = app.applicationName
}
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
val res = beanstalkClient.describeEnvironments(desRequest)
res.environments?.forEach { desc ->
println("The environment ARN is ${desc.environmentArn}")
}
}
}
}
}
该示例展示了 SDK for Kotlin 的两个惯用特性:
- 空安全迭代:
response.applications?.forEach { ... }对可能为空的集合使用安全调用链; - 请求过滤:
DescribeEnvironmentsRequest { applicationName = ... }只返回指定应用下的环境,配合environmentNames/environmentIds等过滤字段可精确控制返回范围。
描述单个环境(DescribeEnvironment)
DescribeEnvironment.kt 按应用名过滤环境:
suspend fun describeEnv(appName: String) {
val request =
DescribeEnvironmentsRequest {
environmentNames = listOf(appName)
}
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
val res = beanstalkClient.describeEnvironments(request)
res.environments?.forEach { env ->
println("The environment name is ${env.environmentName}")
println("The environment ARN is ${env.environmentArn}")
}
}
}
environmentNames 接受一个字符串列表,可一次查询多个环境。注意该示例的用法文本将参数描述为"应用名称",而实际请求字段为 environmentNames,从代码行为看它直接将该值作为环境名列表传入——运行时请传入环境名而非应用名。
描述配置选项(DescribeConfigurationOptions)
DescribeConfigurationOptions.kt 用于查询环境的可配置项,用法:
Usage:
<envName>
Where:
envName - The name of the AWS Elastic Beanstalk environment.
suspend fun getOptions(envName: String) {
val spec =
OptionSpecification {
namespace = "aws:ec2:instances"
}
val request =
DescribeConfigurationOptionsRequest {
environmentName = envName
options = listOf(spec)
}
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
val res = beanstalkClient.describeConfigurationOptions(request)
res.options?.forEach { option ->
println("The namespace is ${option.namespace}")
val optionName = option.name
println("The name is $optionName")
if (optionName != null) {
if (optionName.compareTo("InstanceTypes") == 0) {
val valueOptions = option.valueOptions
valueOptions?.forEach { value ->
println("The value is $value")
}
}
}
}
}
}
关键要素:
OptionSpecification:限定查询范围。namespace = "aws:ec2:instances"表示只查看 EC2 实例相关的命名空间;- 结果过滤:遍历返回的配置项,当
option.name等于InstanceTypes时,进一步枚举其valueOptions(该选项允许的全部取值,如t2.micro、t3.small等实例类型); - 用法价值:这类查询可用于编写自动化脚本——在创建环境前先探测某命名空间下合法的选项值,避免硬编码非法配置。
删除应用:注意破坏性操作
DeleteApplication.kt 执行的是破坏性操作,会删除整个应用:
suspend fun deleteApp(appName: String?) {
val applicationRequest =
DeleteApplicationRequest {
applicationName = appName
terminateEnvByForce = true
}
ElasticBeanstalkClient.fromEnvironment { region = "us-east-1" }.use { beanstalkClient ->
beanstalkClient.deleteApplication(applicationRequest)
println("The Elastic Beanstalk application was successfully deleted!")
}
}
重点提醒:
terminateEnvByForce = true:该参数要求同时强制终止应用下所有运行中的环境。若置为false且应用下仍有关联环境,删除请求可能失败;- 破坏性提示:本示例会删除 AWS 资源,运行前务必确认操作对象。建议使用独立测试专用资源进行实验,避免影响生产环境;
- 从仓库测试可以看到,删除前特意
TimeUnit.MINUTES.sleep(5)等待 5 分钟,确保环境有足够时间进入可删除状态(详见下节)。
使用 JUnit 5 自动化测试:ElasticBeanstalkTest
仓库为全部 6 个操作配套了端到端测试文件 ElasticBeanstalkTest.kt,基于 JUnit 5 与 kotlinx.coroutines.runBlocking 将挂起函数接入 JUnit 测试方法。
测试结构与执行顺序
测试类通过注解控制生命周期与顺序:
@TestInstance(TestInstance.Lifecycle.PER_CLASS):类级别单实例,允许@BeforeAll非静态方法初始化;@TestMethodOrder(OrderAnnotation::class)配合@Order(1..7):按顺序执行 7 个测试,形成完整的资源生命周期。
@BeforeAll
fun setUp() {
val random = Random()
val randomNum = random.nextInt(10000 - 1 + 1) + 1
appName = appName + randomNum
envName = envName + randomNum
}
setUp() 为应用名/环境名追加 1~10000 的随机后缀(如 TestApp1234),避免与既有资源冲突,同时保证测试可重复执行。
7 个测试用例及其断言逻辑:
| 顺序 | 测试方法 | 行为 | 断言 |
|---|---|---|---|
| 1 | whenInitializingAWSService_thenNotNull |
校验初始化 | appName 非空 |
| 2 | createApp |
创建应用 | 返回的 appArn 非空 |
| 3 | createEnvironment |
创建环境 | 返回的 envArn 非空 |
| 4 | describeApplications |
描述应用及环境 | 无断言,仅打印 |
| 5 | describeEnvironment |
描述环境 | 无断言,仅打印 |
| 6 | describeOptions |
查询配置选项 | 无断言,仅打印 |
| 7 | deleteApplication |
先等待 5 分钟后删除应用 | 无断言,仅打印 |
每个测试通过 SLF4J 日志输出 Test N passed。例如第 3 个测试执行成功时,控制台会显示:
Test 3 passed
其中第 7 个测试的 5 分钟等待(TimeUnit.MINUTES.sleep(5))是因为环境创建/终止本身耗时较长,直接删除可能因环境仍处于 Terminating 或 Updating 状态而失败——这是编写 Beanstalk 集成测试时需要注意的真实时序问题。
运行测试
测试可从 IDE(如 IntelliJ IDEA)直接运行,也可通过 Gradle 命令行执行:
gradle test
构建配置见 kotlin/services/elasticbeanstalk/build.gradle.kts,其中关键配置包括:
- Kotlin/JVM 2.1.0 插件 +
application插件,sourceCompatibility/targetCompatibility为 Java 17,kotlinOptions.jvmTarget = "17"; - 依赖通过 AWS SDK for Kotlin BOM 管理:
implementation(platform("aws.sdk.kotlin:bom:1.5.63"))锁定版本,随后引入aws.sdk.kotlin:elasticbeanstalk(本示例核心模块)与aws.sdk.kotlin:secretsmanager; - HTTP 引擎:
aws.smithy.kotlin:http-client-engine-okhttp与http-client-engine-crt; - 测试依赖:
org.junit.jupiter:junit-jupiter:5.9.2,配合tasks.test { useJUnitPlatform() }启用 JUnit Platform; - ktlint:应用
org.jlleitschuh.gradle.ktlint:11.3.1插件进行代码风格检查。
运行测试前的必要配置(config.properties)
仓库源码中所有代码示例都从 AWS 凭证链读取凭证,且测试使用的应用名/环境名在 ElasticBeanstalkTest.kt 中由随机数自动生成,因此若全部配置项齐备,测试即可直接运行。
原 README 提示在运行 JUnit 测试前,需要在 resources 文件夹的 config.properties 文件中定义所需值;若未定义全部值,JUnit 测试会失败。需要配置的键为:
- appName - 应用的名称。
- envName - 环境的名称。
注意:在当前仓库的该目录结构中,未提供现成的 config.properties 文件与 resources 目录,测试代码也改为在 setUp() 中动态生成名称。因此实际运行时,请结合本地源码版本判断:若你的代码从 properties 文件读取名称,则必须先补齐上述两个键;若采用本仓库随机命名方案,则重点确保凭证与区域配置正确即可。
测试运行的注意事项
- 会产生真实资源与费用:
createApplication、createEnvironment会真实创建 Beanstalk 应用与环境,请确保在具备权限且预算可控的账户下运行; - 耗时较长:第 7 个测试内置 5 分钟等待,整套测试预计耗时超过 5 分钟,属于正常现象;
- 失败排查顺序:若测试失败,优先检查 ① AWS 凭证是否有效;②
aws-elasticbeanstalk-ec2-role等 IAM 角色是否存在;③ 指定区域是否支持所用平台栈。
从零到一的调用链总结
综合源码,一次完整的 Beanstalk 资源生命周期调用链为:
createApplication → createEnvironment → describeApplications
→ describeEnvironments → describeConfigurationOptions → deleteApplication(terminateEnvByForce=true)
SDK for Kotlin 侧的统一底座是 ElasticBeanstalkClient:所有请求对象(CreateApplicationRequest、CreateEnvironmentRequest、DescribeEnvironmentsRequest、DeleteApplicationRequest 等)都通过 Kotlin 构建器 DSL 构造,所有调用均为挂起函数,配合 .use {} 自动管理客户端生命周期——这与仓库内其他 Kotlin 服务示例(如 glue、dynamodb 目录)保持一致的代码风格。
扩展阅读
- 本示例完整源码与构建配置:kotlin/services/elasticbeanstalk;
- AWS SDK for Kotlin 开发者指南(Get started 与 setup 章节),用于环境搭建与凭证配置;
- AWS Elastic Beanstalk 开发者指南,用于理解平台栈、配置命名空间与托管策略的细节。
版权声明:本仓库示例代码遵循 Apache-2.0 License(Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.)。