환경 변수

환경 변수란 Amplify Hosting에서 사용할 수 있도록 애플리케이션 설정에 추가할 수 있는 키-값 페어입니다. 모범 사례로 환경 변수를 사용하여 이러한 애플리케이션 구성 데이터를 노출할 수 있습니다. 추가하는 모든 환경 변수는 불법 액세스를 방지하기 위해 암호화됩니다.

Amplify는 사용자가 생성하는 환경 변수에 다음과 같은 제약 조건을 적용합니다.

• Amplify에서는 접두사가 AWS 있는 환경 변수 이름을 만들 수 없습니다. 이 접두사는 Amplify 내부용으로만 사용됩니다.

• 환경 변수 값은 5500자를 초과할 수 없습니다.

중요

환경 변수를 사용하여 암호를 저장하지 않도록 합니다. 2세대 앱의 경우 Amplify 콘솔의 비밀 관리 기능을 사용하십시오. 자세한 내용은 Amplify 설명서의 시크릿 및 환경 변수를 참조하십시오. 1세대 앱의 경우 AWS Systems Manager 파라미터 스토어를 사용하여 만든 환경 시크릿에 시크릿을 저장하십시오. 자세한 정보는 환경 시크릿 관리을 참조하세요.

Amplify 환경 변수

다음 환경 변수는 Amplify 콘솔 내에서 기본적으로 액세스할 수 있습니다.

