만약 당신의 파일들이 이미 Amazon S3에 저장되어 있다면, 데이터베이스와 함께 브랜치(branch)를 생성하는 저장소라는 제안은 매력적이지만, "마이그레이션 (migration)"이라는 단어는 마치 거대한 프로젝트처럼 느껴지게 만듭니다. 하지만 실제로는 그렇지 않습니다. Neon의 오브젝트 스토리지 (object storage)는 S3 API를 지원하므로, 이미 작성한 코드, AWS SDK 호출, 그리고 서명된 URL (presigned URLs)이 그대로 작동합니다. 바뀌는 점은 클라이언트를 가리키는 방식과 버킷 (bucket)이 어디서 오는지에 대한 부분이며, 이는 작고 기계적인 차이일 뿐입니다. 실제 데이터 이동은 한 번만 실행하면 되는 복사 루프 (copy loop)입니다. 사전에 해야 할 한 가지는 앱이 실제로 의존하고 있는 오브젝트 작업 (object operations)을 확인하는 것입니다. 여기 데모에서는 PutObject, GetObject, 리스팅 (listing), 그리고 서명된 URL (presigned URLs)을 실행하며, 아래쪽에서 직접 확인해야 할 S3 기능들을 표시해 두었습니다.

이 포스트는 실무적인 버전입니다. 무엇이 동일하게 유지되는지, 정확히 어떤 설정이 바뀌는지, 오브젝트를 복사하기 위한 스크립트, 그리고 확정하기 전에 무엇을 확인해야 할지 알 수 있도록 대응하는 기능이 없는 S3 기능 목록을 솔직하게 담았습니다. 작동하는 클라이언트가 포함된 repo는 마지막에 있습니다.

요약 (TL;DR)

• Neon 오브젝트 스토리지 (object storage)는 S3 호환(S3-compatible)입니다. 일반적인 작업인 PutObject, GetObject, getSignedUrl, 목록 조회(listing)를 위한 @aws-sdk/client-s3 코드는 변경 없이 작동합니다 (데모에서 검증하는 부분입니다). 대용량 객체를 위한 멀티파트 (multipart) 업로드와 같이 그 외의 기능은 현재 프리뷰(preview) 버전을 통해 확인하시기 바랍니다.
• 차이점은 클라이언트 설정에 있습니다: endpoint를 Neon 스토리지 엔드포인트로 지정하고, region: 'us-east-2'로 고정하며, forcePathStyle: true를 설정합니다. 버킷은 콘솔에서 생성하는 대신 neon.ts에서 선언됩니다. 또한 자격 증명(credentials)은 브랜치별로 주입됩니다.
• 두 개의 S3 클라이언트(소스 AWS, 대상 Neon) 사이에서 목록 조회 및 복사(list-and-copy) 루프를 사용하여 데이터를 이동합니다.
• 이전되지 않는 항목: S3 버킷 정책 (bucket policies), 이벤트 알림 (event notifications) 및 Lambda 트리거, 스토리지 클래스 (storage classes) 및 Glacier 전환, 그리고 교차 리전 복제 (cross-region replication)입니다. 객체 CRUD 및 사전 서명 (presigning)은 유지됩니다.
• 이 시리즈의 다른 모든 내용이 주는 보상은 다음과 같습니다: 파일이 Neon에 위치하게 되면, 데이터베이스와 함께 브랜치 (branch)됩니다.

요구 사항 (Prerequisites)

• 기존 S3 버킷 및 이를 읽을 수 있는 자격 증명 (credentials)
• 선언된 버킷(us-east-2)이 있는 플랫폼 프리뷰 (platform preview) 상의 Neon 프로젝트
• AWS SDK (@aws-sdk/client-s3, @aws-sdk/s3-request-presigner)

동일하게 유지되는 부분 (What stays the same)

안심하셔도 되는 부분입니다. 스토리지에 접근하는 애플리케이션 코드는 변경되지 않는데, 양쪽 모두 S3 API를 사용하기 때문입니다. 동일한 PutObjectCommand, GetObjectCommand, getSignedUrl 호출이 어느 저장소에 대해서도 실행됩니다. 유일한 차이점은 해당 호출을 어떤 클라이언트에 전달하느냐입니다.

• AWS S3:

import { S3Client } from '@aws-sdk/client-s3';

// AWS: region은 실제 리전이며, endpoint는 추론되고, 가상 호스트 스타일 (virtual-hosted style)입니다.
...

• Neon Storage

import { S3Client } from '@aws-sdk/client-s3';

// Neon: 명시적 엔드포인트 (explicit endpoint), 고정된 리전 (pinned region), 경로 스타일 (path-style). 자격 증명은 ... 에서 가져옵니다.
...

변경되는 차이점 (The diff that changes)

세 가지 설정 차이점과 두 가지 운영상의 차이점은 다음과 같습니다:

