Firebase Extensions를 함수 키트로 이전

이 가이드에서는 지원이 중단된 Firebase Extensions 환경에서 Firebase (2세대) 코드베이스용 자체 Cloud Functions에 설치하고 배포할 수 있는 함수 키트로 확장 프로그램을 이전하는 방법을 보여줍니다.

Firebase Extensions 확장 프로그램 생성, 업데이트, 삭제의 모든 측면을 관리합니다. 함수 키트는 확장 프로그램의 기능을 일반적인 2세대 Cloud Functions for Firebase로 패키징합니다. 함수 키트는 표준 Cloud Functions이므로 Firebase 프로젝트 내에서 Firebase CLI를 사용하여 함수 키트를 만들고, 업데이트하고, 삭제하고, 문제를 해결합니다. 이 가이드를 통해 지금 함수를 관리하고 업데이트가 제공될 때 이를 적용할 수 있습니다.

이 가이드에서는 BigQuery에 Cloud Firestore 스트리밍 확장 프로그램 (firestore-bigquery-export)을 마이그레이션의 각 단계에 대한 명령어와 명령어 출력을 보여주는 예로 사용합니다.

마이그레이션 경로 결정

Firebase에서는 모든 Firebase Extensions 게시자가 npm에 게시된 함수 키트로 확장 프로그램을 대체하도록 권장합니다. 다음과 같은 여러 방법으로 확장 프로그램에 함수 키트 대체가 제공되는지 확인할 수 있습니다.

  • 프로젝트의 Firebase 콘솔의 확장 프로그램 페이지로 이동합니다. 설치된 각 확장 프로그램은 사용 가능한 기능 키트 대체가 있는지 나타냅니다.

  • 터미널에서 Firebase 프로젝트 내에서 firebase ext:list를 실행하여 설치된 확장 프로그램 중 공식 대체 항목이 있는 확장 프로그램을 표시합니다.

    firebase ext:list --project my-project

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
✔  extensions: required API firebaseextensions.googleapis.com is enabled
i  extensions: list of extensions installed in my-project:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2   │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/storage-resize-images     │ firebase  │ storage-resize-images          │ ACTIVE │ 0.3.6   │ 2026-06-03 17:41:24 │                                                   │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

확장 프로그램에 공식 함수 키트 대체가 제공되는 경우 npm에서 함수 키트로 마이그레이션 섹션을 사용하여 마이그레이션할 수 있습니다.

게시된 대체 항목을 찾을 수 없는 경우 모든 확장 프로그램이 오픈소스이므로 확장 프로그램 코드를 포크하고 자체 대체 항목을 만들 수 있습니다. 이렇게 하려면 직접 만든 함수 키트로 이전 가이드를 따르세요.

마이그레이션 경로 선택: npm의 함수 키트로 마이그레이션 직접 만든 함수 키트로 마이그레이션

npm의 함수 키트로 마이그레이션

알려진 이전 제한사항 확인

확장 프로그램 인스턴스 마이그레이션을 시작하기 전에 설정에서 해결 방법이 필요하거나 아직 함수 키트에서 지원되지 않는 다음 기능을 사용하는지 확인하세요.

  • 커스텀 Docker 저장소 및 KMS 키에는 수동 해결 방법이 필요함 Cloud Functions for Firebase는 커스텀 Docker 저장소 또는 고객 관리 암호화 키 (KMS 키)를 구성하기 위한 대체 시스템 매개변수를 지원하지 않습니다. 확장 프로그램이 이러한 매개변수 중 하나를 구성하는 경우 FAQ 해결 방법을 참고하세요.

시작하기 전에

Firebase CLI를 설정하고 Firebase 프로젝트를 초기화해야 합니다. CLI를 사용할 때는 새 이전 및 함수 키트 명령어가 있는 firebase-tools 버전 >= 15.32.0을 사용해야 합니다.

필수 계정 권한 및 역할

마이그레이션 중에 Firebase CLI에서 만들어야 하고 구성해야 하는 항목에 따라 Firebase 및 Google Cloud로 인증하는 데 사용하는 계정에 다음 역할이 있어야 합니다.

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (공개 엔드포인트에 setIamPermissions를 실행해야 하는 경우)
  • roles/secretmanager.admin (보안 비밀을 사용하는 경우)
  • roles/serviceusage.serviceUsageAdmin (새 API를 사용 설정해야 하는 경우)

