Workflow

SST를 사용하여 앱을 구축하는 기본 워크플로우.

워크플로우

SST에서 작업할 때 다른 프레임워크와의 주요 차이점은 앱과 관련된 모든 것이 코드로 정의된다는 점입니다.

SST는 앱에서 정의한 AWS(또는 다른 프로바이더)의 리소스를 자동으로 관리합니다.
클라우드 프로바이더의 콘솔에서 수동으로 변경할 필요가 없습니다.

이러한 _모든 것을 자동화_하는 개념은 처음에는 낯설게 느껴질 수 있습니다. 따라서 워크플로우를 살펴보고 몇 가지 기본 개념을 알아보겠습니다.

설정

앱 작업을 시작하기 전에, 몇 가지 설정을 권장합니다.

코드 편집기부터 시작해 보겠습니다.

에디터

SST 앱은 sst.config.ts 파일을 통해 설정됩니다. 이 파일은 TypeScript 파일로, 여러분의 에디터와 함께 작동하여 타입 체크와 자동 완성을 제공할 수 있습니다. 또한 인라인 도움말도 표시할 수 있습니다.

에디터 타입 체크

VS Code와 Neovim을 포함한 대부분의 모던 에디터는 위 기능을 자동으로 제공합니다. 하지만 시작하기 전에 에디터가 제대로 설정되었는지 확인해야 합니다.

인증 정보

SST 앱은 여러분의 인프라에 배포됩니다. AWS, Cloudflare 또는 다른 클라우드 프로바이더에 배포하더라도 로컬에서 해당 인증 정보가 설정되어 있는지 확인하세요.

AWS 인증 정보 설정 방법에 대해 더 알아보세요.

콘솔

SST는 콘솔도 제공합니다. 이 콘솔은 여러분의 모든 앱과 그 안의 리소스를 보여주며, _git push to deploy_를 설정하고, 문제가 발생할 때 알림을 보내줍니다.

콘솔 사용은 선택 사항이지만, 무료 계정을 생성하고 AWS 계정과 연결하는 것을 권장합니다. SST 콘솔에 대해 더 알아보세요.

sst.config.ts

이제 여러분의 앱과 sst.config.ts 작업을 준비했으니, _모든 것을 코드로 구성한다_는 의미를 살펴보겠습니다.

IaC

Infrastructure as Code, 줄여서 _IaC_는 코드를 통해 인프라 관리를 자동화하는 프로세스입니다. 콘솔이나 사용자 인터페이스를 통해 수동으로 작업하는 대신 코드로 정의합니다.

예를 들어, 앱에 함수와 S3 버킷이 있다면 sst.config.ts 파일에 다음과 같이 정의할 수 있습니다.

const bucket = new sst.aws.Bucket("MyBucket");

new sst.aws.Function("MyFunction", {
  handler: "index.handler"
});

이제 AWS 콘솔에서 Lambda나 S3 부분을 직접 설정할 필요가 없습니다. SST가 여러분을 대신해 작업을 수행합니다.

위 코드에서 sst.aws.Function과 sst.aws.Bucket은 컴포넌트라고 부릅니다. 컴포넌트에 대해 더 알아보세요.

리소스

이것이 작동하는 이유는 SST가 위의 앱을 배포할 때, 이를 일련의 커맨드로 변환하기 때문입니다. 이 커맨드들은 여러분의 자격 증명을 사용해 AWS를 호출하여 기본 리소스를 생성합니다. 따라서 위의 컴포넌트들은 AWS의 저수준 리소스 목록으로 변환됩니다.

AWS 콘솔에 로그인하면 내부적으로 생성된 리소스를 확인할 수 있습니다. 이 리소스들은 다소 복잡해 보일 수 있지만, 모두 SST가 관리하며 여러분이 직접 관리할 필요는 없습니다.

SST는 앱에 정의된 모든 저수준 리소스를 생성, 추적, 제거합니다.

예외 사항

이 규칙에는 몇 가지 예외가 있습니다. 여러분의 SST 설정에 정의되지 않은 리소스가 있을 수 있습니다. 이러한 리소스는 다음과 같습니다:

이전에 생성된 리소스

이전에 수동으로 생성한 리소스를 새로운 SST 앱에서 사용하고 싶을 수 있습니다. 이러한 리소스를 앱으로 가져올 수 있습니다. 이후부터는 SST가 이 리소스를 관리합니다. 리소스 가져오기에 대해 더 알아보세요.
외부에서 관리되는 리소스

다른 팀에서 관리하는 리소스가 있을 수 있습니다. 이 경우 SST가 이 리소스를 관리하지 않도록 할 수 있습니다. 단순히 앱에서 이 리소스를 참조하고 싶을 수 있습니다. 리소스 참조하기에 대해 더 알아보세요.
스테이지 간 공유되는 리소스

미리보기 환경을 생성할 때 데이터베이스와 같은 특정 리소스를 복사하지 않고 여러 스테이지에서 공유하고 싶을 수 있습니다. 스테이지 간 리소스 공유에 대해 더 알아보세요.

리소스 연결

