Firebase Extensions에서 함수 키트로 마이그레이션한 후에는 Firebase 프로젝트에서 키트 인스턴스를 표준 2세대 Cloud Functions로 관리합니다. 이 가이드에서는 기존 확장 프로그램을 이전하지 않고 npm에서 직접 새 함수 키트를 설치하고, 키트 매개변수와 전역 옵션을 업데이트하고, 게시자가 업데이트를 출시할 때 npm 패키지 버전을 업그레이드하고, 필요한 경우 이전을 롤백하는 방법을 설명합니다.
이전하지 않고 npm 패키지에서 함수 키트 사용
확장 프로그램에서 이전하지 않는 경우 함수 키트 사용은 다음 두 부분으로 구성됩니다.
키트 설치
다음 CLI 명령어를 사용하여 함수 키트를 설치할 수 있습니다.
firebase functions:kits:install --package <npm-package-name>
작업 예시:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i function-kits/firestore-bigquery-export/source/package.json is unchanged
i function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i functions: Building TypeScript source...
✔ Wrote configuration info to firebase.json
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1
✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project
✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing
# Omitting many more parameters for brevity
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
i functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠ functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.
기본 전역 옵션 변경
키트 인스턴스의 전역 옵션을 구성하려면 function-kits/<your-kit-id>/source/src/index.ts에 있는 index.ts 파일을 수정하세요.
기본값을 키트의 모든 인스턴스에서 공유하려면 index.ts에서 직접 설정하세요. 그렇지 않으면 index.ts에 설명된 예와 안내에 따라 인스턴스별로 설정되는 매개변수를 만듭니다.
키트 배포
함수 키트를 배포하려면 다음을 실행하세요.
firebase deploy --only functions:<kit-instance-id>
작업 예시:
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!
키트를 설치하고 배포하면 다음 작업이 실행됩니다.
- 키트 패키지를 가져오고 내보내는 기본
index.ts파일을 포함하는 키트 소스를 만들고 키트의 각 인스턴스에 대해 다른 위치를 선택할 수 있는 매개변수를 설정하는function-kits/firestore-bigquery-export/source를 만듭니다. function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id>를 만들고 함수에 입력된 구성 데이터로 채웁니다. 향후 업데이트에서 새 매개변수가 추가되면 다음 배포 시 메시지가 표시됩니다.- 특정 IAM 역할, 함수, Eventarc 트리거, Cloud Tasks 대기열이 있는 서비스 계정을 비롯하여 이 키트를 실행하는 데 필요한 Google Cloud 리소스를 만듭니다.
동일한 프로젝트에 키트 인스턴스가 여러 개 있는 경우 이러한 명령어를 반복하여 동일한 키트의 새 인스턴스를 만들고 배포할 수 있습니다. 또한 구성이 다른 여러 Firebase 프로젝트 (예: 스테이징 프로젝트와 프로덕션 프로젝트)에 단일 키트 인스턴스를 배포할 수도 있습니다. 고급 설정에 대해 자세히 알아보려면 고급 마이그레이션을 참고하세요.
키트 제거
키트와 모든 인스턴스를 삭제하려면 다음을 실행하세요.
firebase functions:kits:uninstall --kit <kit-id>
이렇게 하면 모든 인스턴스와 해당 구성이 삭제되고 디스크에서 키트 소스가 삭제됩니다.
키트의 단일 인스턴스만 삭제하려면 다음을 실행하세요.
firebase functions:kits:uninstall --instance <kit-instance-id>
키트 인스턴스가 하나만 있는 경우 전체 키트가 제거됩니다.
키트 구성 업데이트
설치 또는 첫 번째 배포 중에 확장 프로그램에서 구성을 이전하지 않은 경우 키트의 모든 매개변수를 구성하라는 메시지가 표시됩니다.
이러한 매개변수는 키트 인스턴스 구성 디렉터리의 .env 파일에 저장됩니다. 예를 들어 프로젝트 my-project에 firestore-bigquery-export라는 키트 인스턴스가 있는 경우 .env 파일은 function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project에 있습니다.
다음과 같이 표시됩니다.
DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1
변경하려는 구성 값을 알고 있다면 .env 파일에서 직접 수정할 수 있습니다. 설치 및 배포 중에 실행되는 대화형 프롬프트를 사용하려면 .env 파일에서 변경하려는 매개변수를 삭제하고 키트 인스턴스를 재배포하세요. 배포 중에 이러한 매개변수를 입력하라는 메시지가 표시됩니다.
예를 들어 COLLECTION_PATH=posts 줄을 삭제하고 배포하면 배포 중에 해당 줄이 표시됩니다.
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:
Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)
함수 키트 유지보수 및 업그레이드
게시자는 버그를 수정하거나, 기능을 추가하거나, 종속 항목을 업데이트하거나, 보안 취약점을 해결하기 위해 시간이 지남에 따라 npm 패키지를 업데이트할 수 있습니다. 이러한 출시 정보를 최신 상태로 유지하고 업데이트, 특히 보안 취약점을 해결하는 업데이트를 설치하는 것이 좋습니다.
functions:kits:install 명령어는 키트를 npm 패키지로 설치하고 키트의 각 인스턴스에 대해 모든 함수를 내보내는 코드베이스를 만듭니다.
키트를 업그레이드하려면 패키지 버전을 업데이트한 후 키트의 각 인스턴스를 다시 배포하여 변경사항을 적용합니다.
키트에 업데이트가 있는지 확인
function-kits/<your-kit-id>/source에서 키트의 source 디렉터리로 이동합니다. 이 source 디렉터리에서 다음 명령어를 실행하여 함수 키트와 Cloud Functions SDK를 비롯한 모든 오래된 npm 패키지에 관한 보고서를 가져옵니다.
npm outdated
업데이트해야 하는 종속 항목을 식별하는 도구(예: GitHub용 Dependabot)를 이미 사용하고 있다면 키트 디렉터리를 해당 워크플로에 통합하는 것이 좋습니다.
키트 업데이트
키트와 종속 항목을 호환성이 깨지지 않는 최신 버전(호환성이 깨지는 변경사항이 포함될 수 있는 메이저 버전 업데이트 제외)으로 업데이트하려면 다음을 실행합니다.
npm update --save
함수 키트 패키지만 업데이트하고 다른 패키지는 업데이트하지 않으려면 패키지 이름을 npm update에 전달하세요.
npm update <package-name> --save
패키지를 최신 메이저 버전 (호환성이 깨지는 변경사항이 도입될 수 있음)으로 업그레이드하려면 다음을 실행합니다.
npm update --save <npm-package-name>@latest
패키지 문서와 출시 노트를 검토하여 변경된 사항을 확인하고, 호환성이 깨지는 변경사항을 방지하기 위해 배포 전후에 추가 단계를 수행해야 하는지 확인합니다.
업데이트된 인스턴스 배포
npm update를 실행하면 로컬 소스 코드만 업데이트됩니다. 클라우드에서 실행 중인 함수를 업데이트하려면 함수를 다시 배포하세요. 다음 명령어를 실행하여 함수 키트를 포함한 프로젝트의 모든 함수를 다시 배포할 수 있습니다.
firebase deploy --only functions
마이그레이션 실행 취소
이전을 실행취소하려면 먼저 확장 프로그램을 재설치하세요. 키트의 .env 파일을 사용하여 설치 중에 필요한 구성 값을 찾을 수 있습니다.
확장 프로그램을 배포한 후 키트 인스턴스를 제거합니다 (남은 마지막 인스턴스인 경우 전체 키트가 제거됨).
firebase functions:kits:uninstall --instance <kit-instance-id> --project <project-id>
향후 마이그레이션을 위해 확장 프로그램 구성 저장
2027년 3월 31일 이후에는 기존 확장 프로그램 구성을 가져올 수 없습니다. 2027년 3월 31일 전에 이전할 수 없는 경우 이 날짜 이후에 이전하기로 결정할 경우를 대비해 확장 프로그램을 저장하는 것이 좋습니다.
확장 프로그램 인스턴스 ID 목록을 가져옵니다.
ext:listCLI 명령어를 사용하여 Firebase 프로젝트의 모든 확장 프로그램 인스턴스 목록을 가져올 수 있습니다.firebase ext:list --project <project-id>작업 예시:
firebase ext:list --project my-project» firebaselocal ext:list i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i extensions: list of extensions installed in ajp-testing: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3 │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export │ ACTIVE │ 0.3.2 │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshootingext:list명령어에는 JSON 출력 형식도 있으며, 유틸리티 jq가 설치되어 있는 경우 이를 사용하여 프로젝트의 모든 인스턴스 ID 목록을 가져올 수 있습니다.firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'작업 예시:
firebase ext:list --json --project my-project | jq -r '.result[].instanceId'출력:
firestore-bigquery-export-zbrp firestore-bigquery-export각 인스턴스의 구성을 내보냅니다.
각 인스턴스의 경우 다음 내보내기 명령어를 실행하여 디스크에 구성을 저장할 수 있습니다.
firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>작업 예시:
firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export출력:
i extensions: ensuring required API firebaseextensions.googleapis.com is enabled... i functions: Saving exported extensions config as a Function Kits .env file i functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control. i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Loaded environment variables from firestore-bigquery-export/.env.testing i functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing디스크에서
<instance-id>/.env.<project-id>과 같은 위치에 이 확장 프로그램 인스턴스의 내보내기가 표시됩니다. 이 예시에서는firestore-bigquery-export/.env.my-project에 있습니다.인스턴스당 한 번 이 프로세스를 반복할 수 있으며, 나중에 이전의 일부로 재사용할 수 있는 모든 확장 프로그램 인스턴스 구성이 포함된
.env파일 집합이 생성됩니다.내보낸
.env파일을 더 나은 위치로 이동합니다.확장에서 내보낸
.env파일이 Firebase 프로젝트에 직접 배치되었지만 함수 키트로 이전하지 않은 경우 일상적으로 필요하지 않습니다. 나중에 필요하거나 삭제하기로 결정할 때까지 프로젝트에서 적절한 다른 저장 위치로 이동할 수 있습니다.