변수 이름	설명	예시 값
_BUILD_TIMEOUT	빌드 타임아웃 기간(분)	30
_LIVE_UPDATES	도구가 최신 버전으로 업그레이드됩니다.	[{"name":"Amplify CLI","pkg":"@aws-amplify/cli","type":"npm","version":"latest"}]
USER_DISABLE_TESTS	빌드 중에 테스트 단계를 생략합니다. 앱의 모든 브랜치 또는 특정 브랜치에 대한 테스트를 비활성화할 수 있습니다. 이 환경 변수는 빌드 단계에서 테스트를 수행하는 앱에 사용됩니다. 이 변수 설정에 대한 자세한 내용을 알아보려면 테스트 비활성화을 참조하십시오.	true
AWS_APP_ID	현재 빌드의 앱 ID	abcd1234
AWS_BRANCH	현재 빌드의 브랜치 이름	main, develop, beta, v2.0
AWS_BRANCH_ARN	현재 빌드의 브랜치 Amazon 리소스 이름(ARN)	aws:arn:amplify:us-west-2:123456789012:appname/branch/...
AWS_CLONE_URL	git 리포지토리 콘텐츠를 가져오기 위해 사용된 복제 URL	[e-mail]:<user-name>/<repo-name>.git
AWS_COMMIT_ID	현재 빌드의 커밋 ID 다시 빌드하기 위한 "HEAD"	abcd1234
AWS_JOB_ID	현재 빌드의 작업 ID입니다. 여기에는 제로 패딩(‘0’)이 포함되므로 길이가 항상 동일합니다.	0000000001
AWS_PULL_REQUEST_ID	풀 리퀘스트 웹 프리뷰 빌드의 풀 리퀘스트 ID입니다. 저장소 AWS CodeCommit 공급자로 사용할 때는 이 환경 변수를 사용할 수 없습니다.	1
AWS_PULL_REQUEST_SOURCE_BRANCH	Amplify 콘솔에서 애플리케이션 브랜치에 제출되는 풀 리퀘스트 미리보기의 기능 브랜치 이름입니다.	featureA
AWS_PULL_REQUEST_DESTINATION_BRANCH	기능 브랜치 풀 요청이 제출되는 Amplify 콘솔의 애플리케이션 브랜치 이름입니다.	main
AMPLIFY_AMAZON_CLIENT_ID	Amazon 클라이언트 ID	123456
AMPLIFY_AMAZON_CLIENT_SECRET	Amazon 클라이언트 암호	example123456
AMPLIFY_FACEBOOK_CLIENT_ID	Facebook 클라이언트 ID	123456
AMPLIFY_FACEBOOK_CLIENT_SECRET	Facebook 클라이언트 암호	example123456
AMPLIFY_GOOGLE_CLIENT_ID	Google 클라이언트 ID	123456
AMPLIFY_GOOGLE_CLIENT_SECRET	Google 클라이언트 암호	example123456
AMPLIFY_DIFF_DEPLOY	diff 기반 프런트엔드 배포를 활성화 또는 비활성화합니다. 자세한 정보는 diff 기반 프런트엔드 빌드 및 배포 활성화 또는 비활성화을 참조하세요.	true
AMPLIFY_DIFF_DEPLOY_ROOT	리포지토리의 루트를 기준으로 diff 기반 프런트엔드 배포를 비교하는 데 사용할 경로입니다.	dist
AMPLIFY_DIFF_BACKEND	diff 기반 백엔드 빌드를 활성화 또는 비활성화합니다. 이는 1세대 앱에만 적용됩니다. 자세한 정보는 1세대 앱의 diff 기반 백엔드 빌드를 활성화 또는 비활성화합니다. 섹션을 참조하십시오.	true
AMPLIFY_BACKEND_PULL_ONLY	Amplify는 이 환경 변수를 관리합니다. 이는 1세대 앱에만 적용됩니다. 자세한 정보는 다른 백엔드를 가리키도록 기존 프론트엔드를 편집합니다. 섹션을 참조하십시오.	true
AMPLIFY_BACKEND_APP_ID	Amplify는 이 환경 변수를 관리합니다. 이는 1세대 앱에만 적용됩니다. 자세한 정보는 다른 백엔드를 가리키도록 기존 프론트엔드를 편집합니다. 섹션을 참조하십시오.	abcd1234
AMPLIFY_SKIP_BACKEND_BUILD	빌드 사양에 백엔드 섹션이 없고 백엔드 빌드를 비활성화하려면 이 환경 변수를 true으(로) 설정합니다. 이는 1세대 앱에만 적용됩니다.	true
AMPLIFY_ENABLE_DEBUG_OUTPUT	로그에 스택 true 트레이스를 인쇄하려면 이 변수를 로 설정합니다. 이는 백엔드 빌드 오류를 디버깅하는 데 유용합니다.	true
AMPLIFY_MONOREPO_APP_ROOT	리포지토리의 루트를 기준으로 모노레포 앱의 앱 루트를 지정하는 데 사용할 경로입니다.	apps/react-app
AMPLIFY_USERPOOL_ID	인증을 위해 가져온 Amazon Cognito 사용자 풀의 ID	us-west-2_example
AMPLIFY_WEBCLIENT_ID	웹 애플리케이션에서 사용할 앱 클라이언트의 ID AMPLIFY_USERPOOL_ID 환경 변수로 지정된 Amazon Cognito 사용자 풀에 액세스할 수 있도록 앱 클라이언트를 구성해야 합니다.	123456
AMPLIFY_NATIVECLIENT_ID	네이티브 애플리케이션에서 사용할 앱 클라이언트의 ID AMPLIFY_USERPOOL_ID 환경 변수로 지정된 Amazon Cognito 사용자 풀에 액세스할 수 있도록 앱 클라이언트를 구성해야 합니다.	123456
AMPLIFY_IDENTITYPOOL_ID	Amazon Cognito 자격 증명 풀의 ID	example-identitypool-id
AMPLIFY_PERMISSIONS_BOUNDARY_ARN	Amplify에서 생성한 모든 IAM 역할에 적용되는 권한 경계로 사용할 IAM 정책의 ARN입니다. 자세한 내용은 Amplify 생성 역할의 IAM 권한 경계를 참조하십시오.	arn:aws:iam::123456789012:policy/example-policy
AMPLIFY_DESTRUCTIVE_UPDATES	잠재적으로 데이터 손실을 일으킬 수 있는 스키마 작업으로 GraphQL API를 업데이트할 수 있도록 하려면 이 환경 변수를 true로 설정합니다.	true

참고

AMPLIFY_AMAZON_CLIENT_ID및 AMPLIFY_AMAZON_CLIENT_SECRET 환경 변수는 OAuth 토큰이지 AWS 액세스 키와 비밀 키가 아닙니다.

환경 변수 설정

Amplify 콘솔에서 애플리케이션의 환경 변수를 설정하려면 다음 지침을 따르십시오.

참고

앱이 연속 배포되도록 설정하고 git 리포지토리에 연결된 경우에만 Amplify 콘솔의 앱 설정 메뉴에 환경 변수가 표시됩니다. 이러한 유형의 배포에 대한 지침은 기존 코드로 시작하기를 참조하십시오.

환경 변수를 설정하는 방법

1. 에 AWS Management Console 로그인하고 Amplify 콘솔을 엽니다.

2. Amplify 콘솔에서 호스팅을 선택한 다음 환경 변수를 선택합니다.

3. 환경 변수 페이지에서 변수 관리를 선택합니다.