• endpoint. AWS는 지역(region)으로부터 이를 추론하지만, Neon의 경우 주입된 AWS_ENDPOINT_URL_S3로 명시적으로 설정해야 합니다.
• region. us-east-2로 고정하십시오. 런타임이 주입하는 AWS_REGION은 실제로는 스토리지 셀(storage-cell) 호스트이므로, SDK가 이를 지역으로 인식하지 못하고 거부합니다. 따라서 환경 변수에서 이를 읽어오지 마십시오.
• forcePathStyle: true. Neon 스토리지는 가상 호스트 방식(virtual-hosted, bucket.endpoint/key)이 아닌 경로 방식(path-style, endpoint/bucket/key)을 사용합니다.
• 버킷(bucket)의 출처. AWS 콘솔이나 Terraform에서 생성하는 대신, neon.ts의 preview.buckets 아래에 선언합니다. 버킷은 브랜치(branch)와 함께 프로비저닝됩니다.
• 자격 증명(Credentials). 환경 변수에 장기 보관용 액세스 키(access keys)를 두는 대신, neon deploy에 의해 브랜치별로 자격 증명이 주입됩니다. 이는 관리하고 교체해야 할 비밀값(secret)이 하나 줄어듦을 의미합니다.

객체 이동 (Moving the objects)

데이터 이동은 목록 나열 및 복사(list-and-copy) 루프 방식으로 이루어집니다. 소스 버킷의 목록을 나열하고, 각 객체를 AWS로부터 스트리밍하여 Neon에 저장(put)합니다. 두 개의 S3 클라이언트를 사용하여 하나는 읽고, 하나는 씁니다.

import { S3Client, ListObjectsV2Command, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';

const source = new S3Client({ region: 'us-east-1' }); // AWS
...

백필(backfill)을 위해 한 번 실행하고, 다운타임을 허용할 수 없는 경우 짧은 기간 동안 이중 쓰기(dual-writing)를 유지한 다음 읽기 작업을 전환하십시오. 이 루프의 목적지 측인 Neon으로의 PutObject는 데모에서 모든 업로드 시 수행하는 방식과 정확히 일치하므로 검증된 경로이며, 소스 측은 이미 운영 중인 표준 S3입니다.

전환(cut over)하기 전에 확인해야 할 두 가지가 있습니다. 첫째, 데이터베이스가 객체 키(object keys)가 아닌 전체 S3 URL을 저장하고 있다면, 해당 행들은 이전 호스트를 가리키게 됩니다. 키를 저장하는 방식으로 마이그레이션하거나 URL을 다시 작성하십시오. 둘째, 다른 어떤 것도 변경할 필요가 없도록 이동 과정에서 키를 동일하게 유지하십시오. 위의 루프(loop)가 이를 보존합니다.

이전되지 않는 사항

한계점을 솔직하게 파악하는 것이 운영 환경에서의 예기치 못한 상황을 방지합니다. 핵심 객체 작업(demo에서 연습하는 작업들)은 깔끔하게 이식됩니다. 하지만 대용량 객체(larger-object) 및 그와 관련된 S3 플랫폼 기능들은 아직 초기 프리뷰(early preview) 단계이며 기능이 계속 채워지는 중이므로, 의존하기 전에 프리뷰를 통해 확인해야 합니다:

만약 애플리케이션이 처리를 시작하기 위해 S3 이벤트(S3 events)에 의존하고 있다면, 이를 인라인(inline)으로 작업을 수행하거나 쓰기(write) 후에 작업을 큐에 넣는(enqueueing) 함수로 교체해야 합니다. Glacier 계층화(Glacier tiering)에 의존한다면, 이것은 해당 기능이 아닙니다. 업로드, 저장, 서빙, 그리고 이제는 브랜칭(branch)까지 이어지는 일반적인 사례의 경우, 이식 작업은 위의 설정 변경과 복사 루프(copy loop)를 더하는 것으로 충분합니다.

리포지토리 (The repo)

작동하는 Neon 스토리지 클라이언트(마이그레이션의 목적지 측, 그리고 직접 및 서명된 업로드(presigned uploads) 포함)는 여기에 있습니다:

https://github.com/The-DevOps-Daily/neon-storage-demo

마무리

S3 호환성 덕분에 이 작업은 코드 재작성이 아닌 설정 변경만으로 가능합니다. 여러분의 업로드 및 다운로드 코드는 차이점을 알지 못합니다. 클라이언트의 포인트를 다시 지정하고, 브랜치에 버킷(bucket)을 선언하고, 오래 지속되는 키(long-lived keys)를 제거한 뒤, 복사 루프를 한 번 실행하기만 하면 됩니다. 함께 제공되지 않는 S3 플랫폼 기능의 짧은 목록을 확인하십시오. 만약 여러분이 해당 기능이 필요 없는 일반적인 사례에 속한다면, 그 보상은 여러분의 파일이 다른 상태(state) 데이터와 마찬가지로 마침내 데이터베이스와 함께 브랜칭된다는 것입니다.