S3 호환 오브젝트 스토어 — 하나의 컴포넌트, 두 개의 대상, 필수 키 쌍
이 예제는 하나의 S3 호환 오브젝트 스토어, 즉 core/storage/s3-object-store 컴포넌트를 두 가지 자체 호스팅 구현으로 컴파일합니다.
- 로컬 개발용 Docker Compose(
compose/s3-object-store사용), 그리고 - Kubernetes에서 외부 차트 없이 동작하는 합성된 helm Recipe
helm/s3-object-store.
둘 다 프로젝트가 게시한 chrislusf/seaweedfs 이미지로 SeaweedFS(Apache-2.0)를 실행하며, 버킷 하나를 보유한 서버 프로세스 하나로 동작합니다. 버킷은 서버가 서비스를 시작하기 전에 생성됩니다. 같은 컴포넌트는 다른 Recipes에 의해 Amazon S3와 Google Cloud Storage에서도 구현되며, Manifest가 어떤 구현을 선택하든 소비자는 같은 게시된 엔드포인트, 버킷, 리전을 읽습니다.
컴포넌트의 두 키 슬롯 access_key_id와 secret_access_key는 선택 사항인데, 관리형 서비스는 버킷으로부터 키를 받지 않기 때문입니다. SeaweedFS는 이 쌍을 서버 자체의 S3 계정으로 받으며 기본값이 없으므로, 둘 중 한 슬롯이라도 비어 있으면 두 구현 모두 중단됩니다. aggregate.yaml은 아무것도 채우지 않으며 빌드가 중단되는 모습을 보여 줍니다. 나머지 두 Aggregates는 각 대상이 전달하는 형식으로 두 슬롯을 채웁니다. Compose 경로에는 aggregate-auth.yaml(환경 변수로 노출되는 inject-value 자격 증명), 합성된 helm 경로에는 aggregate-helm-synth-auth.yaml(Kubernetes Secret으로 구체화되는 참조 가능한 자격 증명)을 사용합니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | 개발자 의도: 버킷 media를 보유하는 core/storage/s3-object-store 타입의 store 컴포넌트 하나, 연결된 키 없음 — 이를 빌드하면 비어 있는 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가
/data에 볼륨 클레임이 마운트된 레플리카 하나짜리 StatefulSet, 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.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.
# 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}”(AWS_ACCESS_KEY_ID를 전달하는 자격 증명을 access_key_id에 연결하십시오. 예를 들어 키가 AWS_ACCESS_KEY_ID이고 origin이 ${AWS_ACCESS_KEY_ID} 같은 Compose 변수 참조인 core/secret-value입니다). 해결책은 나머지 두 Aggregates가 취하는 단계, 즉 store 컴포넌트의 features.access_key_id와 features.secret_access_key 각각에 자격 증명을 연결하는 것입니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 폴더를 직접 만들지 마십시오. 작업 영역 폴더에 아직 `s3-object-store` 폴더가 없으면 `example`을 `s3-object-store` 값으로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `s3-object-store` 폴더에 예제가 작성됩니다. 그런 다음 각 Release마다 한 번씩, `release-compose-auth.yaml`, `release-helm-synth-auth.yaml` 순서로 `build` 도구를 호출하십시오. 매번 `workspace_root`를 `s3-object-store` 값으로, `release`를 해당 파일로, `auto_pull`을 true로, `write`를 true로 설정합니다. 이어서 `release`를 `release-helm-synth.yaml` 값으로 설정하여 같은 방식으로 `build` 도구를 호출하십시오. 이 호출은 거부되도록 되어 있으므로 거부 내용을 읽어 주십시오. 처음 두 빌드가 작성한 파일을 알려 주십시오. 파일은 `s3-object-store/dist/` 아래에 있습니다.자격 증명 전달 참고
Compose 경로에서 각 키는 inject-value 시크릿입니다(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을 실행합니다.