4. 변수에 키를 입력합니다. 값에 값을 입력합니다. 기본적으로 Amplify는 환경 변수를 모든 브랜치에 적용하므로 새로운 브랜치에 연결할 때 변수를 다시 입력할 필요가 없습니다.

5. (선택 사항) 브랜치에 맞게 환경 변수를 사용자 지정하려면 다음과 같이 브랜치 재정의를 추가합니다.

   1. 작업을 선택한 다음, 변수 재정의 추가를 선택합니다.

   2. 이제 브랜치별 환경 변수 집합을 갖게 되었습니다.

6. 저장을 선택합니다.

빌드 시 환경 변수에 액세스

빌드 중 환경 변수에 액세스하려면 빌드 명령에 환경 변수를 포함하도록 빌드 설정을 편집하십시오.

빌드 구성의 각 명령은 Bash 쉘 내에서 실행됩니다. Bash에서 환경 변수를 사용하는 방법에 대한 자세한 내용은 GNU Bash 매뉴얼의 쉘 확장을 참조하십시오.

환경 변수를 포함하도록 빌드 설정을 편집하려면

1. 에 AWS Management Console 로그인하고 Amplify 콘솔을 엽니다.

2. Amplify 콘솔에서 호스팅을 선택한 다음 빌드 설정을 선택합니다.

3. 앱 빌드 사양 섹션에서 편집을 선택합니다.

4. 환경 변수를 빌드 명령에 추가합니다. 이제 다음 빌드 동안 환경 변수에 액세스할 수 있어야 합니다. 이 예제는 npm의 동작(BUILD_ENV)을 변경하고 나중에 사용할 수 있도록 외부 서비스용 API 토큰(TWITCH_CLIENT_ID)을 환경 파일에 추가합니다.

   build:
     commands:
       - npm run build:$BUILD_ENV
       - echo "TWITCH_CLIENT_ID=$TWITCH_CLIENT_ID" >> backend/.env 

5. 저장을 선택합니다.

환경 변수가 서버 측 런타임에 액세스할 수 있도록 만들기

Next.js 서버 구성 요소는 기본적으로 앱의 환경 변수에 액세스할 수 없습니다. 이는 애플리케이션이 빌드 단계에서 사용하는 환경 변수에 저장된 모든 암호를 보호하기 위한 것입니다.

특정 환경 변수를 Next.js에 액세스할 수 있게 하려면 Next.js가 인식하는 환경 파일에 환경 변수를 설정하도록 Amplify 빌드 사양 파일을 수정해야 합니다. 이를 통해 Amplify는 애플리케이션을 빌드하기 전에 환경 변수를 로드할 수 있습니다. 빌드 사양 수정에 대한 자세한 내용은 빌드 명령 섹션에서 환경 변수를 추가하는 방법의 예를 참조하십시오.

소셜 로그인을 위한 인증 파라미터를 사용하여 새 백엔드 환경 생성

브랜치를 앱에 연결하려면

1. 에 AWS Management Console 로그인하고 Amplify 콘솔을 엽니다.

2. 브랜치를 앱에 연결하는 절차는 브랜치를 새 앱과 기존 앱 중 어디에 연결하는지에 따라 달라집니다.

   • 브랜치를 새 앱에 연결

     1. 빌드 설정 페이지에서 이 브랜치에 사용할 백엔드 환경 선택 섹션을 찾습니다. 환경에서 새 환경 생성을 선택하고 백엔드 환경의 이름을 입력합니다. 다음 스크린샷은 빌드 설정 페이지의 이 브랜치에 사용할 백엔드 환경 선택 섹션에 백엔드 환경 이름을 backend로 입력한 모습입니다.

        

     2. 빌드 설정 페이지에서 고급 설정 섹션을 확장하고 소셜 로그인 키에 대한 환경 변수를 추가합니다. 예를 들어 AMPLIFY_FACEBOOK_CLIENT_SECRET은(는) 유효한 환경 변수입니다. 기본적으로 사용할 수 있는 Amplify 시스템 환경 변수 목록은 Amplify 환경 변수의 표를 참조하십시오.

   • 브랜치를 기존 앱에 연결

     1. 새 브랜치를 기존 앱에 연결하는 경우 브랜치를 연결하기 전에 소셜 로그인 환경 변수를 설정합니다. 탐색 창에서 앱 설정, 환경 변수를 선택합니다.

     2. 환경 변수 섹션에서 변수 관리를 선택합니다.

     3. 변수 관리 섹션에서 변수 추가를 선택합니다.

     4. 변수(키) 에 클라이언트 ID를 입력합니다. 값에 클라이언트 암호를 입력합니다.

     5. 저장을 선택합니다.

