部署
由SSM参数存储器支持的单一应用程序配置值.
何时使用 : 您需要一个不敏感的配置值( 地标, API URL, 阈值) 作为单个 SSM 参数存储 。 每个 AppSetting 实例映射到一个参数.
不使用时 : 对于生产密钥( API 密钥、 OAuth 客户端密钥、 数据库连接字符串、 令牌) , 使用 Secret 是推荐的家 证书保护生产应用, 符合AWS指南的。 。 。 . AppSetting 与 secret: true 在休息时加密该值, 并且是免费的, 所以它是一个精细的倒置 低值 在一个原型中的秘密——但这不是生产秘密的推荐地点. 如果您需要结构化的密钥值数据并附带条件的写和查询,请使用 KVStore 或者说 DistributedTable。 。 。 .
设计与模拟等价细节 : 设计
API 密码
const setting = new AppSetting(scope, id, options)
| 方法 | 回返 | 说明 |
|---|---|---|
get() | Promise<T> | 读取当前值 . |
put(value) | Promise<void> | 运行时更新值 . |
选项
| 选项 | 类型 | 需求 | 说明 |
|---|---|---|---|
name | string | 没有 | SSM 参数路径. 省去时,取自瞄准树 /${fullId},保证堆内的独特性. |
value | T | 没有 | 初标相. 非秘密参数需要。 不得在 secret 已经设定. |
schema | StandardSchemaV1<T> | 没有 | 运行时验证计划 (Zod, Valibot, ArkType). 推断 T 从计划。 无法使用 secret。 。 。 . |
secret | boolean | 没有 | 何时 true,以默认设置创建 SSM 安全串 aws/ssm KMS 密钥( 或 kmsKeyArn (设定时). 无法使用 schema 或者说 value对于生产秘密,更喜欢 Secret (AWS 秘密管理器)——参见 不使用时 见上文. |
kmsKeyArn | string | 没有 | 客户管理的 KMS 密钥的 ARN 加密安全链, 而不是默认 aws/ssm 键。 仅有效 secret: true. 见下文注释. |
logger | ChildLogger | 没有 | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |
客户管理的 KMS 密钥
kmsKeyArn: 提供一个CMK ARN来控制 秘密的解密/授予范围(例如交叉账户访问或专用密钥) (政策)。 构造允许共享处理器kms:Decrypt(单位:千美元)kms:Encrypt关键是ARN 因为AWS Blocks没有你的钥匙, 关键的关键政策也必须 允许应用程序的 Lambda 执行角色 (或通过 账户根报表 CDK 添加到同账户密钥中。 添加或更改kmsKeyArn在已部署的秘密中重新加密当前值 下一次部署时的新密钥, 所以解密继续工作.
名称 : 省略时
name,这个框架从 构造范围树( e)/${fullId}) (中文(简体) ). 这是建议的办法——它 自动防止相撞堆栈。 如果你提供明确name, (中文(简体) ), 你们 负责确保它在所有堆栈中独一无二 部署在同一AWS账户和区域.
处理错误
import { isBlocksError } from '@aws-blocks/core';
import { AppSettingErrors } from '@aws-blocks/bb-app-setting';
try {
await setting.put(value);
} catch (e: unknown) {
if (isBlocksError(e, AppSettingErrors.ValidationFailed)) {
// schema validation failed or value exceeds 4 KB
}
throw e;
}
try {
const value = await setting.get();
} catch (e: unknown) {
if (isBlocksError(e, AppSettingErrors.ParameterNotFound)) {
// the parameter is missing (e.g., deleted out-of-band) or a secret has an empty value
}
throw e;
}
get() 可以抛出 AppSettingErrors.ParameterNotFound 当参数不存在或者一个秘密参数有空值时(在AWS和模拟运行时).
实例
普通字符串设置
// Recommended: let the framework manage the SSM name (unique by default)
const apiUrl = new AppSetting(scope, 'apiUrl', {
value: 'https://api.example.com',
});
export const api = new ApiNamespace(scope, 'api', (context) => ({
async getApiUrl() {
return { url: await apiUrl.get() };
},
async setApiUrl(url: string) {
await apiUrl.put(url);
},
}));
用 Schema 键入对象
import { z } from 'zod';
const config = new AppSetting(scope, 'config', {
value: { maxRetries: 3, timeout: 5000 },
schema: z.object({ maxRetries: z.number(), timeout: z.number() }),
});
export const api = new ApiNamespace(scope, 'api', (context) => ({
async getConfig() {
return await config.get(); // { maxRetries: number; timeout: number }
},
async updateConfig(cfg: { maxRetries: number; timeout: number }) {
await config.put(cfg); // validated against schema
},
}));
秘诀
const stripeKey = new AppSetting(scope, 'stripeKey', {
secret: true,
});
export const api = new ApiNamespace(scope, 'api', (context) => ({
async charge(amount: number) {
const key = await stripeKey.get(); // decrypted from SSM SecureString
// use key...
},
}));
明确名称( 交叉服务读取)
使用明确的 name 当SSM参数必须被其他服务所读取或遵循出名的路径公约时.
您必须保证这个名字在部署到 相同的AWS账户和区域以避免相撞.
const apiUrl = new AppSetting(scope, 'apiUrl', {
name: '/my-app/production/api-url',
value: 'https://api.example.com',
});
审定规则
它们是在CDK合成时间和本地开发中执行的(模拟在建筑中拒绝相同的组合):
secret+ 键schema~ 错误( 机密为平线)schema无value− 出错(参数需要一个有效的初始值)secret与value- 错误(不要在源代码中隐藏秘密)- 无机密
value出错(设置需要初始值)
缩放成本( AWS)
- 字符串参数 : 标准等级,免费,4 KB限额,每个账户/区域10,000
- 安全结构参数 : 标准等级, 免费, 加密
aws/ssmKMS 密钥 - 通过量 : GetParemeter 的40 TPS 默认值( 可增加)
- 延迟 : 读取和写出数位数
地方发展
模拟数据持续到磁盘 .bb-data/settings/{fullId}/value.json 跨 Dev 服务器重启 。 擦拭为 rm -rf .bb-data. 机密在当地生成随机值(没有模拟模式的 KMS 加密).