위 예제에서 여러분의 함수가 S3 버킷에 파일을 업로드하도록 하려면, API에 버킷 이름을 하드코딩해야 합니다.

SST는 리소스를 연결하는 방식을 통해 이를 피할 수 있게 해줍니다.

new sst.aws.Function("MyFunction", {
  handler: "index.handler",
  link: [bucket]
});

이제 여러분의 함수에서 SST의 SDK를 사용해 버킷에 접근할 수 있습니다.

import { Resource } from "sst";

console.log(Resource.MyBucket.name);

위 두 코드 조각은 차이가 있습니다. 하나는 인프라 코드이고 다른 하나는 런타임 코드입니다. 하나는 앱을 생성할 때 실행되고, 다른 하나는 사용자가 앱을 사용할 때 실행됩니다.

_link_를 사용하면 런타임 코드에서 인프라에 접근할 수 있습니다. 리소스 연결에 대해 더 알아보세요.

상태

여러분이 위에서 했던 것처럼 sst.config.ts 파일을 변경하면, SST는 변경된 부분만 배포합니다.

new sst.aws.Function("MyFunction", {
  handler: "index.handler",
  link: [bucket]
});

이렇게 동작하는 이유는 SST가 여러분의 앱 상태를 유지하기 때문입니다. 상태는 앱 내 모든 리소스와 그 속성들을 트리 구조로 나타낸 것입니다.

이 상태는 로컬 파일에 저장되며, 여러분의 AWS(또는 Cloudflare) 계정의 버킷에 백업됩니다.

주의할 점은, 어떤 이유로든 로컬과 프로바이더에서 상태를 삭제하면 SST는 더 이상 리소스를 관리할 수 없게 됩니다. SST는 이 앱이 더 이상 존재하지 않는 것으로 간주합니다.

이 문제를 해결하려면 모든 리소스를 수동으로 다시 앱에 가져와야 합니다. 상태가 어떻게 동작하는지에 대해 더 알아보세요.

동기화 불일치

앞서 SST가 생성하는 저수준 리소스에 대해 여러분이 직접 관리할 필요가 없다고 언급했습니다. 이는 단순히 편의성 문제가 아니라, 절대 해서는 안 되는 일입니다.

그 이유는 SST가 sst.config.ts가 변경될 때만 차이점을 적용하기 때문입니다. 따라서 리소스를 수동으로 변경하면 상태와 동기화가 깨지게 됩니다.

sst refresh를 실행하여 일부 문제를 해결할 수 있지만, 일반적으로 이런 작업은 피해야 합니다.

앱

이제 IaC(Infrastructure as Code)가 어떻게 동작하는지 알았으니, 많은 워크플로우와 개념들이 이해되기 시작할 것입니다. 앱의 주요 부분부터 살펴보겠습니다.

이름

모든 앱에는 이름이 있습니다. 이 이름은 네임스페이스로 사용됩니다. SST가 동일한 클라우드 제공자 계정에 여러 앱을 배포하면서도 각 앱의 리소스를 격리할 수 있게 해줍니다.

sst.config.ts에서 앱 이름을 변경하면 SST는 완전히 새로운 리소스 세트를 생성합니다. 기존 리소스의 이름을 변경하지 않습니다.

예를 들어:

sst.config.ts에서 my-sst-app이라는 이름으로 앱을 생성하고 배포합니다.
sst.config.ts에서 앱 이름을 my-new-sst-app으로 변경하고 다시 배포합니다.

이제 AWS 계정에는 my-sst-app과 my-new-sst-app이라는 두 개의 앱이 존재하게 됩니다.

앱 이름을 변경하려면 먼저 기존 앱을 제거한 후 새로운 이름으로 앱을 배포해야 합니다.

스테이지

앱은 여러 개의 스테이지를 가질 수 있습니다. 스테이지는 _환경_과 비슷하며, 앱의 별도 버전입니다. 예를 들어, 개발 스테이지, 프로덕션 스테이지, 개인 스테이지 등을 가질 수 있습니다.

앱의 여러 버전을 유지하는 것은 사용자가 다른 버전을 계속 사용하는 동안 변경 사항을 적용하고 테스트할 수 있기 때문에 유용합니다.

--stage <name> CLI 옵션을 사용하여 새로운 스테이지에 배포하면 새 스테이지를 생성할 수 있습니다. 스테이지 이름은 앱의 새 버전을 만들기 위한 네임스페이스로 사용됩니다. 이는 앱 이름이 네임스페이스로 사용되는 방식과 유사합니다.

앱 이름과 마찬가지로 스테이지 이름도 변경할 수 없습니다. 따라서 development 스테이지를 dev로 변경하려면 먼저 development를 제거한 후 dev를 배포해야 합니다.

개인 스테이지

기본적으로 스테이지를 전달하지 않으면 SST는 여러분의 컴퓨터 사용자 이름을 사용해 스테이지를 생성합니다. 이를 개인 스테이지라고 합니다. 개인 스테이지는 일반적으로 개발 모드에서 사용되며, 팀의 각 개발자는 자신의 개인 스테이지를 사용해야 합니다.

이에 대해 자세히 살펴보겠습니다.

리전