프런트엔드 프레임워크 환경 변수

자체 환경 변수를 지원하는 프런트엔드 프레임워크로 앱을 개발하는 경우 이러한 변수는 Amplify 콘솔에 구성하는 환경 변수와 동일하지 않다는 점을 이해하는 것이 중요합니다. 예를 들어 React(접두사: REACT_APP)와 Gatsby(접두사: GATSBY)는 해당 프레임워크가 프런트엔드 프로덕션 빌드에 자동으로 번들링하는 런타임 환경 변수를 만들 수 있습니다. 이러한 환경 변수를 사용하여 값을 저장하는 데 따르는 영향을 이해하려면 사용 중인 프런트엔드 프레임워크 설명서를 참조하십시오.

API 키와 같이 중요한 값을 이러한 프런트엔드 프레임워크 접두사가 붙은 환경 변수 내에 저장하는 것은 모범 사례가 아니므로 권장하지 않습니다. 이러한 목적으로 Amplify의 빌드 시간 환경 변수를 사용하는 예는 빌드 시 환경 변수에 액세스 섹션을 참조하십시오.

환경 시크릿 관리

Amplify Gen 2가 출시됨에 따라 환경 암호에 대한 워크플로가 간소화되어 Amplify 콘솔에서 암호 및 환경 변수를 중앙 집중식으로 관리할 수 있습니다. Amplify Gen 2 앱의 보안 정보를 설정하고 액세스하는 방법에 대한 지침은 Amplify 설명서에서 시크릿 및 환경 변수를 참조하십시오.

1세대 앱의 환경 비밀은 환경 변수와 비슷하지만 암호화할 수 있는 AWS Systems Manager 파라미터 스토어 키 값 쌍입니다. Amplify에 대한 ‘Apple 프라이빗 키로 로그인’과 같은 일부 값은 암호화되어야 합니다.

1세대 앱의 환경 비밀을 설정하고 액세스하십시오.

콘솔을 사용하여 Gen 1 Amplify 앱의 환경 암호를 설정하려면 다음 지침을 따르십시오. AWS Systems Manager

환경 암호를 설정하려면

1. 에 AWS Management Console 로그인하고 AWS Systems Manager 콘솔을 엽니다.

2. 탐색 창에서 애플리케이션 관리를 선택한 다음, Parameter Store를 선택합니다.

3. AWS Systems Manager Parameter Store 페이지에서 파라미터 생성을 선택합니다.

4. 파라미터 생성 페이지의 파라미터 세부 정보 섹션에서 다음을 수행합니다.

   1. 이름에 파라미터를 /amplify/{your_app_id}/{your_backend_environment_name}/{your_parameter_name} 형식으로 입력합니다.

   2. 유형(Type)에서 SecureString를 선택합니다.

   3. KMS 키 소스의 경우 내 현재 계정을 선택하여 계정의 기본 키를 사용합니다.

   4. 값 에는 암호화할 암호 값을 입력합니다.

5. 파라미터 생성을 선택합니다.

참고

Amplify는 특정 환경 빌드용 /amplify/{your_app_id}/{your_backend_environment_name} 키에만 액세스할 수 있습니다. Amplify가 값을 AWS KMS key 해독할 수 있도록 하려면 기본값을 지정해야 합니다.

환경 암호에 액세스

빌드 중에 1세대 앱의 환경 암호에 액세스하는 것은 환경 암호가 JSON 문자열로 저장된다는 점을 제외하면 환경 변수에 액세스하는 것과 비슷합니다. process.env.secrets

Amplify 환경 암호

Systems Manager 파라미터를 /amplify/{your_app_id}/{your_backend_environment_name}/AMPLIFY_SIWA_CLIENT_ID 형식으로 지정합니다.

Amplify 콘솔 내에서 기본적으로 액세스할 수 있는 다음 환경 암호를 사용할 수 있습니다.

변수 이름	설명	예시 값
AMPLIFY_SIWA_CLIENT_ID	Apple 클라이언트 ID로 로그인	com.yourapp.auth
AMPLIFY_SIWA_TEAM_ID	Apple 팀 ID로 로그인	ABCD123
AMPLIFY_SIWA_KEY_ID	Apple 키 ID로 로그인	ABCD123
AMPLIFY_SIWA_PRIVATE_KEY	Apple 프라이빗 키로 로그인	-----프라이빗 키 시작----- ****...... -----프라이빗 키 종료-----