이러한 권한 대부분이 이미 부여되어 있으므로 이전에 확장 프로그램을 설치하고 함수를 배포한 계정을 사용하는 것이 좋습니다. 이전하는 계정에 역할이 더 필요한 경우 Google Cloud IAM 안내에 따라 역할을 추가하세요.

CLI 워크플로 선택

확장 프로그램 인스턴스에서 npm에서 사용할 수 있는 함수 키트로 마이그레이션하려면 다음 옵션 중 하나를 선택하세요.

  • (권장) ext:migrate CLI 명령어를 사용하여 이전합니다. 이 명령어는 대체할 확장 프로그램을 제거하기 전에 함수 키트 교체를 배포합니다.
  • 함수 키트 CLI 명령어를 사용하여 이전합니다. 별도의 명령어를 사용하여 확장 프로그램을 업데이트하고, 함수 키트를 설치하고, 확장 프로그램처럼 구성하고, 키트를 배포하고, 확장 프로그램을 제거할 수 있습니다. 이렇게 하면 명령어를 재정렬하거나 단계 사이에 추가 작업을 수행하는 데 더 유연해집니다.

ext:migrate를 사용하여 이전

확장 프로그램 인스턴스당 한 번 다음을 실행하여 마이그레이션을 시작합니다.

firebase ext:migrate --project <project-id>

이 명령어는 다음을 안내합니다.

  1. 공식 함수 키트 대체가 제공되는 확장 프로그램을 선택하여 이전합니다.
  2. 해당 확장 프로그램의 특정 인스턴스를 선택합니다.
  3. 필요한 경우 확장 프로그램을 최신 버전으로 업데이트합니다.
  4. 함수 키트를 설치하고 확장 프로그램 인스턴스가 구성된 방식과 동일하게 인스턴스를 구성합니다.
  5. 함수 키트를 배포합니다.
  6. 함수 키트가 성공적으로 배포되었는지, 모든 수명 주기 후크가 실행되었는지 확인합니다.
  7. 확장 프로그램 인스턴스를 제거합니다.

마이그레이션할 특정 확장 프로그램 또는 확장 프로그램 인스턴스를 알고 있는 경우 다음 명령줄 플래그를 사용하여 지정합니다.

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

특히 Google에서 나열한 공식 대체 패키지가 아닌 특정 패키지로 이전하려는 경우 --package 플래그를 사용하여 지정합니다.

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

함수 키트 배포 확인

키트의 firebase deploy에 오류가 없는지 확인하려면 배포 로그를 확인하여 수명 주기 후크가 트리거되었는지 확인합니다. 스트림 Cloud Firestore에서 BigQuery로와 같은 인기 확장 프로그램은 수명 주기 후크를 사용합니다. 다음은 트리거될 때 수명 주기 후크가 표시되는 방식의 예시입니다.

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

이러한 로그 메시지는 다음을 확인합니다.

  • 수명 주기 후크가 발견되어 실행되었습니다.
  • 태스크가 수명 주기 후크의 연결된 태스크 큐에 대기열에 추가되었습니다.
  • 오류 없이 작업이 완료되었는지 확인할 수 있도록 Cloud Logging 링크가 제공되었습니다.

로그 링크를 따라 Google Cloud 콘솔로 이동하여 로그에 오류가 없고 태스크 큐 이벤트가 성공적으로 처리되었는지 확인합니다. 수명 주기 이벤트가 성공적으로 실행되지 않은 경우 다음을 실행하여 다시 트리거할 수 있습니다.

firebase functions:lifecycle:run <hook-name> <codebase>

함수 키트 인스턴스를 처음 배포하는 경우 다음을 실행합니다.

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

유효성 검사 중에 언제든지 이 이전을 중지하거나 실행취소하려면 확장 프로그램 제거의 안내에 따라 키트를 제거하면 됩니다.

함수 키트 README 검토

일부 키트의 경우 함수 키트에서 자동으로 처리하는 것 외에 추가 작업이 필요할 수 있습니다. 설치하는 키트의 README를 검토하고 추가 안내를 따릅니다.

함수 키 CLI를 사용하여 이전

