兼容 S3 的对象存储——一个组件、两个目标、一对必需的密钥
本示例将一个兼容 S3 的对象存储,即 core/storage/s3-object-store 组件,编译为它的两种自托管实现:
- 用于本地开发的 Docker Compose,通过
compose/s3-object-store,以及 - Kubernetes 上的合成 helm Recipe
helm/s3-object-store,无需外部 chart。
两者都使用其项目发布的 chrislusf/seaweedfs 镜像运行 SeaweedFS(Apache-2.0),作为一个持有一个存储桶的服务器进程,该存储桶在服务器开始服务之前创建。同一组件在 Amazon S3 和 Google Cloud Storage 上由其他 Recipes 实现;无论 Manifest 选择哪种实现,消费者读取的都是相同的已发布端点、存储桶和区域。
该组件的两个密钥槽位 access_key_id 和 secret_access_key 是可选的,因为托管服务不从存储桶获取密钥。SeaweedFS 将这对密钥作为服务器自身的 S3 账户,且没有默认值,因此只要任一槽位为空,它的两种实现都会中止。aggregate.yaml 未填充任何内容,展示了构建中止的情形;另外两个 Aggregates 按各目标的交付形式填充两个槽位:aggregate-auth.yaml 用于 Compose 路径(以环境变量形式呈现的 inject-value 凭据),aggregate-helm-synth-auth.yaml 用于合成的 helm 路径(物化为 Kubernetes Secret 的可引用凭据)。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:一个类型为 core/storage/s3-object-store 的 store 组件,持有存储桶 media,未附加任何密钥——对其构建会中止,并指出空的 access_key_id 槽位。 |
aggregate-auth.yaml | 同一存储,两个密钥都作为 inject-value 凭据附加(Compose 路径)。 |
aggregate-helm-synth-auth.yaml | 同一存储,为合成的 helm 路径将两个密钥都作为可引用凭据附加——每个密钥都被物化为 StatefulSet 所引用的 Kubernetes Secret。 |
manifest-compose.yaml | 将存储类型映射到 Compose Recipe(compose/s3-object-store),并将凭据映射到 dotenv-secret。 |
manifest-helm-synth.yaml | 将存储类型映射到合成的 helm Recipe(helm/s3-object-store),并将凭据映射到 k8s-secret-from-parameter。 |
release-compose.yaml / release-helm-synth.yaml | aggregate.yaml 两种实现的运维记录;它未附加密钥,因此每次构建都会中止。 |
release-compose-auth.yaml / release-helm-synth-auth.yaml | 填充了两个槽位的两个 Aggregates 的运维记录。 |
演示内容
- 一个组件,多种实现。 Aggregate 指定存储桶,而不涉及服务器的任何信息。每个 Manifest 说明如何实现该存储,而改为选择托管实现的 Manifest 会将同一个 Aggregate 部署到 Amazon S3 或 Cloud Storage。
- 存储桶随存储一同提供。 开发者的
values.bucket是该存储持有并发布的存储桶。Kubernetes 上的一个 init 容器和 Compose 上的一个 init 服务会在服务器开始服务之前创建它,并保留已存在的存储桶不变,因此消费者永远不会遇到没有存储桶的存储。SeaweedFS 不接受的存储桶名称会使构建中止,并指出相应规则。 - 单个卷上的有状态服务器。 在 Kubernetes 上,合成的 Recipe 渲染出一个单副本的 StatefulSet,其卷声明挂载在
/data,以及一个 ClusterIP Service 和该 StatefulSet 所指定的 headless Service;在 Compose 上,服务在同一路径挂载一个命名卷,并在主机上发布 S3 端口。 - 一对没有默认值的必需密钥。 存在账户时,SeaweedFS 会对每个 S3 请求进行身份验证,因此不能用目录的每位读者都持有的密钥来代替。每个 Recipe 都会在渲染任何内容之前因槽位为空而中止,并指出该槽位以及应附加什么。附加的这对密钥成为服务器的账户,而私密密钥同时也是服务器的 filer 签名密钥,因此 S3 端口旁的 gRPC 端口同样不接受未经身份验证的更改。
- 消费者读取的内容。 该存储发布
bucket、endpoint(Kubernetes 上为http://store-default:8333,Compose 上为http://store:8333)、host、port8333、protocols3和regionus-east-1,即 S3 客户端从不报告区域的服务器读取的区域。连接到它的消费者将其 S3 客户端指向该端点,并在自己的连接上出示一对密钥。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example s3-object-store然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd s3-object-store构建
此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:
# Local development (Docker Compose)aggrega build --release release-compose-auth.yaml --auto-pull
# Kubernetes (synthesized helm Recipe)aggrega build --release release-helm-synth-auth.yaml --auto-pull渲染产物位于 dist/ 下。
构建未附加密钥的 aggregate.yaml 时,在任一目标上都会在渲染任何内容之前中止:
aggrega build --release release-helm-synth.yaml --auto-pull[… omitted: the pull's lines, which report the same halt, and a lint notice][CATALOG_ERROR E0033] Recipe/FeatureRecipe assertions caused by: Recipe "s3-object-store" instance "store" assertion "key_slots_filled": assertion "Recipe/s3-object-store/store/key_slots_filled": template: Recipe/s3-object-store/store/key_slots_filled:1:138: executing "Recipe/s3-object-store/store/key_slots_filled" at <fail (printf "the %s slot is empty, and SeaweedFS takes the access_key_id and secret_access_key pair as the account its S3 API authenticates every request by, so there is no default for either: attach a referenceable credential, such as core/referenced-secret, to %s" $slot $slot)>: error calling fail: assertion failed: the access_key_id slot is empty, and SeaweedFS takes the access_key_id and secret_access_key pair as the account its S3 API authenticates every request by, so there is no default for either: attach a referenceable credential, such as core/referenced-secret, to access_key_idrelease-compose.yaml 因同一断言中止,其补救说明指出了 Compose 路径所采用的形式:“attach a credential to access_key_id delivering AWS_ACCESS_KEY_ID, such as core/secret-value with key AWS_ACCESS_KEY_ID and its origin a Compose variable reference such as ${AWS_ACCESS_KEY_ID}”(为 access_key_id 附加一个传递 AWS_ACCESS_KEY_ID 的凭据,例如键为 AWS_ACCESS_KEY_ID、origin 为 Compose 变量引用(如 ${AWS_ACCESS_KEY_ID})的 core/secret-value)。修复方法就是另外两个 Aggregates 所采取的步骤:在 store 组件的 features.access_key_id 和 features.secret_access_key 下各附加一个凭据。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
仅使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `s3-object-store` 文件夹,请调用一次 `scaffold` 工具,将 `example` 设为 `s3-object-store`,且不设 `dir`:它会把示例写入新的 `s3-object-store` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-compose-auth.yaml` 和 `release-helm-synth-auth.yaml`——每次都将 `workspace_root` 设为 `s3-object-store`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。然后以同样方式调用 `build` 工具,将 `release` 设为 `release-helm-synth.yaml`:这次调用本应被拒绝,所以请把拒绝信息读给我听。告诉我前两次构建写入了哪些文件;它们位于 `s3-object-store/dist/` 下。凭据传递说明
在 Compose 路径上,每个密钥都是一个 inject-value secret(aggregate-auth.yaml):其值通过组件的环境管道,以其 values.key 指定的变量 AWS_ACCESS_KEY_ID 或 AWS_SECRET_ACCESS_KEY 传递,这正是 Recipe 交给服务器的变量;以任何其他名称传递的附加项会使构建中止,并指出该槽位。每个 origin 都是一个 Compose 变量引用,因此渲染出的文件携带的是引用而不是密钥:
environment: AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID} AWS_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY} WEED_JWT_FILER_SIGNING_KEY: ${S3_SECRET_ACCESS_KEY}合成的 helm 路径使用可引用凭据(aggregate-helm-synth-auth.yaml):每个密钥都被物化为一个以组件和槽位命名的 Kubernetes Secret,StatefulSet 通过 env secretKeyRef 引用它,因此两个密钥都不会出现在 StatefulSet 清单中——只存在于 Secret 中:
env: - name: AWS_ACCESS_KEY_ID valueFrom: secretKeyRef: name: store-access-key-id key: access-key-id - name: AWS_SECRET_ACCESS_KEY valueFrom: secretKeyRef: name: store-secret-access-key key: secret-access-key - name: WEED_JWT_FILER_SIGNING_KEY valueFrom: secretKeyRef: name: store-secret-access-key key: secret-access-keyaggregate-helm-synth-auth.yaml 中的 origin 值是开发用占位符,会原样写入生成的 Secret。对于承载真实流量的 Release,请改为将 core/referenced-secret 映射到 k8s-existing-secret,并让每个 origin 指定一个已存在于命名空间中、并在附加项的 key 下持有该密钥的 Secret。
运行(Compose)
aggrega build --release release-compose-auth.yaml --auto-pullexport S3_ACCESS_KEY_ID=<an access key identifier of your choosing>export S3_SECRET_ACCESS_KEY=<a secret key of your choosing>docker compose -f dist/app/compose/docker-compose.yaml up -d存储桶服务创建 media 之后,S3 API 在 http://localhost:8333 上响应。使用导出的密钥对和区域 us-east-1,将任意 S3 客户端指向该地址。使用 docker compose -f dist/app/compose/docker-compose.yaml down 拆除。