AWS(그리고 다른 많은 프로바이더)에서 생성된 대부분의 리소스는 특정 리전에 속합니다. 따라서 여러분이 앱을 배포할 때 특정 리전에 배포됩니다.

AWS의 경우, 리전은 여러분의 AWS 자격 증명에서 가져오지만 sst.config.ts 파일에서 지정할 수도 있습니다.

export default $config({
  app(input) {
    return {
      name: "my-sst-app",
      providers: {
        aws: { region: "us-west-2" }
      }
    };
  }
});

앱과 스테이지와 마찬가지로, 리전을 변경하려면 기존 리전의 앱을 제거하고 새로운 리전에 배포해야 합니다.

커맨드

위의 배경 지식을 바탕으로 SST 앱을 만드는 워크플로를 살펴보겠습니다.

다음과 같이 앱을 생성했다고 가정해 보겠습니다.

sst init

개발

먼저, 앱을 개발 모드로 실행합니다.

sst dev

이 명령어는 앱을 여러분의 개인 스테이지에 _개발 모드_로 배포합니다. 이 명령어는 앱을 배포하고, 함수를 실행하며, 터널을 생성하고, 프론트엔드와 컨테이너 서비스를 시작하는 멀티플렉서를 실행합니다.

이 명령어는 앱을 조금 다르게 배포하며, 로컬 개발에 최적화되어 있습니다.

앱의 함수를 라이브 모드로 실행합니다. 이때 스텁 버전을 배포합니다. 이 스텁 버전은 모든 요청을 여러분의 로컬 머신으로 프록시합니다.
프론트엔드나 컨테이너 서비스는 배포하지 않습니다. 대신, 로컬에서 실행합니다.
또한, VPC에 배포된 리소스에 연결할 수 있도록 터널을 생성합니다.

이러한 이유로, 로컬 개발에는 개인 스테이지를 사용하고, 앱을 사용자와 공유할 때는 별도의 스테이지에 배포하는 것을 권장합니다.

sst dev에 대해 더 알아보세요.

배포

프로덕션 환경으로 이동할 준비가 되면 다음 명령어를 실행할 수 있습니다.

sst deploy --stage production

여기서는 프로덕션을 위해 어떤 스테이지 이름도 사용할 수 있습니다.

제거

여러분의 앱과 그 안의 모든 리소스를 제거하려면 다음 명령어를 실행할 수 있습니다.

sst remove --stage <name>

이 명령어를 실행할 때는 주의해야 합니다. AWS(또는 클라우드 프로바이더) 계정에서 모든 리소스를 영구적으로 제거하기 때문입니다.

실수로 인한 제거를 방지하기 위해, 우리의 템플릿 sst.config.ts에는 다음과 같은 설정이 포함되어 있습니다.

removal: input?.stage === "production" ? "retain" : "remove",

이 설정은 스테이지가 production으로 명명된 경우, 제거 시 버킷과 데이터베이스 같은 중요한 리소스를 유지하도록 SST에 지시합니다. 이로 인해 실수로 인한 데이터 손실을 방지할 수 있습니다.

제거 정책에 대해 더 알아보세요.

팀과 함께 작업하기

이 워크플로우는 팀과 함께 작업할 때 빛을 발합니다. 기본적인 git 워크플로우와 함께 어떻게 작동하는지 살펴보겠습니다.

팀의 모든 개발자는 sst dev를 사용하여 각자의 격리된 개인 스테이지에서 작업합니다.
변경 사항을 dev라는 브랜치에 커밋합니다.
dev 브랜치의 모든 변경 사항은 sst deploy --stage dev를 사용하여 자동으로 배포됩니다.
팀은 앱의 dev 스테이지에 적용된 변경 사항을 테스트합니다.
테스트 결과가 양호하면 dev 브랜치를 production 브랜치로 병합합니다.
production 브랜치의 모든 변경 사항은 sst deploy --stage production을 사용하여 production 스테이지에 자동으로 배포됩니다.

이 설정에서는 개발자별로 별도의 스테이지, 테스트를 위한 dev 스테이지, 그리고 production 스테이지가 있습니다.

자동 배포

특정 브랜치에 커밋이 푸시될 때 스테이지 환경에 자동으로 배포되도록 하려면 GitHub Actions를 설정해야 합니다.

SST 콘솔 자동 배포

또는 저장소를 SST 콘솔에 연결하면 앱이 자동으로 배포됩니다. 자동 배포에 대해 더 알아보세요.

PR 환경 설정

프리뷰 환경을 자동으로 생성하도록 설정할 수도 있습니다.

예를 들어, 풀 리퀘스트(PR#12)가 생성되면 sst deploy --stage pr-12 명령어를 사용해 새로운 스테이지를 자동으로 배포합니다. 그리고 PR이 머지되면 sst remove --stage pr-12 명령어를 사용해 프리뷰 환경이나 스테이지를 제거합니다.

위에서 설명한 것처럼, GitHub Actions를 사용해 이 설정을 구성하거나 SST Console이 자동으로 처리하도록 할 수 있습니다.

이제 여러분은 _SST 방식_으로 앱을 구축할 준비가 되었습니다.