시작하기 전에 키트로 이전할 확장 프로그램의 인스턴스 ID와 대체 키트의 npm 패키지 이름을 식별하여 적어 둡니다. firebase ext:list의 출력을 사용하여 두 값을 모두 찾을 수 있습니다. ext:list 사용 예시는 마이그레이션 경로 결정을 참고하세요.

1. 확장 프로그램 인스턴스를 최신 버전으로 업그레이드

확장 프로그램 인스턴스와 교체 키트 간의 차이를 최소화하려면 확장 프로그램을 최신 버전으로 업데이트해야 합니다. 확장 프로그램이 업그레이드되지 않으면 확장 프로그램 인스턴스와 키트 대체 사이에 중요한 브레이킹 체인지가 있을 수 있습니다. 버전 간 매개변수 변경으로 인해 내보낸 구성이 키트에서 예상하는 것과 일치하지 않을 수 있습니다.

확장 프로그램이 설치된 위치에 따라 다음 옵션 중 하나를 사용하여 확장 프로그램을 업데이트합니다.

  • Firebase 콘솔에서
  • Firebase CLI에서 다음을 사용하여 실행합니다.
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

이 단계를 건너뛰면 확장 프로그램이 최신 버전이 아닌 경우 구성을 내보낼 때 CLI에서 업그레이드하라는 메시지가 표시됩니다.

2. 교체 함수 키트 인스턴스 검토 및 설치

다음 CLI 명령어를 사용하여 함수 키트를 설치할 수 있습니다.

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

설치 중에 키트의 인스턴스 ID를 선택할 때 나중에 이전 안내에서 사용할 수 있도록 기록해 두세요.

키트가 설치되면 Firebase 프로젝트 내에 function-kits/<kit-name>/source과 같은 위치에 새 디렉터리가 생성됩니다. 이 디렉터리에는 확장 프로그램을 대체하는 키트가 포함된 npm 패키지와 Firebase가 배포하고 맞춤 구성을 설정할 수 있도록 이러한 함수를 내보내는 기본 index.ts 파일이 포함됩니다.

키트의 README를 검토하고 여기에 나열된 추가 안내를 따릅니다.

동일한 프로젝트에 키트 인스턴스가 여러 개 있는 경우 이 명령어를 반복하여 동일한 키트의 새 인스턴스를 만들 수 있습니다. 또한 구성이 다른 두 개의 Firebase 프로젝트 (예: 스테이징 프로젝트와 프로덕션 프로젝트)에 단일 키트 인스턴스를 배포할 수도 있습니다. 이러한 고급 설정에 대해 자세히 알아보려면 고급 이전을 참고하세요.

작업 예시:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. 확장 프로그램과 동일하게 함수 키트 인스턴스 구성

이 키트 인스턴스를 대체하는 확장 프로그램과 동일한 구성으로 맞춤설정해야 합니다. 확장 프로그램 인스턴스 구성을 .env 파일로 내보낼 수 있습니다. 이 파일에는 키트를 포함한 모든 Cloud Functions의 매개변수, 환경 변수, 비밀 참조 구성 데이터가 저장됩니다. 키트의 구성 파일로 직접 내보내려면 다음을 실행하세요.

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

이 단계가 끝나면 이 인스턴스의 구성 정보가 인스턴스 구성 디렉터리의 프로젝트별 .env 파일에 저장됩니다(예: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>).

4. 키트 교체 배포 및 확인

이제 키트가 설치되고 함수 집합으로 사용할 수 있으므로 키트 교체를 배포할 수 있습니다. 함수 키트는 표준 함수와 마찬가지로 작동하며, 각 키트 인스턴스는 함수를 정리하기 위한 별도의 코드베이스 역할을 합니다. 모든 함수를 배포하거나 특정 키트 인스턴스만 배포할 수 있습니다. 단일 확장 프로그램 인스턴스를 이전하는 동안 해당 키트 인스턴스만 배포합니다.

키트에서 이전한 확장 프로그램 인스턴스에 없던 새 매개변수를 사용하는 경우 Firebase CLI는 배포 프로세스 시작 시 이러한 매개변수를 묻는 메시지를 표시합니다. 최신 firestore-bigquery-export 확장 프로그램의 이 예에서는 예상되지 않지만 많은 키트에서 키트에서 사용하는 모든 이벤트 트리거 소스에 대한 새 매개변수를 묻는 메시지를 표시합니다. 이 이전의 일환으로, 업데이트된 키트는 확장 프로그램이 이전에 1세대 함수를 사용한 경우 2세대 함수를 사용합니다. 2세대에서는 함수가 이벤트 소스 근처에 있으며 추가 매개변수로 추가됩니다. 향후 업데이트에서 새 매개변수가 추가되면 CLI에서 다음 배포 시 메시지를 표시합니다.

작업 예시:

firebase deploy --only functions:firestore-bigquery-export --project my-project

출력:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

키트의 firebase deploy에 오류가 없는지 확인하려면 배포 로그를 확인하여 수명 주기 후크가 트리거되었는지 확인합니다. 스트림 Cloud Firestore에서 BigQuery로와 같은 인기 확장 프로그램은 수명 주기 후크를 사용합니다. 다음은 트리거될 때 수명 주기 후크가 표시되는 방식의 예시입니다.

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

이러한 로그 메시지는 다음을 확인합니다.

  • 수명 주기 후크가 발견되어 실행되었습니다.
  • 태스크가 수명 주기 후크의 연결된 태스크 큐에 대기열에 추가되었습니다.
  • 오류 없이 작업이 완료되었는지 확인할 수 있도록 Cloud Logging 링크가 제공되었습니다.

로그 링크를 따라 Google Cloud 콘솔로 이동하여 로그에 오류가 없고 태스크 큐 이벤트가 성공적으로 처리되었는지 확인합니다. 수명 주기 이벤트가 성공적으로 실행되지 않은 경우 다음을 실행하여 다시 트리거할 수 있습니다.

firebase functions:lifecycle:run <hook-name> <codebase>

함수 키트 인스턴스를 처음 배포하는 경우 다음을 실행합니다.

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

유효성 검사 중에 언제든지 이 이전을 중지하거나 실행취소하려면 확장 프로그램 제거의 안내에 따라 키트를 제거하면 됩니다.

5. 확장 프로그램 제거

배포된 함수 키트를 확인한 후에는 키트에서 한 번, 확장 프로그램에서 한 번 동작이 중복되지 않도록 확장 프로그램을 제거할 수 있습니다. --immediate 플래그를 전달하면 설치 방법에 관계없이 Firebase CLI에서 모든 확장 프로그램을 제거할 수 있습니다.

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

작업 예시:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

출력:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

고급 마이그레이션

단일 코드베이스로 관리하려는 여러 Firebase 프로젝트에 확장 프로그램을 포함할 수 있습니다. 예를 들어 testing 환경과 production 환경에 동일한 인프라를 배포하고 각 환경에는 BigQuery로 내보내는 documents Cloud Firestore 인스턴스가 있는 경우 firestore-bigquery-export 확장 프로그램의 인스턴스가 두 개 설치될 수 있습니다.

  • export-documents-testing
  • export-documents-production

Firebase CLI로 작업할 때 이러한 두 확장 프로그램 인스턴스를 단일 코드베이스의 두 함수 키트 인스턴스로 마이그레이션하고 firebase deploy --project testing 및 firebase deploy --project production를 사용하여 배포한 경우 각 배포는 testing 및 production 환경 모두에서 두 인스턴스를 생성합니다.

대신 두 확장 프로그램 인스턴스를 여러 프로젝트에 배포된 firestore-bigquery-export의 함수 키트 인스턴스 하나로 대체합니다. 각 프로젝트에는 자체 구성이 있습니다. 인스턴스의 구성 디렉터리는 다음과 같이 표시됩니다.

  • config-export-documents/
    • .env.testing
    • .env.production

testing 및 production에 대한 각 배포는 해당 구성으로 키트의 인스턴스를 하나 만듭니다. ext:migrate 또는 functions:kits:install 호출마다 --project 플래그를 전달하면 기존 CLI 명령어에서 이 설정을 만듭니다.

작업 예시:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

이제 각 구성으로 testing 및 production 프로젝트에 배포하도록 구성된 단일 키트 인스턴스가 있습니다. testing 프로젝트에서 인스턴스를 만들고 production 프로젝트에서 동일한 패키지에 대해 functions:kits:install 명령어를 실행하면 testing에 구성된 인스턴스를 재사용하거나 두 번째 인스턴스를 설치하는 옵션이 표시됩니다.